Resources

Contacts

Individuals who serve as points of contact for the business.

Retrieve contact

GET /contacts/{contactId}
Retrieve a specific contact.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested contact.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/contacts/89
Response
application/json
{
"contactId": 1543,
"type": "manager",
"firstName": "Joe",
"middleName": "scott",
"lastName": "Bloggs",
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-4320"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "2025550104"
},
{
"type": "mobile",
"value": "0987654321"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Update contact

PUT /contacts/{contactId}
Update a specific contact.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the contact.
Request
curl --request put \
--url https://api.payroc.com/v1/contacts/89 \
--header 'Content-Type: application/json' \
--data '{"type":"manager","firstName":"David","middleName":"scott","lastName":"Simpson","identifiers":[{"type":"nationalId","value":"987-65-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}]}'

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Delete contact

DELETE /contacts/{contactId}
Delete a contact.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the contact.
Request
curl --request delete \
--url https://api.payroc.com/v1/contacts/89

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Merchant platform

Legal entity

Create merchant platform

POST /merchant-platforms
Create a merchant platform.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the merchant platform.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/merchant-platforms \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"business":{"name":"abc123","taxId":"abc123","organizationType":"privateCorporation","countryOfOperation":"US","addresses":[{"type":"legalAddress","address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"}],"contactMethods":[{"type":"email","value":"[email protected]"}]},"processingAccounts":[{"doingBusinessAs":"abc123","owners":[{"firstName":"David","middleName":"scott","lastName":"Simpson","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxx-xx-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"title":"abc123","isControlProng":false,"isAuthorizedSignatory":false}}],"website":"abc123","businessType":"retail","categoryCode":5999,"merchandiseOrServiceSold":"abc123","businessStartDate":"2020-01-01","timezone":"Pacific/Midway","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"[email protected]"}],"processing":{"transactionAmounts":{"average":89,"highest":89},"monthlyAmounts":{"average":89,"highest":89},"volumeBreakdown":{"cardPresentKeyed":47,"cardPresentSwiped":30,"mailOrTelephone":3,"ecommerce":20},"isSeasonal":false,"monthsOfOperation":["jan"],"ach":{"naics":"44-45","previouslyTerminatedForAch":false,"refunds":{"writtenRefundPolicy":false,"refundPolicyUrl":"abc123"},"estimatedMonthlyTransactions":89,"limits":{"singleTransaction":10000,"dailyDeposit":200000,"monthlyDeposit":89},"transactionTypes":["prearrangedPayment","other"],"transactionTypesOther":"anotherTransactionType"},"cardAcceptance":{"debitOnly":false,"cardsAccepted":["visa","mastercard","discover","amexOptBlue"],"specialityCards":{"americanExpressDirect":{"enabled":false,"merchantNumber":"abc123"},"electronicBenefitsTransfer":{"enabled":false,"fnsNumber":"1234567"},"other":{"wexMerchantNumber":"abc123","voyagerMerchantId":"abc123","fleetMerchantId":"abc123"}}}},"funding":{"fundingSchedule":"nextday","acceleratedFundingFee":1999,"dailyDiscount":false,"fundingAccounts":[{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}]},"pricing":{"type":"intent","pricingIntentId":89},"signature":"requestedViaEmail","contacts":[{"type":"manager","firstName":"David","middleName":"scott","lastName":"Simpson","identifiers":[{"type":"nationalId","value":"987-65-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}]}],"metadata":{"customerId":"2345"}}],"metadata":{"customerId":"2345"}}'
Response
application/json
{
"merchantPlatformId": "12346",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"business": {
"name": "Example corp",
"taxId": "xxx-xx-4321",
"organizationType": "privateCorporation",
"countryOfOperation": "US",
"addresses": [
{
"type": "legalAddress",
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "123 456 7890"
}
]
},
"processingAccounts": [
{
"processingAccountId": "38765",
"doingBusinessAs": "dba",
"status": "pending",
"link": {
"rel": "processingAccount",
"href": "https://api.payroc.com/v1/processing-accounts/38765",
"method": "get"
},
"signature": {
"type": "requestedViaDirectLink",
"link": {
"rel": "agreement",
"href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
"method": "get"
}
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Funding accounts limit reached
Funding accounts restricted. You can not have any more than two funding accounts attached to this entity
Too many control prongs
Your request included more than one owner as the control prong. You can set only one owner as the control prong.
No control prong or authorized signatory
Your request didn’t indicate which owner is the control prong or the authorized signatory. Set one owner as the control prong or the authorized signatory.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Tax ID in use
The tax ID supplied is already in use.
National ID in use
One or more supplied national IDs are not unique. All national IDs must be unique.
Api error
Unable to process your request.

List merchant platforms

GET /merchant-platforms
Retrieve a list of merchant platforms associated with your account.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of merchant platforms associated with your account.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/merchant-platforms
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/merchant-platforms?before=12345&limit=2"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/merchant-platforms?after=12346&limit=2"
}
],
"data": [
{
"merchantPlatformId": "12345",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"business": {
"name": "Example corp",
"taxId": "xxx-xx-1234",
"organizationType": "privateCorporation",
"countryOfOperation": "US",
"addresses": [
{
"type": "legalAddress",
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "123 456 7890"
}
]
},
"processingAccounts": [
{
"processingAccountId": "237654",
"doingBusinessAs": "example dba",
"status": "pending",
"link": {
"rel": "processingAccount",
"href": "https://api.payroc.com/v1/processing-accounts/237654",
"method": "get"
}
}
]
},
{
"merchantPlatformId": "12346",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"business": {
"name": "Example corp",
"taxId": "xxx-xx-4321",
"organizationType": "privateCorporation",
"countryOfOperation": "US",
"addresses": [
{
"type": "legalAddress",
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "123 456 7890"
}
]
},
"processingAccounts": [
{
"processingAccountId": "38765",
"doingBusinessAs": "dba",
"status": "pending",
"link": {
"rel": "processingAccount",
"href": "https://api.payroc.com/v1/processing-accounts/38765",
"method": "get"
}
}
]
}
]
}

Errors

ErrorDescription
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve merchant platform

GET /merchant-platforms/{merchantPlatformId}
Retrieve a specific merchant platform.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the merchant platform.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/merchant-platforms/abc123
Response
application/json
{
"merchantPlatformId": "12345",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"business": {
"name": "abc123",
"taxId": "abc123",
"organizationType": "privateCorporation",
"countryOfOperation": "US",
"addresses": [
{
"type": "legalAddress",
"address1": "1 Example Ave.",
"address2": "abc123",
"address3": "abc123",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
]
},
"processingAccounts": [
{
"processingAccountId": "12345",
"doingBusinessAs": "abc123",
"status": "entered",
"link": {
"rel": "processingAccount",
"href": "https://api.payroc.com/v1/processing-accounts/1",
"method": "get"
},
"signature": {
"type": "requestedViaDirectLink",
"link": {
"rel": "agreement",
"href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
"method": "get"
}
}
}
],
"metadata": {
"customerId": "2345"
},
"links": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Paginated list of open processing accounts of a merchant platform

GET /merchant-platforms/{merchantPlatformId}/processing-accounts
Retrieve processing accounts associated with a merchant platform.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of processing accounts associated with the merchant platform.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/merchant-platforms/abc123/processing-accounts
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts?before=12345&limit=2"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/merchant-platforms/12346/processing-accounts?after=12346&limit=2"
}
],
"data": [
{
"processingAccountId": "12345",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "approved",
"doingBusinessAs": "Example business",
"owners": [
{
"ownerId": 4563,
"firstName": "Jane",
"lastName": "Bloggs",
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/owners/4563",
"method": "get"
}
}
],
"website": "www.example.com",
"businessType": "retail",
"categoryCode": 5999,
"merchandiseOrServiceSold": "Food",
"businessStartDate": "2020-01-01",
"timezone": "America/Chicago",
"address": {
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "123 456 7890"
}
],
"processing": {
"merchantId": "444412365478965",
"transactionAmounts": {
"average": 1000,
"highest": 200000
},
"monthlyAmounts": {
"average": 1000000,
"highest": 200000000
},
"volumeBreakdown": {
"cardPresentKeyed": 47,
"cardPresentSwiped": 30,
"mailOrTelephone": 3,
"ecommerce": 20
},
"isSeasonal": true,
"monthsOfOperation": [
"jan",
"feb",
"mar",
"nov",
"dec"
],
"ach": {
"naics": "441222",
"previouslyTerminatedForAch": false,
"refunds": {
"writtenRefundPolicy": true,
"refundPolicyUrl": "http://www.example.com/refunds"
},
"estimatedMonthlyTransactions": 1000,
"limits": {
"singleTransaction": 10000000,
"dailyDeposit": 1000,
"monthlyDeposit": 2000
},
"transactionTypes": [
"telephoneInitiatedPayment",
"webInitiatedPayment"
]
},
"cardAcceptance": {
"debitOnly": false,
"cardsAccepted": [
"visa",
"mastercard"
],
"specialityCards": {
"americanExpressDirect": {
"enabled": true,
"merchantNumber": "1234567890"
},
"electronicBenefitsTransfer": {
"enabled": true,
"fnsNumber": "1234567"
},
"other": {
"wexMerchantNumber": "1234567890",
"voyagerMerchantId": "1234567890",
"fleetMerchantId": "1234567890"
}
}
}
},
"funding": {
"status": "enabled",
"fundingSchedule": "nextday",
"acceleratedFundingFee": 1999,
"fundingAccounts": [
{
"fundingAccountId": 123,
"status": "pending",
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/123"
}
}
]
},
"pricing": {
"link": {
"rel": "pricing",
"method": "get",
"href": "https://api.payroc.com/v1/processing-account/12345/pricing"
}
},
"signature": {
"type": "requestedViaEmail"
},
"contacts": [
{
"contactId": 87926,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/contacts/87926",
"method": "get"
}
}
]
},
{
"processingAccountId": "12346",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "approved",
"doingBusinessAs": "Example internet business",
"owners": [
{
"ownerId": 4564,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/owners/4564",
"method": "get"
}
}
],
"website": "www.example.com",
"businessType": "internet",
"categoryCode": 5999,
"merchandiseOrServiceSold": "Food",
"businessStartDate": "2020-01-01",
"timezone": "America/Chicago",
"address": {
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "123 456 7890"
}
],
"processing": {
"merchantId": "444412365478966",
"transactionAmounts": {
"average": 2000,
"highest": 300000
},
"monthlyAmounts": {
"average": 2000000,
"highest": 300000000
},
"volumeBreakdown": {
"cardPresentKeyed": 0,
"cardPresentSwiped": 0,
"mailOrTelephone": 0,
"ecommerce": 100
},
"isSeasonal": false
},
"funding": {
"status": "enabled",
"fundingSchedule": "nextday",
"acceleratedFundingFee": 1999,
"fundingAccounts": [
{
"fundingAccountId": 124,
"status": "pending",
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/124"
}
}
]
},
"pricing": {
"link": {
"rel": "pricing",
"method": "get",
"href": "https://api.payroc.com/v1/processing-account/12346/pricing"
}
},
"signature": {
"type": "requestedViaEmail"
},
"contacts": [
{
"contactId": 87926,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/contacts/87926",
"method": "get"
}
}
]
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Create processing account

POST /merchant-platforms/{merchantPlatformId}/processing-accounts
Create a new processing account.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the processing account.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/merchant-platforms/abc123/processing-accounts \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"doingBusinessAs":"abc123","owners":[{"firstName":"David","middleName":"scott","lastName":"Simpson","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxx-xx-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"title":"abc123","isControlProng":false,"isAuthorizedSignatory":false}}],"website":"abc123","businessType":"retail","categoryCode":5999,"merchandiseOrServiceSold":"abc123","businessStartDate":"2020-01-01","timezone":"Pacific/Midway","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"[email protected]"}],"processing":{"transactionAmounts":{"average":89,"highest":89},"monthlyAmounts":{"average":89,"highest":89},"volumeBreakdown":{"cardPresentKeyed":47,"cardPresentSwiped":30,"mailOrTelephone":3,"ecommerce":20},"isSeasonal":false,"monthsOfOperation":["jan"],"ach":{"naics":"44-45","previouslyTerminatedForAch":false,"refunds":{"writtenRefundPolicy":false,"refundPolicyUrl":"abc123"},"estimatedMonthlyTransactions":89,"limits":{"singleTransaction":10000,"dailyDeposit":200000,"monthlyDeposit":89},"transactionTypes":["prearrangedPayment","other"],"transactionTypesOther":"anotherTransactionType"},"cardAcceptance":{"debitOnly":false,"cardsAccepted":["visa","mastercard","discover","amexOptBlue"],"specialityCards":{"americanExpressDirect":{"enabled":false,"merchantNumber":"abc123"},"electronicBenefitsTransfer":{"enabled":false,"fnsNumber":"1234567"},"other":{"wexMerchantNumber":"abc123","voyagerMerchantId":"abc123","fleetMerchantId":"abc123"}}}},"funding":{"fundingSchedule":"nextday","acceleratedFundingFee":1999,"dailyDiscount":false,"fundingAccounts":[{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}]},"pricing":{"type":"intent","pricingIntentId":89},"signature":"requestedViaEmail","contacts":[{"type":"manager","firstName":"David","middleName":"scott","lastName":"Simpson","identifiers":[{"type":"nationalId","value":"987-65-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}]}],"metadata":{"customerId":"2345"}}'
Response
application/json
{
"processingAccountId": "12345",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "entered",
"doingBusinessAs": "abc123",
"owners": [
{
"ownerId": 1,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/owners/1",
"method": "get"
}
}
],
"website": "abc123",
"businessType": "retail",
"categoryCode": 5999,
"merchandiseOrServiceSold": "abc123",
"businessStartDate": "2020-01-01",
"timezone": "Pacific/Midway",
"address": {
"address1": "1 Example Ave.",
"address2": "abc123",
"address3": "abc123",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"processing": {
"merchantId": "444412365478965",
"transactionAmounts": {
"average": 89,
"highest": 89
},
"monthlyAmounts": {
"average": 89,
"highest": 89
},
"volumeBreakdown": {
"cardPresentKeyed": 47,
"cardPresentSwiped": 30,
"mailOrTelephone": 3,
"ecommerce": 20
},
"isSeasonal": false,
"monthsOfOperation": [
"jan"
],
"ach": {
"naics": "44-45",
"previouslyTerminatedForAch": false,
"refunds": {
"writtenRefundPolicy": false,
"refundPolicyUrl": "abc123"
},
"estimatedMonthlyTransactions": 89,
"limits": {
"singleTransaction": 10000,
"dailyDeposit": 200000,
"monthlyDeposit": 89
},
"transactionTypes": [
"prearrangedPayment",
"other"
],
"transactionTypesOther": "anotherTransactionType"
},
"cardAcceptance": {
"debitOnly": false,
"cardsAccepted": [
"visa",
"mastercard",
"discover",
"amexOptBlue"
],
"specialityCards": {
"americanExpressDirect": {
"enabled": false,
"merchantNumber": "abc123"
},
"electronicBenefitsTransfer": {
"enabled": false,
"fnsNumber": "1234567"
},
"other": {
"wexMerchantNumber": "abc123",
"voyagerMerchantId": "abc123",
"fleetMerchantId": "abc123"
}
}
}
},
"funding": {
"status": "enabled",
"fundingSchedule": "nextday",
"acceleratedFundingFee": 1999,
"dailyDiscount": false,
"fundingAccounts": [
{
"fundingAccountId": 123,
"status": "pending",
"link": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
}
]
},
"pricing": {
"link": {
"rel": "pricing",
"href": "https://api.payroc.com/v1/processing-account/1/pricing",
"method": "get"
}
},
"contacts": [
{
"contactId": 1,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "contact",
"href": "https://api.payroc.com/v1/contacts/1",
"method": "get"
}
}
],
"signature": {
"type": "requestedViaDirectLink",
"link": {
"rel": "agreement",
"href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
"method": "get"
}
},
"metadata": {
"customerId": "2345"
},
"links": [
{
"rel": "merchantPricingAgreement",
"href": "https://agreementexpress.com/38765",
"method": "get"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Funding accounts limit reached
Funding accounts restricted. You can not have any more than two funding accounts attached to this entity
Too many control prongs
Your request included more than one owner as the control prong. You can set only one owner as the control prong.
No control prong or authorized signatory
Your request didn’t indicate which owner is the control prong or the authorized signatory. Set one owner as the control prong or the authorized signatory.
Not Authorized
Your identity could not be verified
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Api error
Unable to process your request.

Owners

Individuals who own or control the business.

Retrieve owner

GET /owners/{ownerId}
Retrieve a specific owner.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested owner.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/owners/89
Response
application/json
{
"ownerId": 1543,
"firstName": "David",
"middleName": "scott",
"lastName": "Simpson",
"dateOfBirth": "1964-03-22",
"address": {
"address1": "1 Example Ave.",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-4320"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "2025550104"
},
{
"type": "mobile",
"value": "0987654321"
}
],
"relationship": {
"equityPercentage": 35.4,
"title": "string",
"isControlProng": true,
"isAuthorizedSignatory": false
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Update owner

PUT /owners/{ownerId}
Update a specific owner.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the owner.
Request
curl --request put \
--url https://api.payroc.com/v1/owners/89 \
--header 'Content-Type: application/json' \
--data '{"firstName":"David","middleName":"scott","lastName":"Simpson","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxx-xx-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"title":"abc123","isControlProng":false,"isAuthorizedSignatory":false}}'

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
KYC check failed
KYC check failed
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Delete owner

DELETE /owners/{ownerId}
Delete a owner.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the owner.
Request
curl --request delete \
--url https://api.payroc.com/v1/owners/89

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Pricing intents

Create and manage pricing intents.

List pricing intents

GET /pricing-intents
Retrieve a list of pricing intents.

Query parameters

Response Schema

Status Code 200

Successful response. Returns a list of pricing intents.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/pricing-intents
Response
application/json
{
"limit": 1,
"count": 1,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/pricing-intents?before=5&limit=1"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/pricing-intents?after=5&limit=1"
}
],
"data": [
{
"id": "5",
"createdDate": "2020-09-22T09:00:00.000Z",
"lastUpdatedDate": "2020-09-22T09:00:00.000Z",
"status": "active",
"key": "base",
"country": "US",
"version": "4.0",
"base": {
"addressVerification": 5,
"annualFee": {
"billInMonth": "december",
"amount": 100
},
"regulatoryAssistanceProgram": 15,
"pciNonCompliance": 4995,
"merchantAdvantage": 10,
"platinumSecurity": {
"billingFrequency": "monthly",
"amount": 1295
},
"maintenance": 500,
"minimum": 100,
"voiceAuthorization": 95,
"chargeback": 2500,
"retrieval": 1500,
"batch": 1000,
"earlyTermination": 57500
},
"processor": {
"card": {
"planType": "interchangePlus",
"fees": {
"mastercardVisaDiscover": {
"volume": 1.25,
"transaction": 5
},
"amex": {
"type": "optBlue",
"volume": 1.25,
"transaction": 10
},
"pinDebit": {
"additionalDiscount": 1.25,
"transaction": 10,
"monthlyAccess": 1200
},
"electronicBenefitsTransfer": {
"transaction": 10
},
"enhancedInterchange": {
"enrollment": 1000,
"creditToMerchant": 5.25
},
"specialityCards": {
"transaction": 10
}
}
},
"ach": {
"fees": {
"transaction": 50,
"batch": 1000,
"returns": 400,
"unauthorizedReturn": 1999,
"statement": 800,
"monthlyMinimum": 20000,
"accountVerification": 100,
"discountRateUnder10000": 5.25,
"discountRateAbove10000": 10
}
}
},
"gateway": {
"fees": {
"monthly": 1000,
"setup": 25000,
"perTransaction": 0,
"perDeviceMonthly": 0,
"additionalServiceMonthly": 0
}
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Api error
Unable to process your request.

Create pricing intent

POST /pricing-intents
Create a pricing intent.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful response. We created the pricing intent and it is waiting for approval.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/pricing-intents \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"key":"abc123","metadata":{"internalReference":"2345"},"country":"US","version":"4.0","base":{"addressVerification":5,"annualFee":{"billInMonth":"december","amount":100},"regulatoryAssistanceProgram":15,"pciNonCompliance":4995,"merchantAdvantage":10,"platinumSecurity":{"billingFrequency":"monthly"},"maintenance":500,"minimum":100,"voiceAuthorization":95,"chargeback":2500,"retrieval":1500,"batch":1500,"earlyTermination":57500},"processor":{"card":{"planType":"interchangePlus","fees":{"mastercardVisaDiscover":{"volume":1.25,"transaction":0},"amex":{"type":"optBlue","volume":1.25,"transaction":0},"pinDebit":{"additionalDiscount":1.25,"transaction":0,"monthlyAccess":0},"electronicBenefitsTransfer":{"transaction":0},"enhancedInterchange":{"enrollment":0,"creditToMerchant":1.25},"specialityCards":{"transaction":0}}},"ach":{"fees":{"transaction":50,"batch":1000,"returns":400,"unauthorizedReturn":1999,"statement":800,"monthlyMinimum":20000,"accountVerification":100,"discountRateUnder10000":1.25,"discountRateAbove10000":1.25}}},"gateway":{"fees":{"monthly":0,"setup":0,"perTransaction":0,"perDeviceMonthly":0,"additionalServiceMonthly":0}}}'
Response
application/json
{
"id": "5",
"createdDate": "2020-09-22T09:00:00.000Z",
"lastUpdatedDate": "2020-09-22T09:00:00.000Z",
"status": "active",
"key": "string",
"metadata": {
"internalReference": "2345"
},
"country": "US",
"version": "4.0",
"base": {
"addressVerification": 5,
"annualFee": {
"billInMonth": "december",
"amount": 100
},
"regulatoryAssistanceProgram": 15,
"pciNonCompliance": 4995,
"merchantAdvantage": 10,
"platinumSecurity": {
"billingFrequency": "monthly",
"amount": 1295
},
"maintenance": 500,
"minimum": 100,
"voiceAuthorization": 95,
"chargeback": 2500,
"retrieval": 1500,
"batch": 1000,
"earlyTermination": 57500
},
"processor": {
"card": {
"planType": "interchangePlus",
"fees": {
"mastercardVisaDiscover": {
"volume": 1.25,
"transaction": 5
},
"amex": {
"type": "optBlue",
"volume": 1.25,
"transaction": 10
},
"pinDebit": {
"additionalDiscount": 1.25,
"transaction": 10,
"monthlyAccess": 1200
},
"electronicBenefitsTransfer": {
"transaction": 10
},
"enhancedInterchange": {
"enrollment": 1000,
"creditToMerchant": 5.25
},
"specialityCards": {
"transaction": 10
}
}
},
"ach": {
"fees": {
"transaction": 50,
"batch": 1000,
"returns": 400,
"unauthorizedReturn": 1999,
"statement": 800,
"monthlyMinimum": 20000,
"accountVerification": 100,
"discountRateUnder10000": 5.25,
"discountRateAbove10000": 10
}
}
},
"gateway": {
"fees": {
"monthly": 1000,
"setup": 25000,
"perTransaction": 0,
"perDeviceMonthly": 0,
"additionalServiceMonthly": 0
}
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Api error
Unable to process your request.

Retrieve pricing intent

GET /pricing-intents/{pricingIntentId}
Retrieve a specific pricing intent.

Path parameters

Response Schema

Status Code 200

Successful response. Returns the requested pricing intent.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/pricing-intents/abc123
Response
application/json
{
"id": "5",
"createdDate": "2020-09-22T09:00:00.000Z",
"lastUpdatedDate": "2020-09-22T09:00:00.000Z",
"status": "active",
"key": "string",
"metadata": {
"internalReference": "2345"
},
"country": "US",
"version": "4.0",
"base": {
"addressVerification": 5,
"annualFee": {
"billInMonth": "december",
"amount": 100
},
"regulatoryAssistanceProgram": 15,
"pciNonCompliance": 4995,
"merchantAdvantage": 10,
"platinumSecurity": {
"billingFrequency": "monthly",
"amount": 1295
},
"maintenance": 500,
"minimum": 100,
"voiceAuthorization": 95,
"chargeback": 2500,
"retrieval": 1500,
"batch": 1000,
"earlyTermination": 57500
},
"processor": {
"card": {
"planType": "interchangePlus",
"fees": {
"mastercardVisaDiscover": {
"volume": 1.25,
"transaction": 5
},
"amex": {
"type": "optBlue",
"volume": 1.25,
"transaction": 10
},
"pinDebit": {
"additionalDiscount": 1.25,
"transaction": 10,
"monthlyAccess": 1200
},
"electronicBenefitsTransfer": {
"transaction": 10
},
"enhancedInterchange": {
"enrollment": 1000,
"creditToMerchant": 5.25
},
"specialityCards": {
"transaction": 10
}
}
},
"ach": {
"fees": {
"transaction": 50,
"batch": 1000,
"returns": 400,
"unauthorizedReturn": 1999,
"statement": 800,
"monthlyMinimum": 20000,
"accountVerification": 100,
"discountRateUnder10000": 5.25,
"discountRateAbove10000": 10
}
}
},
"gateway": {
"fees": {
"monthly": 1000,
"setup": 25000,
"perTransaction": 0,
"perDeviceMonthly": 0,
"additionalServiceMonthly": 0
}
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Update pricing intent

PUT /pricing-intents/{pricingIntentId}
Update a pricing intent.

Path parameters

Body parameters

Response Schema

Status Code 204

Resource successfully updated
Request
curl --request put \
--url https://api.payroc.com/v1/pricing-intents/abc123 \
--header 'Content-Type: application/json' \
--data '{"key":"abc123","metadata":{"internalReference":"2345"},"country":"US","version":"4.0","base":{"addressVerification":5,"annualFee":{"billInMonth":"december","amount":100},"regulatoryAssistanceProgram":15,"pciNonCompliance":4995,"merchantAdvantage":10,"platinumSecurity":{"billingFrequency":"monthly"},"maintenance":500,"minimum":100,"voiceAuthorization":95,"chargeback":2500,"retrieval":1500,"batch":1500,"earlyTermination":57500},"processor":{"card":{"planType":"interchangePlus","fees":{"mastercardVisaDiscover":{"volume":1.25,"transaction":0},"amex":{"type":"optBlue","volume":1.25,"transaction":0},"pinDebit":{"additionalDiscount":1.25,"transaction":0,"monthlyAccess":0},"electronicBenefitsTransfer":{"transaction":0},"enhancedInterchange":{"enrollment":0,"creditToMerchant":1.25},"specialityCards":{"transaction":0}}},"ach":{"fees":{"transaction":50,"batch":1000,"returns":400,"unauthorizedReturn":1999,"statement":800,"monthlyMinimum":20000,"accountVerification":100,"discountRateUnder10000":1.25,"discountRateAbove10000":1.25}}},"gateway":{"fees":{"monthly":0,"setup":0,"perTransaction":0,"perDeviceMonthly":0,"additionalServiceMonthly":0}}}'

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Partially update pricing intent

PATCH /pricing-intents/{pricingIntentId}
Partially update a pricing intent.

Path parameters

Header parameters

Body parameters

array of objects

Response Schema

Status Code 200

Successful request. We updated the pricing intent.
Response body
Request
curl --request patch \
--url https://api.payroc.com/v1/pricing-intents/abc123 \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '[{"op":"add","path":"/a/b/c","value":["foo","bar"]},{"op":"remove","path":"/a/b/c"},{"op":"replace","path":"/a/b/c","value":42},{"op":"move","from":"/a/b/c","path":"/a/b/d"},{"op":"copy","from":"/a/b/d","path":"/a/b/e"},{"op":"test","path":"/a/b/c","value":"foo"}]'
Response
application/json
{
"id": "5",
"createdDate": "2020-09-22T09:00:00.000Z",
"lastUpdatedDate": "2020-09-22T09:00:00.000Z",
"status": "active",
"key": "string",
"metadata": {
"internalReference": "2345"
},
"country": "US",
"version": "4.0",
"base": {
"addressVerification": 5,
"annualFee": {
"billInMonth": "december",
"amount": 100
},
"regulatoryAssistanceProgram": 15,
"pciNonCompliance": 4995,
"merchantAdvantage": 10,
"platinumSecurity": {
"billingFrequency": "monthly",
"amount": 1295
},
"maintenance": 500,
"minimum": 100,
"voiceAuthorization": 95,
"chargeback": 2500,
"retrieval": 1500,
"batch": 1000,
"earlyTermination": 57500
},
"processor": {
"card": {
"planType": "interchangePlus",
"fees": {
"mastercardVisaDiscover": {
"volume": 1.25,
"transaction": 5
},
"amex": {
"type": "optBlue",
"volume": 1.25,
"transaction": 10
},
"pinDebit": {
"additionalDiscount": 1.25,
"transaction": 10,
"monthlyAccess": 1200
},
"electronicBenefitsTransfer": {
"transaction": 10
},
"enhancedInterchange": {
"enrollment": 1000,
"creditToMerchant": 5.25
},
"specialityCards": {
"transaction": 10
}
}
},
"ach": {
"fees": {
"transaction": 50,
"batch": 1000,
"returns": 400,
"unauthorizedReturn": 1999,
"statement": 800,
"monthlyMinimum": 20000,
"accountVerification": 100,
"discountRateUnder10000": 5.25,
"discountRateAbove10000": 10
}
}
},
"gateway": {
"fees": {
"monthly": 1000,
"setup": 25000,
"perTransaction": 0,
"perDeviceMonthly": 0,
"additionalServiceMonthly": 0
}
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Delete pricing intent

DELETE /pricing-intents/{pricingIntentId}
Delete a pricing intent.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the pricing intent.
Request
curl --request delete \
--url https://api.payroc.com/v1/pricing-intents/abc123

Errors

ErrorDescription
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Processing account

Create and manage processing accounts.

Retrieve processing account

GET /processing-accounts/{processingAccountId}
Retrieve a specific processing account.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the processing account.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-accounts/abc123
Response
application/json
{
"processingAccountId": "12345",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "entered",
"doingBusinessAs": "abc123",
"owners": [
{
"ownerId": 1,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/owners/1",
"method": "get"
}
}
],
"website": "abc123",
"businessType": "retail",
"categoryCode": 5999,
"merchandiseOrServiceSold": "abc123",
"businessStartDate": "2020-01-01",
"timezone": "Pacific/Midway",
"address": {
"address1": "1 Example Ave.",
"address2": "abc123",
"address3": "abc123",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"processing": {
"merchantId": "444412365478965",
"transactionAmounts": {
"average": 89,
"highest": 89
},
"monthlyAmounts": {
"average": 89,
"highest": 89
},
"volumeBreakdown": {
"cardPresentKeyed": 47,
"cardPresentSwiped": 30,
"mailOrTelephone": 3,
"ecommerce": 20
},
"isSeasonal": false,
"monthsOfOperation": [
"jan"
],
"ach": {
"naics": "44-45",
"previouslyTerminatedForAch": false,
"refunds": {
"writtenRefundPolicy": false,
"refundPolicyUrl": "abc123"
},
"estimatedMonthlyTransactions": 89,
"limits": {
"singleTransaction": 10000,
"dailyDeposit": 200000,
"monthlyDeposit": 89
},
"transactionTypes": [
"prearrangedPayment",
"other"
],
"transactionTypesOther": "anotherTransactionType"
},
"cardAcceptance": {
"debitOnly": false,
"cardsAccepted": [
"visa",
"mastercard",
"discover",
"amexOptBlue"
],
"specialityCards": {
"americanExpressDirect": {
"enabled": false,
"merchantNumber": "abc123"
},
"electronicBenefitsTransfer": {
"enabled": false,
"fnsNumber": "1234567"
},
"other": {
"wexMerchantNumber": "abc123",
"voyagerMerchantId": "abc123",
"fleetMerchantId": "abc123"
}
}
}
},
"funding": {
"status": "enabled",
"fundingSchedule": "nextday",
"acceleratedFundingFee": 1999,
"dailyDiscount": false,
"fundingAccounts": [
{
"fundingAccountId": 123,
"status": "pending",
"link": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
}
]
},
"pricing": {
"link": {
"rel": "pricing",
"href": "https://api.payroc.com/v1/processing-account/1/pricing",
"method": "get"
}
},
"contacts": [
{
"contactId": 1,
"firstName": "Joe",
"lastName": "Bloggs",
"link": {
"rel": "contact",
"href": "https://api.payroc.com/v1/contacts/1",
"method": "get"
}
}
],
"signature": {
"type": "requestedViaDirectLink",
"link": {
"rel": "agreement",
"href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000000",
"method": "get"
}
},
"metadata": {
"customerId": "2345"
},
"links": [
{
"rel": "merchantPricingAgreement",
"href": "https://agreementexpress.com/38765",
"method": "get"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List processing account's funding accounts

GET /processing-accounts/{processingAccountId}/funding-accounts
Retrieve a list of funding accounts associated with a processing account.

Path parameters

Response Schema

Status Code 200

Successful request. Returns a list of funding accounts associated with the processing account.
Response body
array of funding accounts
Request
curl --request get \
--url https://api.payroc.com/v1/processing-accounts/abc123/funding-accounts
Response
application/json
[
{
"fundingAccountId": 123,
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "approved",
"type": "checking",
"use": "credit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****6789",
"accountNumber": "******7890"
}
}
],
"metadata": {
"internalRef": "2345"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/processing-accounts/2",
"method": "get"
}
]
},
{
"fundingAccountId": 124,
"createdDate": "2021-01-08T12:00:00.000Z",
"lastModifiedDate": "2021-01-08T12:00:00.000Z",
"status": "pending",
"type": "checking",
"use": "debit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****8725",
"accountNumber": "******3491"
}
}
],
"metadata": {
"internalRef": "2346"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/processing-accounts/2",
"method": "get"
}
]
}
]

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List contacts

GET /processing-accounts/{processingAccountId}/contacts
Retrieve a list of contacts associated with a processing account.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of contacts associated with the processing account.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-accounts/abc123/contacts
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/processing-accounts/12345/contacts?before=12345&limit=2"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/processing-accounts/12346/contacts?after=12346&limit=2"
}
],
"data": [
{
"contactId": 12345,
"type": "manager",
"firstName": "Joe",
"middleName": "Scott",
"lastName": "Bloggs",
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-1234"
}
],
"contactMethods": [
{
"type": "phone",
"value": "98765432000"
},
{
"type": "mobile",
"value": "85645787451"
},
{
"type": "email",
"value": "[email protected]"
}
]
},
{
"contactId": 12346,
"type": "representative",
"firstName": "Jane",
"middleName": "Emma",
"lastName": "Bloggs",
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-9876"
}
],
"contactMethods": [
{
"type": "phone",
"value": "98765432000"
},
{
"type": "mobile",
"value": "85645787451"
},
{
"type": "email",
"value": "[email protected]"
}
]
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Get processing account pricing agreement

GET /processing-accounts/{processingAccountId}/pricing
Retrieve a pricing agreement for a processing account.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the pricing agreement for the processing account.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-accounts/abc123/pricing
Response
application/json
{
"country": "US",
"version": "4.0",
"base": {
"addressVerification": 5,
"annualFee": {
"billInMonth": "december",
"amount": 100
},
"regulatoryAssistanceProgram": 15,
"pciNonCompliance": 4995,
"merchantAdvantage": 10,
"platinumSecurity": {
"billingFrequency": "monthly",
"amount": 1295
},
"maintenance": 500,
"minimum": 100,
"voiceAuthorization": 95,
"chargeback": 2500,
"retrieval": 1500,
"batch": 1500,
"earlyTermination": 57500
},
"processor": {
"card": {
"planType": "interchangePlus",
"fees": {
"mastercardVisaDiscover": {
"volume": 1.25,
"transaction": 0
},
"amex": {
"type": "optBlue",
"volume": 1.25,
"transaction": 0
},
"pinDebit": {
"additionalDiscount": 1.25,
"transaction": 0,
"monthlyAccess": 0
},
"electronicBenefitsTransfer": {
"transaction": 0
},
"enhancedInterchange": {
"enrollment": 0,
"creditToMerchant": 1.25
},
"specialityCards": {
"transaction": 0
}
}
},
"ach": {
"fees": {
"transaction": 50,
"batch": 1000,
"returns": 400,
"unauthorizedReturn": 1999,
"statement": 800,
"monthlyMinimum": 20000,
"accountVerification": 100,
"discountRateUnder10000": 1.25,
"discountRateAbove10000": 1.25
}
}
},
"gateway": {
"fees": {
"monthly": 0,
"setup": 0,
"perTransaction": 0,
"perDeviceMonthly": 0,
"additionalServiceMonthly": 0
}
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List owners

GET /processing-accounts/{processingAccountId}/owners
Retrieve owners associated with a processing account.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of owners associated with the processing account.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-accounts/abc123/owners
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/processing-accounts/12345/owners?before=12345&limit=2"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/processing-accounts/12346/owners?after=12346&limit=2"
}
],
"data": [
{
"ownerId": 12345,
"firstName": "Joe",
"middleName": "Scott",
"lastName": "Bloggs",
"dateOfBirth": "1964-03-22",
"address": {
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-1234"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "1234567890"
}
],
"relationship": {
"equityPercentage": 49,
"title": "CFO",
"isControlProng": false,
"isAuthorizedSignatory": false
}
},
{
"ownerId": 12346,
"firstName": "Jane",
"middleName": "Emma",
"lastName": "Bloggs",
"dateOfBirth": "1964-03-22",
"address": {
"address1": "1 Example Ave.",
"address2": "example line 2",
"address3": "example line 3",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-4321"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "1234567890"
}
],
"relationship": {
"equityPercentage": 51,
"title": "CEO",
"isControlProng": true,
"isAuthorizedSignatory": false
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Funding accounts

Financial accounts associated with entities.

List funding accounts

GET /funding-accounts
Retrieve a list of all funding accounts associated with the ISV.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of all funding accounts.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/funding-accounts
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts?before=123&limit=2"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts?after=124&limit=2"
}
],
"data": [
{
"fundingAccountId": 123,
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "approved",
"type": "checking",
"use": "credit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****6789",
"accountNumber": "******7890"
}
}
],
"metadata": {
"internalRef": "2345"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/merchants/1234",
"method": "get"
}
]
},
{
"fundingAccountId": 124,
"createdDate": "2021-01-08T12:00:00.000Z",
"lastModifiedDate": "2021-01-08T12:00:00.000Z",
"status": "pending",
"type": "checking",
"use": "debit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****8725",
"accountNumber": "******3491"
}
}
],
"metadata": {
"internalRef": "2346"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/funding-recipient/2",
"method": "get"
}
]
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Retrieve funding account

GET /funding-accounts/{fundingAccountId}
Retrieve a specific funding account.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested funding account.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/funding-accounts/89
Response
application/json
{
"fundingAccountId": 123,
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "pending",
"type": "checking",
"use": "credit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****6789",
"accountNumber": "******7890"
}
}
],
"metadata": {
"internalRef": "2345"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/merchants/1234",
"method": "get"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Update funding account

PUT /funding-accounts/{fundingAccountId}
Update a funding account.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the funding account.
Request
curl --request put \
--url https://api.payroc.com/v1/funding-accounts/89 \
--header 'Content-Type: application/json' \
--data '{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}'

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
KYC check failed
KYC check failed
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Delete funding account

DELETE /funding-accounts/{fundingAccountId}
Delete a funding account.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the funding account.
Request
curl --request delete \
--url https://api.payroc.com/v1/funding-accounts/89

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Funding activity

Activity associated with a payfac account.

Retrieve funding balance

GET /funding-balance
Retrieve the balance of funds that are available for each merchant.

Query parameters

Response Schema

Status Code 200

Successful request. Returns the balance available for each merchant.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/funding-balance
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/funding-balance?before=65&limit=2"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/funding-balance?after=66&limit=2"
}
],
"data": [
{
"merchantId": "65",
"funds": 120000,
"pending": 50050,
"available": 69950,
"currency": "USD"
},
{
"merchantId": "66",
"funds": 50000,
"pending": 0,
"available": 50000,
"currency": "USD"
}
]
}

Errors

ErrorDescription
Bad request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List funding activity

GET /funding-activity
Retrieve funding activity for a specific date range.

Query parameters

Response Schema

Status Code 200

Successful request. Returns all available funding activity for the date range.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/funding-activity?dateFrom=2022-10-01&dateTo=2022-10-01'
Response
application/json
{
"limit": 10,
"count": 10,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/funding-activity?before=11&limit=10&datefrom=2021-01-01&dateto=2021-01-30"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2021-01-01&dateto=2021-01-30"
}
],
"data": [
{
"id": "11",
"date": "2021-01-01T17:00:00.000Z",
"merchant": "Joes Hot dogs",
"description": "sales",
"type": "credit",
"amount": 20000,
"currency": "USD"
},
{
"id": "12",
"date": "2021-01-01T19:32:00.000Z",
"merchant": "Joes Hot dogs",
"description": "sales",
"type": "credit",
"amount": 50000,
"currency": "USD"
},
{
"id": "13",
"date": "2021-01-01T17:00:00.000Z",
"merchant": "Joes Hot dogs",
"recipient": "Joes Hot dogs",
"description": "payment",
"type": "debit",
"amount": 10000,
"currency": "USD"
},
{
"id": "14",
"date": "2021-01-01T17:00:00.000Z",
"merchant": "Joes Hot dogs",
"recipient": "Payroc",
"description": "Interchange Fees",
"type": "debit",
"amount": 500,
"currency": "USD"
},
{
"id": "15",
"date": "2021-01-03T09:10:00.000Z",
"merchant": "Joes Hot dogs",
"description": "sales",
"type": "credit",
"amount": 30000,
"currency": "USD"
},
{
"id": "16",
"date": "2021-01-10T17:00:00.000Z",
"merchant": "Janes shoe laces LTD",
"description": "adjustment",
"type": "credit",
"amount": 500,
"currency": "USD"
},
{
"id": "17",
"date": "2021-01-10T17:00:00.000Z",
"merchant": "Janes shoe laces LTD",
"recipient": "Payroc",
"description": "Interchange Fees",
"type": "debit",
"amount": 500,
"currency": "USD"
},
{
"id": "18",
"date": "2021-01-15T17:00:00.000Z",
"merchant": "Joes Hot dogs",
"recipient": "Payroc",
"description": "Charge back",
"type": "debit",
"amount": 1000,
"currency": "USD"
},
{
"id": "19",
"date": "2021-01-17T17:00:00.000Z",
"merchant": "Janes shoe laces LTD",
"description": "sales",
"type": "credit",
"amount": 50000,
"currency": "USD"
},
{
"id": "20",
"date": "2021-01-26T17:00:00.000Z",
"merchant": "Joes Hot dogs",
"recipient": "Mr Payfac corp",
"description": "payment",
"type": "debit",
"amount": 5000,
"currency": "USD"
}
]
}

Errors

ErrorDescription
Bad request
One or more validation errors occurred.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Funding instructions

Instructions on how to split fund between recipients.

Create Funding Instruction

POST /funding-instructions
Create funding instructions to tell us how to divide funds between your funding recipients.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We accepted the instructions.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/funding-instructions \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"merchants":[{"merchantId":"123456","recipients":[{"fundingAccountId":5432425374,"paymentMethod":"ACH","amount":{"value":12350,"currency":"USD"},"metadata":{"customerId":"2345"}}]}],"metadata":{"internalInstructionRef":"abcdef"}}'
Response
application/json
{
"instructionId": 123,
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": null,
"status": "accepted",
"merchants": [
{
"merchantId": "99999",
"recipients": [
{
"status": "accepted",
"fundingAccountId": 67890,
"paymentMethod": "ACH",
"amount": {
"value": 12350,
"currency": "USD"
},
"metadata": {
"customerId": "2345"
},
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/67890"
}
}
],
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/99999"
}
}
],
"metadata": {
"instructionRef": "abcd"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Insufficient funds
You do not have enough funds to complete the request.
Idempotency key missing
Idempotency key must be supplied
Funding accounts restricted
Funding accounts restricted.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Api error
Unable to process your request.

List funding instructions

GET /funding-instructions
Retrieve a list of funding instructions for a specific date range.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of funding instructions.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/funding-instructions?dateFrom=2022-10-01&dateTo=2022-10-01'
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/funding-instructions?before=65&limit=2&datefrom=2021-01-01&dateto=2021-01-30"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/funding-instructions?after=66&limit=2&datefrom=2021-01-01&dateto=2021-01-30"
}
],
"data": [
{
"instructionId": 65,
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"status": "completed",
"merchants": [
{
"merchantId": "99999",
"recipients": [
{
"status": "funded",
"fundingAccountId": 67890,
"paymentMethod": "ACH",
"amount": {
"value": 12350,
"currency": "USD"
},
"metadata": {
"customerId": "2345"
},
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/67890"
}
},
{
"status": "rejected",
"fundingAccountId": 67889,
"paymentMethod": "ACH",
"amount": {
"value": 9000,
"currency": "USD"
},
"metadata": {
"customerId": "2345"
},
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/67889"
}
}
],
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/99999"
}
}
],
"metadata": {
"instrcutionRef": "abcd"
},
"link": {
"rel": "fundingInstruction",
"method": "get",
"href": "https://api.payroc.com/v1/funding-instructions/65"
}
},
{
"instructionId": 66,
"createdDate": "2021-09-06T13:15:00.000Z",
"lastModifiedDate": null,
"status": "accepted",
"merchants": [
{
"merchantId": "12345",
"recipients": [
{
"status": "accepted",
"fundingAccountId": 54784,
"paymentMethod": "ACH",
"amount": {
"value": 5000,
"currency": "USD"
},
"metadata": {
"customerId": "5412"
},
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/54784"
}
}
],
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/12345"
}
},
{
"merchantId": 12346,
"recipients": [
{
"status": "accepted",
"fundingAccountId": 54784,
"paymentMethod": "ACH",
"amount": {
"value": 1000,
"currency": "USD"
},
"metadata": {
"customerId": "5412"
},
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/54784"
}
}
],
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/12346"
}
}
],
"metadata": {
"instrcutionRef": "efgh"
},
"link": {
"rel": "fundingInstruction",
"method": "get",
"href": "https://api.payroc.com/v1/funding-instructions/66"
}
}
]
}

Errors

ErrorDescription
Bad request
One or more validation errors occurred.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve funding instruction

GET /funding-instructions/{instructionId}
Retrieve a specific funding instruction.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested funding instruction.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/funding-instructions/89
Response
application/json
{
"instructionId": 12345,
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"status": "accepted",
"merchants": [
{
"merchantId": "123456",
"recipients": [
{
"fundingAccountId": 5432425374,
"paymentMethod": "ACH",
"amount": {
"value": 12350,
"currency": "USD"
},
"status": "accepted",
"metadata": {
"customerId": "2345"
},
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/5432425374"
}
}
],
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/123456"
}
}
],
"metadata": {
"internalInstructionRef": "abcdef"
}
}

Errors

ErrorDescription
Bad request
One or more validation errors occurred.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Update Funding Instruction

PUT /funding-instructions/{instructionId}
Update an existing funding instruction.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the funding instruction.
Request
curl --request put \
--url https://api.payroc.com/v1/funding-instructions/89 \
--header 'Content-Type: application/json' \
--data '{"merchants":[{"merchantId":"123456","recipients":[{"fundingAccountId":5432425374,"paymentMethod":"ACH","amount":{"value":12350,"currency":"USD"},"metadata":{"customerId":"2345"}}]}],"metadata":{"internalInstructionRef":"abcdef"}}'

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Insufficient funds
You do not have enough funds to complete the request.
Cannot be modified
Resource cannot be modified.
Bad request
One or more validation errors occurred.
Funding accounts restricted
Funding accounts restricted.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Delete Funding Instruction

DELETE /funding-instructions/{instructionId}
Delete an existing funding instruction.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the funding instruction.
Request
curl --request delete \
--url https://api.payroc.com/v1/funding-instructions/89

Errors

ErrorDescription
Cannot be modified
Resource cannot be modified.
Bad request
One or more validation errors occurred.
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Funding recipient

Entities that can receive funding but not take payments

Create funding recipient

POST /funding-recipients
Create a funding recipient.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the funding recipient.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/funding-recipients \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"recipientType":"privateCorporation","taxId":"123456789","charityId":"abc123","doingBusinessAs":"abc123","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"[email protected]"}],"metadata":{"customerId":"2345"},"owners":[{"firstName":"David","middleName":"scott","lastName":"Simpson","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxx-xx-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"title":"abc123","isControlProng":false,"isAuthorizedSignatory":false}}],"fundingAccounts":[{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}]}'
Response
application/json
{
"recipientId": 1,
"status": "approved",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"recipientType": "privateCorporation",
"taxId": "123456789",
"charityId": "abc123",
"doingBuinessAs": "abc123",
"address": {
"address1": "1 Example Ave.",
"address2": "abc123",
"address3": "abc123",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"metadata": {
"customerId": "2345"
},
"owners": [
{
"ownerId": 1,
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/owners/1",
"method": "get"
}
}
],
"fundingAccounts": [
{
"fundingAccountId": 1,
"status": "approved",
"link": {
"rel": "fundingAccount",
"herf": "https://api.payroc.com/v1/funding-accounts/1",
"method": "get"
}
},
{
"fundingAccountId": 2,
"status": "rejected",
"link": {
"rel": "fundingAccount",
"herf": "https://api.payroc.com/v1/funding-accounts/2",
"method": "get"
}
}
]
}

Errors

ErrorDescription
Idempotency key missing
Idempotency key must be supplied
Bad Request
One or more validation errors occurred
KYC check failed
KYC check failed
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Api error
Unable to process your request.

List funding recipients

GET /funding-recipients
Retrieve a list of all funding recipients associated with the ISV.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of all funding recipients.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/funding-recipients
Response
application/json
{
"limit": 10,
"count": 1,
"hasMore": false,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/funding-recipients?before=12345&limit=10"
}
],
"data": [
{
"recipientId": 12345,
"status": "approved",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"recipientType": "privateCorporation",
"taxId": "123456789",
"doingBuinessAs": "Example llc",
"address": {
"address1": "1 Example Ave.",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "phone",
"value": "123 456 7890"
}
],
"metadata": {
"customerId": 12345
},
"owners": [
{
"ownerId": 1,
"link": {
"rel": "owner",
"method": "get",
"href": "https://api.payroc.com/v1/owners/1"
}
}
],
"fundingAccounts": [
{
"fundingAccountId": 1,
"status": "approved",
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/1"
}
},
{
"fundingAccountId": 2,
"status": "hold",
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/2"
}
}
]
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Api error
Unable to process your request.

Retrieve a funding recipient

GET /funding-recipients/{recipientId}
Retrieve a specific funding recipient.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested funding recipient.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/funding-recipients/89
Response
application/json
{
"recipientId": 12345,
"status": "approved",
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"recipientType": "privateCorporation",
"taxId": "123456789",
"doingBuinessAs": "Example llc",
"address": {
"address1": "1 Example Ave.",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "phone",
"value": "123 456 7890"
}
],
"metadata": {
"customerId": 12345
},
"owners": [
{
"ownerId": 1,
"link": {
"rel": "owner",
"method": "get",
"href": "https://api.payroc.com/v1/owners/1"
}
}
],
"fundingAccounts": [
{
"fundingAccountId": 1,
"status": "approved",
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/1"
}
},
{
"fundingAccountId": 2,
"status": "hold",
"link": {
"rel": "fundingAccount",
"method": "get",
"href": "https://api.payroc.com/v1/funding-accounts/2"
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Update funding recipient

PUT /funding-recipients/{recipientId}
Update a funding recipient. If you make significant changes, we may need to approve the funding recipient again.

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the funding recipient.
Request
curl --request put \
--url https://api.payroc.com/v1/funding-recipients/89 \
--header 'Content-Type: application/json' \
--data '{"recipientType":"privateCorporation","taxId":"123456789","charityId":"abc123","doingBuinessAs":"abc123","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"[email protected]"}],"metadata":{"customerId":"2345"}}'

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
KYC check failed
KYC check failed
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Delete funding recipient

DELETE /funding-recipients/{recipientId}
Delete a funding recipient. This includes funding accounts and owners linked to the funding recipient.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the funding recipient.
Request
curl --request delete \
--url https://api.payroc.com/v1/funding-recipients/89

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

List Funding Accounts

GET /funding-recipients/{recipientId}/funding-accounts
Retrieve all funding accounts associated with the funding recipient.

Path parameters

Response Schema

Status Code 200

Successful request. Returns a list of all funding accounts associated with the funding recipient.
Response body
array of funding accounts
Request
curl --request get \
--url https://api.payroc.com/v1/funding-recipients/89/funding-accounts
Response
application/json
[
{
"fundingAccountId": 123,
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "approved",
"type": "checking",
"use": "credit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****6789",
"accountNumber": "******7890"
}
}
],
"metadata": {
"internalRef": "2345"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/funding-recipient/2",
"method": "get"
}
]
},
{
"fundingAccountId": 124,
"createdDate": "2021-01-08T12:00:00.000Z",
"lastModifiedDate": "2021-01-08T12:00:00.000Z",
"status": "pending",
"type": "checking",
"use": "debit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****8725",
"accountNumber": "******3491"
}
}
],
"metadata": {
"internalRef": "2346"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/funding-recipient/2",
"method": "get"
}
]
}
]

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Create Funding Account

POST /funding-recipients/{recipientId}/funding-accounts
Create a new funding account, and add it to the funding recipient.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the funding account and added it to the funding recipient.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/funding-recipients/89/funding-accounts \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"type":"checking","use":"credit","nameOnAccount":"Joe Bloggs","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"internalRef":"2345"}}'
Response
application/json
{
"fundingAccountId": 123,
"createdDate": "2020-09-08T12:00:00.000Z",
"lastModifiedDate": "2020-09-08T12:00:00.000Z",
"status": "approved",
"type": "checking",
"use": "credit",
"nameOnAccount": "Joe Bloggs",
"paymentMethods": [
{
"type": "ach",
"value": {
"routingNumber": "*****6789",
"accountNumber": "******7890"
}
}
],
"metadata": {
"internalRef": "2345"
},
"links": [
{
"rel": "parent",
"href": "https://api.payroc.com/v1/funding-recipient/2",
"method": "get"
}
]
}

Errors

ErrorDescription
Idempotency key missing
Idempotency key must be supplied
Bad Request
One or more validation errors occurred
KYC check failed
KYC check failed
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Api error
Unable to process your request.

List Owner

GET /funding-recipients/{recipientId}/owners
Retrieve all owners associated with the funding recipient.

Path parameters

Response Schema

Status Code 200

Successful request. Returns a list of all owners associated with the funding recipient.
Response body
array of owners
Request
curl --request get \
--url https://api.payroc.com/v1/funding-recipients/89/owners
Response
application/json
{
"ownerId": 1543,
"firstName": "David",
"middleName": "scott",
"lastName": "Simpson",
"dateOfBirth": "1964-03-22",
"address": {
"address1": "1 Example Ave.",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-4320"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
},
{
"type": "phone",
"value": "2025550104"
},
{
"type": "mobile",
"value": "0987654321"
}
],
"relationship": {
"equityPercentage": 35.4,
"title": "string",
"isControlProng": true,
"isAuthorizedSignatory": false
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Create Owner

POST /funding-recipients/{recipientId}/owners
Create a new owner, and add it to the funding recipient.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the owner and added it to the funding recipient.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/funding-recipients/89/owners \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"firstName":"David","middleName":"scott","lastName":"Simpson","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"abc123","address3":"abc123","city":"Example city","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxx-xx-4320"}],"contactMethods":[{"type":"email","value":"[email protected]"}],"relationship":{"equityPercentage":35.4,"title":"abc123","isControlProng":false,"isAuthorizedSignatory":false}}'
Response
application/json
{
"ownerId": 1543,
"firstName": "David",
"middleName": "scott",
"lastName": "Simpson",
"dateOfBirth": "1964-03-22",
"address": {
"address1": "1 Example Ave.",
"address2": "abc123",
"address3": "abc123",
"city": "Example city",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"identifiers": [
{
"type": "nationalId",
"value": "xxx-xx-4320"
}
],
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"relationship": {
"equityPercentage": 35.4,
"title": "abc123",
"isControlProng": false,
"isAuthorizedSignatory": false
}
}

Errors

ErrorDescription
Idempotency key missing
Idempotency key must be supplied
Bad Request
One or more validation errors occurred
KYC check failed
KYC check failed
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Idempotency key in use
Idempotency key in use
Api error
Unable to process your request.

Payment instructions

Submit instructions for initiating payments on physical devices running semi-integrated apps.

Submit payment instruction

POST /devices/{serialNumber}/payment-instructions
Submit an instruction request to initiate a sale on a payment device.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 202

Successful request. We accepted the payment instruction to process.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/devices/abc123/payment-instructions \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"jbloggs","processingTerminalId":"1021","order":{"orderId":"4fd4-99bc","currency":"USD","amount":1000},"customizationOptions":{"entryMethod":"deviceRead"},"autoCapture":true}'
Response
application/json
{
"paymentInstructionId": "3743a9165d134678a9100ebba3b29597",
"status": "inProgress",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/payment-instructions/3743a9165d134678a9100ebba3b29597"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Retrieve payment instruction

GET /payment-instructions/{paymentInstructionId}
Retrieve the current status of a specific payment instruction.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the current status of the requested payment instruction.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/payment-instructions/abc123
Response
application/json
{
"paymentInstructionId": "3743a9165d134678a9100ebba3b29597",
"status": "completed",
"link": {
"rel": "payment",
"method": "GET",
"href": "https://api.payroc.com/v1/payments/DD6ZDQU7L2"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Refund instructions

Submit instructions for initiating refunds on physical devices running semi-integrated apps.

Submit refund instruction

POST /devices/{serialNumber}/refund-instructions
Submit an instruction request to initiate a refund on a payment device.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 202

Successful request. We accepted the refund instruction to process.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/devices/abc123/refund-instructions \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"jbloggs","processingTerminalId":"1021","order":{"orderId":"4fd4-99bc","currency":"USD","amount":1000},"customizationOptions":{"entryMethod":"manualEntry"}}'
Response
application/json
{
"refundInstructionId": "3743a9165d134678a9100ebba3b29597",
"status": "inProgress",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/refund-instructions/3743a9165d134678a9100ebba3b29597"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Retrieve refund instruction

GET /refund-instructions/{refundInstructionId}
Retrieve the current status of a specific refund instruction.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the current status of the requested refund instruction.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/refund-instructions/abc123
Response
application/json
{
"refundInstructionId": "3743a9165d134678a9100ebba3b29597",
"status": "completed",
"link": {
"rel": "refund",
"method": "GET",
"href": "https://api.payroc.com/v1/refunds/DD6ZDQU7L2"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Bank accounts

Validate bank account information.

Verify a bank account

POST /bank-accounts/verify
Verify the customer's bank account details.

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. Returns the verification status of the customer's bank account details.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-accounts/verify \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"processingTerminalId":"1017","bankAccount":{"type":"pad","accountType":"checking","nameOnAccount":"Joe Bloggs","accountNumber":"12345678909","routingNumber":"123456789","transitNumber":"12345","institutionNumber":"123"}}'
Response
application/json
{
"processingTerminalId": "1017",
"verified": true
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Bank transfer payments

Take bank-transfer payments.

Create payment

POST /bank-transfer-payments
Run a sale with a customer's bank account details.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We processed the sale.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-transfer-payments \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"processingTerminalId":"1017","order":{"orderId":"orderpop123","description":"sample order","amount":11110,"currency":"USD","breakdown":{"subtotal":10000,"tip":{"type":"percentage","percentage":10},"taxes":[{"name":"VAT","rate":1}]}},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"[email protected]"}]},"credentialOnFile":{"tokenize":true},"paymentMethod":{"type":"ach","accountType":"checking","nameOnAccount":"Joe Bloggs","accountNumber":"11101010","routingNumber":"053200983","secCode":"web"}}'
Response
application/json
{
"paymentId": "M2MJOG6O2Y",
"processingTerminalId": "1017",
"order": {
"orderId": "orderpop123",
"dateTime": "2023-07-25T13:08:45.179Z",
"description": "sample order",
"amount": 11110,
"currency": "USD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"amount": 1010,
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 1,
"amount": 100
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****1010",
"routingNumber": "053200983",
"secureToken": {
"secureTokenId": "MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK",
"customerName": "Joe Bloggs",
"token": "2967534039611822",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK"
}
}
},
"transactionResult": {
"type": "payment",
"status": "ready",
"authorizedAmount": 11110,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List payments

GET /bank-transfer-payments
Retrieve a list of payments.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of payments.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/bank-transfer-payments?processingTerminalId=abc123'
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"paymentId": "GTNOY9O4R4",
"processingTerminalId": "1017",
"order": {
"orderId": "602",
"dateTime": "2023-05-16T15:53:18.000Z",
"description": "sample order",
"amount": 12100,
"currency": "CAD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"amount": 1100,
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 10,
"amount": 1000
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "pad",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "*******8909",
"transitNumber": "12345",
"institutionNumber": "123"
},
"transactionResult": {
"type": "payment",
"status": "ready",
"authorizedAmount": 12100,
"currency": "CAD",
"responseCode": "A"
}
},
{
"paymentId": "E29U8OU8Q4",
"processingTerminalId": "1017",
"order": {
"orderId": "541",
"dateTime": "2023-05-16T15:52:56.000Z",
"description": "test",
"amount": 12100,
"currency": "CAD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"amount": 1100,
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 10,
"amount": 1000
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "pad",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "*******8909",
"transitNumber": "12345",
"institutionNumber": "123"
},
"transactionResult": {
"type": "payment",
"status": "ready",
"authorizedAmount": 12100,
"currency": "CAD",
"responseCode": "A"
}
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/bank-transfer-payments?limit=2&processingTerminalId=1017&after=E29U8OU8Q4"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1//bank-transfer-payments?limit=2&processingTerminalId=1017&before=GTNOY9O4R4"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve payment

GET /bank-transfer-payments/{paymentId}
Retrieve a specific payment.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the specific payment.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/bank-transfer-payments/abc123
Response
application/json
{
"paymentId": "M2MJOG6O2Y",
"processingTerminalId": "1017",
"order": {
"orderId": "orderpop123",
"dateTime": "2023-07-25T13:08:45.179Z",
"description": "sample order",
"amount": 11110,
"currency": "USD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"amount": 1010,
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 1,
"amount": 100
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****1010",
"routingNumber": "053200983",
"secureToken": {
"secureTokenId": "MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK",
"customerName": "Joe Bloggs",
"token": "2967534039611822",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK"
}
}
},
"transactionResult": {
"type": "payment",
"status": "ready",
"authorizedAmount": 11110,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Reverse payment

POST /bank-transfer-payments/{paymentId}/reverse
Cancel a payment in an open batch.

Path parameters

Header parameters

Response Schema

Status Code 200

Successful request. We voided the payment.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-transfer-payments/abc123/reverse \
--header 'Idempotency-Key: abc123'
Response
application/json
{
"paymentId": "JKNIJXNZAK",
"processingTerminalId": "1017",
"order": {
"orderId": "157",
"dateTime": "2023-05-16T15:54:43.000Z",
"description": "sample order",
"amount": 12100,
"currency": "CAD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 10,
"amount": 1000
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "pad",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "*******8909",
"transitNumber": "12345",
"institutionNumber": "123"
},
"transactionResult": {
"type": "payment",
"status": "reversal",
"authorizedAmount": 12100,
"currency": "CAD",
"responseCode": "A"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Refund payment

POST /bank-transfer-payments/{paymentId}/refund
Refund a payment.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We refunded the payment.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-transfer-payments/abc123/refund \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"amount":10000,"description":"amount to refund"}'
Response
application/json
{
"paymentId": "M12F8SUHGM",
"processingTerminalId": "1017",
"order": {
"orderId": "243",
"dateTime": "2023-07-25T21:57:11.000Z",
"description": "amount to refund",
"amount": 11110,
"currency": "CAD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"amount": 1010,
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 1,
"amount": 100
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "pad",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****9031",
"transitNumber": "14574",
"institutionNumber": "644",
"secureToken": {
"secureTokenId": "MREF_465772d1-ab4e-4881-8052-5021a745ed18Df",
"customerName": "Joe Bloggs",
"token": "2967536686508441",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_465772d1-ab4e-4881-8052-5021a745ed18Df"
}
}
},
"transactionResult": {
"type": "payment",
"status": "reversal",
"authorizedAmount": 11110,
"currency": "CAD",
"responseCode": "A"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Re-present payment

POST /bank-transfer-payments/{paymentId}/represent
Re-present a customer's bank account details if the first payment was declined.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We processed the payment.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-transfer-payments/abc123/represent \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"paymentMethod":{"type":"ach","accountType":"checking","nameOnAccount":"Joe Bloggs","accountNumber":"49100130","routingNumber":"292735277","secCode":"TEL"}}'
Response
application/json
{
"paymentId": "M2MJOG6O2Y",
"processingTerminalId": "1017",
"order": {
"orderId": "orderpop123",
"dateTime": "2023-07-25T13:08:45.179Z",
"description": "sample order",
"amount": 11110,
"currency": "USD",
"breakdown": {
"subtotal": 10000,
"tip": {
"type": "percentage",
"amount": 1010,
"percentage": 10
},
"taxes": [
{
"name": "VAT",
"rate": 1,
"amount": 100
}
]
}
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****1010",
"routingNumber": "053200983",
"secureToken": {
"secureTokenId": "MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK",
"customerName": "Joe Bloggs",
"token": "2967534039611822",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_8d9b44e4-fd9c-45a7-b4b5-5e3d591dd385tK"
}
}
},
"transactionResult": {
"type": "payment",
"status": "ready",
"authorizedAmount": 11110,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Bank transfer refunds

Return payments to customers' bank accounts.

Create refund

POST /bank-transfer-refunds
Send a refund to a customer's bank account. The refund transaction is not linked to the previous transaction.
Note*: This function is available to only certain merchant accounts.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We sent the refund to the customer's bank account.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-transfer-refunds \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"processingTerminalId":"1017","order":{"orderId":314,"description":"refund example","amount":1000,"currency":"USD"},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"[email protected]"}]},"refundMethod":{"type":"ach","secCode":"web","accountType":"checking","nameOnAccount":"Joe Bloggs","accountNumber":"32183159","routingNumber":"063100277"}}'
Response
application/json
{
"refundId": "JH58KQ5K5E",
"processingTerminalId": "1017",
"order": {
"orderId": "314",
"dateTime": "2023-05-17T13:24:11.693Z",
"description": "refund example",
"amount": 50000,
"currency": "USD"
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****3159",
"routingNumber": "*****0277"
},
"transactionResult": {
"type": "unreferencedRefund",
"status": "ready",
"authorizedAmount": -50000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List refunds

GET /bank-transfer-refunds
Return a list of refund transactions.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of refund transactions.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/bank-transfer-refunds?processingTerminalId=abc123'
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"refundId": "DYDJ5KHRT4",
"processingTerminalId": "1017",
"order": {
"orderId": "304",
"dateTime": "2023-05-17T13:23:41.000Z",
"description": "refund example",
"amount": 100000,
"currency": "USD"
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****3159",
"routingNumber": "*****0277"
},
"transactionResult": {
"type": "unreferencedRefund",
"status": "ready",
"authorizedAmount": -100000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
},
{
"refundId": "B6ZOFZNVOP",
"processingTerminalId": "1017",
"order": {
"orderId": "355",
"dateTime": "2023-05-17T13:21:30.000Z",
"description": "refund example",
"amount": 12000,
"currency": "USD"
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****3159",
"routingNumber": "*****0277"
},
"transactionResult": {
"type": "unreferencedRefund",
"status": "ready",
"authorizedAmount": -12000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/bank-transfer-refunds?limit=2&processingTerminalId=1017&after=B6ZOFZNVOP"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/bank-transfer-refunds?processingTerminalId=1017&limit=2&before=DYDJ5KHRT4"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve refund

GET /bank-transfer-refunds/{refundId}
Return a specific refund transaction.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the specific refund.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/bank-transfer-refunds/abc123
Response
application/json
{
"refundId": "JH58KQ5K5E",
"processingTerminalId": "1017",
"order": {
"orderId": "314",
"dateTime": "2023-05-17T13:24:11.693Z",
"description": "refund example",
"amount": 50000,
"currency": "USD"
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****3159",
"routingNumber": "*****0277"
},
"transactionResult": {
"type": "unreferencedRefund",
"status": "ready",
"authorizedAmount": -50000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Reverse refund

POST /bank-transfer-refunds/{refundId}/reverse
Void a refund transaction.

Path parameters

Header parameters

Response Schema

Status Code 200

Successful request. We reversed the refund transaction.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/bank-transfer-refunds/abc123/reverse \
--header 'Idempotency-Key: abc123'
Response
application/json
{
"refundId": "B5FK0CBP2D",
"processingTerminalId": "1017",
"order": {
"orderId": "622",
"dateTime": "2023-05-17T13:54:51.000Z",
"description": "refund example",
"amount": 1000,
"currency": "USD"
},
"customer": {
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"bankAccount": {
"type": "ach",
"secCode": "web",
"accountType": "checking",
"nameOnAccount": "Joe Bloggs",
"accountNumber": "****3159",
"routingNumber": "*****0277"
},
"transactionResult": {
"type": "unreferencedRefund",
"status": "reversal",
"authorizedAmount": -1000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "NoError",
"processorResponseCode": "0"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Cards

Validate card information.

Verify a card

POST /cards/verify
Verify that a card is valid. For banks that do not support verification, we charge a micro deposit that we void immediately.

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. Returns the verification status of the card details.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/cards/verify \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"Mark Simpsons","processingTerminalId":"1001","card":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Joe Bloggs","cardholderSignature":"13ab","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1230"}}}}'
Response
application/json
{
"operator": "Mark Simpsons",
"processingTerminalId": "1001",
"card": {
"type": "Visa Credit",
"entryMethod": "keyed",
"cardholderName": "Joe Bloggs",
"cardholderSignature": "13ab",
"cardNumber": "453985******7062",
"expiryDate": "1230"
},
"verified": true,
"transactionResult": {
"status": "ready",
"responseCode": "A",
"responseMessage": "APPROVAL"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Balance inquiry

POST /cards/balance
Request the balance of an Electronic Benefit Transfer (EBT) card.

Body parameters

Response Schema

Status Code 200

Successful request. Returns the current balance of the EBT card.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/cards/balance \
--header 'Content-Type: application/json' \
--data '{"operator":"Mark Simpsons","processingTerminalId":"1024","currency":"USD","card":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Joe Bloggs","cardholderSignature":"12ab","keyedData":{"dataFormat":"plainText","cardNumber":"6007602801003837967","expiryDate":"1229","device":{"type":"PAX_A920_PRO","dataKsn":"FFFF5B09910001000061","firmwareVersion":"PayDroid_8.1.0_Sagittarius_V11.1.11_20200904 V1.04.02_20210617","category":"attended","serialNumber":"1850010868"}},"pinDetails":{"dataFormat":"dukpt","pin":"0123456789abcdef","pinKsn":"0002152304aad1234561"},"ebtDetails":{"benefitCategory":"cash"}}}}'
Response
application/json
{
"operator": "Mark Simpsons",
"processingTerminalId": "1024",
"card": {
"type": "Common Benefit Identification Card",
"entryMethod": "keyed",
"cardholderName": "Joe Bloggs",
"cardholderSignature": "12ab",
"cardNumber": "600760*********7967",
"expiryDate": "1229",
"balances": [
{
"benefitCategory": "cash",
"amount": 10000,
"currency": "USD"
}
]
},
"responseCode": "A",
"responseMessage": "Approved"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Lookup BIN information

POST /cards/bin-lookup
Perform a BIN (Bank Identification Number) lookup to retrieve information about a card.

Body parameters

Response Schema

Status Code 200

Successful request. Returns the BIN information.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/cards/bin-lookup \
--header 'Content-Type: application/json' \
--data '{"operator":"Andrew White","processingTerminalId":"1005","card":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Joe Bloggs","cardholderSignature":"13ab","keyedData":{"dataFormat":"plainText","cardNumber":"5001650000000000","expiryDate":"1225"}}}}'
Response
application/json
{
"type": "MASTERCARD",
"cardNumber": "500165******0000",
"country": "US",
"currency": "USD",
"debit": false
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Currency conversion

Offer dynamic currency conversion to customers.

Fx rates inquiry

POST /fx-rates
Check if a customer’s card is eligible for Dynamic Currency Conversion (DCC). If the card is eligible for DCC, offer currency conversion to the customer during a transaction.
Note: We offer this through the DCC service, which gives customers a choice to pay in the local currency or their own currency.

Body parameters

Response Schema

Status Code 200

Successful request. Returns the currency conversion rate for the transaction.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/fx-rates \
--header 'Content-Type: application/json' \
--data '{"channel":"web","operator":"Aaron","processingTerminalId":"1005","baseAmount":10000,"baseCurrency":"EUR","paymentMethod":{"type":"card","accountType":"checking","cardDetails":{"entryMethod":"keyed","cardholderName":"Joe Bloggs","keyedData":{"dataFormat":"plainText","cardNumber":"5001650000000000","expiryDate":"0430"}}}}'
Response
application/json
{
"processingTerminalId": "1005",
"operator": "Aaron",
"baseAmount": 10000,
"baseCurrency": "EUR",
"inquiryResult": {
"dccOffered": true
},
"dccOffer": {
"accepted": true,
"reference": "3396977e-40b9-4b26-8a3f-c25bc1280ee2",
"fxAmount": 13612,
"fxCurrency": "JPY",
"fxCurrencyCode": "392",
"fxCurrencyExponent": 0,
"fxRate": 136.1248,
"markup": 3,
"provider": "FEXCO",
"source": "REUTERS WHOLESALE INTERBANK"
},
"cardInfo": {
"type": "MASTERCARD",
"cardNumber": "500165******0000"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Payment plans

Create and manage payment plans.

Create payment plan

POST /processing-terminals/{processingTerminalId}/payment-plans
Create a new payment plan.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the payment plan.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/payment-plans \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"paymentPlanId":"1001_yearly_plan","name":"1001 yearly payment plan","description":"1001 yearly payment plan","currency":"EUR","setupOrder":{"amount":1010,"description":"payment plan setup order","breakdown":{"subtotal":1000,"taxes":[{"name":"VAT","rate":1}]}},"recurringOrder":{"amount":1010,"description":"payment plan setup order","breakdown":{"subtotal":1000,"taxes":[{"name":"VAT","rate":1}]}},"length":5,"type":"automatic","frequency":"yearly","onUpdate":"continue","onDelete":"complete"}'
Response
application/json
{
"paymentPlanId": "1001_yearly_plan",
"processingTerminalId": "1001",
"name": "1001 yearly payment plan",
"description": "1001 yearly payment plan",
"currency": "EUR",
"setupOrder": {
"amount": 1010,
"description": "payment plan setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "payment plan recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"length": 5,
"type": "automatic",
"frequency": "yearly",
"onUpdate": "continue",
"onDelete": "complete"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List payment plans

GET /processing-terminals/{processingTerminalId}/payment-plans
Retrieve a list of payment plans.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of payment plans.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-terminals/abc123/payment-plans
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"paymentPlanId": "1001_yearly_plan",
"processingTerminalId": "1001",
"name": "1001 yearly plan",
"description": "payment plan, setup order with taxes",
"currency": "EUR",
"length": 0,
"type": "automatic",
"frequency": "yearly",
"onUpdate": "continue",
"onDelete": "complete"
},
{
"paymentPlanId": "1001_payment_plan_premium",
"processingTerminalId": "1001",
"name": "1001 payment plan premium",
"description": "a template payment plan for premium users",
"currency": "EUR",
"length": 0,
"type": "automatic",
"frequency": "yearly",
"onUpdate": "continue",
"onDelete": "complete"
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&after=M4MY49Z5JB"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&before=GKB49GZ6DL"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve payment plan

GET /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}
Retrieve a specific payment plan.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested payment plan.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-terminals/abc123/payment-plans/abc123
Response
application/json
{
"paymentPlanId": "1001_yearly_plan",
"processingTerminalId": "1001",
"name": "1001 yearly payment plan",
"description": "1001 yearly payment plan",
"currency": "EUR",
"setupOrder": {
"amount": 1010,
"description": "payment plan setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "payment plan recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"length": 5,
"type": "automatic",
"frequency": "yearly",
"onUpdate": "continue",
"onDelete": "complete"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Update payment plan

PATCH /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}
Make changes to an existing payment plan.

Path parameters

Header parameters

Body parameters

array of objects

Response Schema

Status Code 200

Successful request. We updated the payment plan.
Response body
Request
curl --request patch \
--url https://api.payroc.com/v1/processing-terminals/abc123/payment-plans/abc123 \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '[{"op":"add","path":"/a/b/c","value":["foo","bar"]},{"op":"remove","path":"/a/b/c"},{"op":"replace","path":"/a/b/c","value":42},{"op":"move","from":"/a/b/c","path":"/a/b/d"},{"op":"copy","from":"/a/b/d","path":"/a/b/e"},{"op":"test","path":"/a/b/c","value":"foo"}]'
Response
application/json
{
"paymentPlanId": "1001_yearly_plan",
"processingTerminalId": "1001",
"name": "1001 yearly payment plan",
"description": "1001 yearly payment plan",
"currency": "EUR",
"setupOrder": {
"amount": 1010,
"description": "payment plan setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "payment plan recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"length": 5,
"type": "automatic",
"frequency": "yearly",
"onUpdate": "continue",
"onDelete": "complete"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Delete payment plan

DELETE /processing-terminals/{processingTerminalId}/payment-plans/{paymentPlanId}
Delete an existing payment plan.
Note: After you delete a payment plan, you can't reuse the paymentPlanId.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the payment plan.
Request
curl --request delete \
--url https://api.payroc.com/v1/processing-terminals/abc123/payment-plans/abc123

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Payments

Take card payments.

Create payment

POST /payments
Run a sale or pre-authorization. You can also:
  • Save the customer's payment details.
  • Set up recurring billing.
  • Process the transaction offline.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We processed the transaction.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/payments \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"channel":"web","processingTerminalId":"1023","operator":"Postman","order":{"orderId":"order123","description":"Example payment","currency":"USD","amount":100},"customer":{"firstName":"Robert","lastName":"Red","billingAddress":{"address1":"billing address1","address2":"billing address2","address3":"billing address3","city":"Los Angeles","state":"California","country":"US","postalCode":90005},"shippingAddress":{"recipientName":"shipping recipientName","address":{"address1":"shipping address1","address2":"shipping address2","address3":"shipping address3","city":"San Diego","state":"California","country":"US","postalCode":91911}}},"paymentMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"model":"paxA80","serialNumber":"WPC202833004712"},"expiryDate":"0328","cardNumber":"5001650000000000"}}}}'
Response
application/json
{
"paymentId": "KP77BIWR96",
"processingTerminalId": "1023",
"operator": "Postman",
"order": {
"orderId": "order123",
"dateTime": "2023-07-26T16:42:25.018Z",
"description": "Example payment",
"amount": 100,
"currency": "USD"
},
"customer": {
"firstName": "Robert",
"lastName": "Red",
"billingAddress": {
"address1": "billing address",
"address2": "billing address2",
"address3": "billing address3",
"city": "Los Angeles",
"state": "California",
"country": "US",
"postalCode": "90005"
},
"shippingAddress": {
"recipientName": "shipping recipientName",
"address": {
"address1": "shipping address1",
"address2": "shipping address2",
"address3": "shipping address3",
"city": "San Diego",
"state": "California",
"country": "US",
"postalCode": "91911"
}
}
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "ready",
"approvalCode": "OK3",
"authorizedAmount": 100,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK3"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List payments

GET /payments
Return a list of payments.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of payments.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/payments
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"paymentId": "IFA1T74OBS",
"processingTerminalId": "1001",
"operator": "Automatic Payment",
"order": {
"orderId": "684255528917",
"dateTime": "2023-05-16T16:45:29.000Z",
"description": "recurring order",
"amount": 100,
"currency": "EUR"
},
"card": {
"type": "Visa Credit",
"cardholderName": "Joe Bloggs",
"cardNumber": "453985******7062",
"expiryDate": "0129",
"secureToken": {
"secureTokenId": "FirefoxSecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/FirefoxSecureCard1001"
}
},
"securityChecks": {
"cvvResult": "M",
"avsResult": "X"
}
},
"supportedOperations": [
"fullyReverse",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "ready",
"approvalCode": "475318",
"authorizedAmount": 100,
"currency": "EUR",
"responseCode": "A",
"responseMessage": "APPROVAL"
}
},
{
"paymentId": "CW4BA4MUH0",
"processingTerminalId": "1001",
"operator": "Automatic Payment",
"order": {
"orderId": "684255528143",
"dateTime": "2023-05-16T16:45:28.000Z",
"description": "yearly avant-gard cinema subscription",
"amount": 1000,
"currency": "EUR"
},
"card": {
"type": "Visa Debit",
"cardholderName": "Joe Bloggs",
"cardNumber": "400006******0006",
"expiryDate": "0129",
"secureToken": {
"secureTokenId": "FirefoxSecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/FirefoxSecureCard1001"
}
},
"securityChecks": {
"cvvResult": "M",
"avsResult": "X"
}
},
"supportedOperations": [
"fullyReverse",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "ready",
"approvalCode": "475318",
"authorizedAmount": 1000,
"currency": "EUR",
"responseCode": "A",
"responseMessage": "APPROVAL"
}
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/payments?processingTerminalId=1001&limit=2&after=CW4BA4MUH0"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/payments?processingTerminalId=1001&limit=2&before=IFA1T74OBS"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve payment

GET /payments/{paymentId}
Retrieve an existing payment.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the payment.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/payments/abc123
Response
application/json
{
"paymentId": "KP77BIWR96",
"processingTerminalId": "1023",
"operator": "Postman",
"order": {
"orderId": "order123",
"dateTime": "2023-07-26T16:42:25.018Z",
"description": "Example payment",
"amount": 100,
"currency": "USD"
},
"customer": {
"firstName": "Robert",
"lastName": "Red",
"billingAddress": {
"address1": "billing address",
"address2": "billing address2",
"address3": "billing address3",
"city": "Los Angeles",
"state": "California",
"country": "US",
"postalCode": "90005"
},
"shippingAddress": {
"recipientName": "shipping recipientName",
"address": {
"address1": "shipping address1",
"address2": "shipping address2",
"address3": "shipping address3",
"city": "San Diego",
"state": "California",
"country": "US",
"postalCode": "91911"
}
}
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "ready",
"approvalCode": "OK3",
"authorizedAmount": 100,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK3"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Adjust payment

POST /payments/{paymentId}/adjust
Adjust a transaction.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We adjusted the transaction.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/payments/abc123/adjust \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"adjustments":[{"type":"customer","shippingAddress":{"recipientName":"new recipientName","address":{"address1":"new address1","address2":"address2","address3":"address3","city":"Miami","state":"Florida","country":"US","postalCode":33101}}},{"type":"order","amount":1000}]}'
Response
application/json
{
"paymentId": "HW986AQOBB",
"processingTerminalId": "1023",
"order": {
"orderId": "6u6",
"dateTime": "2023-07-27T09:28:44.000Z",
"description": "Example payment",
"amount": 1000,
"currency": "USD"
},
"customer": {
"firstName": "Robert",
"lastName": "Red",
"billingAddress": {
"address1": "billing address",
"address2": "billing address2",
"address3": "billing address3",
"city": "Los Angeles",
"state": "California",
"country": "US",
"postalCode": "90005"
},
"shippingAddress": {
"recipientName": "new recipientName",
"address": {
"address1": "new address1",
"address2": "address2",
"address3": "address3",
"city": "Miami",
"state": "Florida",
"country": "US",
"postalCode": "33101"
}
}
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "ready",
"approvalCode": "OK6",
"authorizedAmount": 1000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK6"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Capture payment

POST /payments/{paymentId}/capture
Capture an existing payment.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We captured the payment.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/payments/abc123/capture \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"processingTerminalId":"abc123","operator":"abc123","amount":89,"breakdown":{"subtotal":89,"cashbackAmount":89,"tip":{"type":"percentage","amount":0,"percentage":0},"taxes":[{"name":"abc123","rate":0}],"surcharge":{"bypass":false},"dualPricing":{"offered":false,"alternativeTender":"card"},"dutyAmount":89,"freightAmount":89,"items":[{"commodityCode":"abc123","productCode":"abc123","description":"abc123","unitOfMeasure":"ACR","unitPrice":0,"quantity":0,"discountRate":0,"taxes":[{"name":"abc123","rate":0}]}]}}'
Response
application/json
{
"paymentId": "KP77BIWR96",
"processingTerminalId": "1023",
"operator": "Postman",
"order": {
"orderId": "order123",
"dateTime": "2023-07-26T16:42:25.018Z",
"description": "Example payment",
"amount": 100,
"currency": "USD"
},
"customer": {
"firstName": "Robert",
"lastName": "Red",
"billingAddress": {
"address1": "billing address",
"address2": "billing address2",
"address3": "billing address3",
"city": "Los Angeles",
"state": "California",
"country": "US",
"postalCode": "90005"
},
"shippingAddress": {
"recipientName": "shipping recipientName",
"address": {
"address1": "shipping address1",
"address2": "shipping address2",
"address3": "shipping address3",
"city": "San Diego",
"state": "California",
"country": "US",
"postalCode": "91911"
}
}
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "ready",
"approvalCode": "OK3",
"authorizedAmount": 100,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK3"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Reverse payment

POST /payments/{paymentId}/reverse
Reverse a payment.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We reversed the payment.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/payments/abc123/reverse \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"amount":10}'
Response
application/json
{
"paymentId": "FRED4RL3GO",
"processingTerminalId": "1023",
"order": {
"orderId": "MAPI_V2_PAY_23",
"dateTime": "2023-05-18T09:29:25.000Z",
"description": "Example payment",
"amount": 100,
"currency": "USD"
},
"customer": {
"firstName": "Giuseppe",
"lastName": "Verdi",
"billingAddress": {
"address1": "example street",
"address2": "example address2",
"address3": "example address3",
"city": "example city",
"state": "California",
"country": "USA",
"postalCode": "1"
},
"shippingAddress": {
"recipientName": "shipping recipientName",
"address": {
"address1": "shipping address1",
"address2": "shipping address2",
"address3": "shipping address3",
"city": "shipping city",
"state": "shipping state",
"country": "IT",
"postalCode": "1"
}
}
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"transactionResult": {
"type": "sale",
"status": "reversal",
"approvalCode": "OK2",
"authorizedAmount": 100,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK2"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Refund payment

POST /payments/{paymentId}/refund
Refund a payment.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We refunded the payment.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/payments/abc123/refund \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"amount":100,"description":"refund - defective item"}'
Response
application/json
{
"paymentId": "JTWWI49L6U",
"processingTerminalId": "1023",
"operator": "Adam Smith",
"order": {
"orderId": "86f",
"dateTime": "2024-01-16T16:57:18.000Z",
"description": "Example payment",
"amount": 100,
"currency": "USD"
},
"customer": {
"firstName": "Robert",
"lastName": "Red",
"billingAddress": {
"address1": "billing address",
"address2": "billing address2",
"address3": "billing address3",
"city": "Los Angeles",
"state": "California",
"country": "US",
"postalCode": "90005"
},
"shippingAddress": {
"recipientName": "shipping recipientName",
"address": {
"address1": "shipping address1",
"address2": "shipping address2",
"address3": "shipping address3",
"city": "San Diego",
"state": "California",
"country": "US",
"postalCode": "91911"
}
}
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"refunds": [
{
"refundId": "BI77XQFQ05",
"dateTime": "2024-01-16T17:00:41.000Z",
"amount": -60,
"currency": "USD",
"status": "ready",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/refunds/BI77XQFQ05"
}
}
],
"supportedOperations": [
"refund"
],
"transactionResult": {
"type": "sale",
"status": "complete",
"approvalCode": "OK13",
"authorizedAmount": 100,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK13"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Refunds

Return payments to customers.

Create refund

POST /refunds
Create an unreferenced refund.

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We processed the refund.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/refunds \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"processingTerminalId":"1023","order":{"orderId":"1023_refund_oa8","description":"refund example","amount":1000,"currency":"USD"},"channel":"web","refundMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"type":"DATECS_BLUEPAD50","serialNumber":"WPC202833004712"},"expiryDate":"0328","cardNumber":"5001650000000000"}}}}'
Response
application/json
{
"refundId": "CD3HN88U9F",
"processingTerminalId": "1023",
"order": {
"orderId": "1023_refund_oa8",
"dateTime": "2023-07-27T08:51:02.910Z",
"description": "refund example",
"amount": 1000,
"currency": "USD"
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328"
},
"transactionResult": {
"type": "refund",
"status": "ready",
"approvalCode": "000000",
"authorizedAmount": -1000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK5"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List refunds

GET /refunds
Return a list of refunds.
To filter your results, use query parameters.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of refunds.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/refunds
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"refundId": "FPU8P48WN8",
"processingTerminalId": "1001",
"order": {
"orderId": "1001_refund_1",
"dateTime": "2023-05-18T15:32:47.000Z",
"description": "refund example",
"amount": 1000,
"currency": "EUR"
},
"card": {
"type": "MasterCard",
"cardNumber": "500165******0000",
"expiryDate": "0328"
},
"transactionResult": {
"type": "refund",
"status": "ready",
"approvalCode": "000000",
"authorizedAmount": -1000,
"currency": "EUR",
"responseCode": "A",
"responseMessage": "APPROVAL"
}
},
{
"refundId": "CYGDZJF0MH",
"processingTerminalId": "1001",
"order": {
"orderId": "1001_refund",
"dateTime": "2023-05-18T15:22:43.000Z",
"description": "refund example",
"amount": 1000,
"currency": "EUR"
},
"card": {
"type": "MasterCard",
"cardNumber": "500165******0000",
"expiryDate": "0328"
},
"transactionResult": {
"type": "refund",
"status": "reversal",
"approvalCode": "000000",
"authorizedAmount": -1000,
"currency": "EUR",
"responseCode": "A",
"responseMessage": "APPROVAL"
}
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/refunds?processingTerminalId=1001&limit=2&after=CYGDZJF0MH"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/refunds?processingTerminalId=1001&limit=2&before=FPU8P48WN8"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve refund

GET /refunds/{refundId}
Retrieve a specific refund.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the specific refund.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/refunds/abc123
Response
application/json
{
"refundId": "CD3HN88U9F",
"processingTerminalId": "1023",
"order": {
"orderId": "1023_refund_oa8",
"dateTime": "2023-07-27T08:51:02.910Z",
"description": "refund example",
"amount": 1000,
"currency": "USD"
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328"
},
"transactionResult": {
"type": "refund",
"status": "ready",
"approvalCode": "000000",
"authorizedAmount": -1000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK5"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Adjust refund

POST /refunds/{refundId}/adjust
Adjust an existing refund.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We updated the refund.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/refunds/abc123/adjust \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"Adam Smith","adjustments":[{"type":"customer","contactMethods":[{"type":"mobile","value":"+14155556666"}]}]}'
Response
application/json
{
"refundId": "I2HLYTVB81",
"processingTerminalId": "1023",
"operator": "Adam Smith",
"order": {
"orderId": "1023_refund_czz",
"dateTime": "2023-07-28T08:44:35.000Z",
"description": "refund example",
"amount": 1000,
"currency": "USD"
},
"customer": {
"contactMethods": [
{
"type": "mobile",
"value": "+14155556666"
}
]
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "500165******0000",
"expiryDate": "0328"
},
"transactionResult": {
"type": "refund",
"status": "ready",
"approvalCode": "000000",
"authorizedAmount": -1000,
"currency": "USD",
"responseCode": "A",
"responseMessage": "OK13"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Reverse refund

POST /refunds/{refundId}/reverse
Void an existing refund.

Path parameters

Header parameters

Response Schema

Status Code 200

Successful request. We voided the refund.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/refunds/abc123/reverse \
--header 'Idempotency-Key: abc123'
Response
application/json
{
"refundId": "IH83EP2SRN",
"processingTerminalId": "1001",
"order": {
"orderId": "1001_refund_2",
"dateTime": "2023-05-18T15:33:10.000Z",
"description": "refund example",
"amount": 1000,
"currency": "EUR"
},
"card": {
"type": "Visa Credit",
"entryMethod": "keyed",
"cardNumber": "453985******7062",
"expiryDate": "0328"
},
"transactionResult": {
"type": "refund",
"status": "reversal",
"approvalCode": "000000",
"authorizedAmount": -1000,
"currency": "EUR",
"responseCode": "A",
"responseMessage": "APPROVAL"
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Secure tokens

Save customers' payment details.

Create secure token

POST /processing-terminals/{processingTerminalId}/secure-tokens
Save the customer's payment details to use in future transactions.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created a secure token that represents your customer's payment details.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/secure-tokens \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"Adam Smith","mitAgreement":"unscheduled","customer":{"firstName":"Jessica","lastName":"Red","dateOfBirth":"1990-01-01","referenceNumber":"Customer-12","billingAddress":{"address1":"Example Street","address2":"Example address2","address3":"Example address3","city":"Fresno","state":"California","country":"US","postalCode":93650},"shippingAddress":{"recipientName":"Example shipping recipientName","address":{"address1":"Example shipping street","address2":"Example shipping address2","address3":"Exampleshipping address3","city":"Austin","state":"Texas","country":"US","postalCode":73301}},"contactMethods":[{"type":"email","value":"[email protected]"}],"notificationLanguage":"en"},"ipAddress":{"type":"ipv4","value":"124.201.101.1"},"source":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Joe Bloggs","keyedData":{"dataFormat":"plainText","cardNumber":"4001020000000009","expiryDate":"0825","cvv":"713"}}}}'
Response
application/json
{
"secureTokenId": "MREF_fce7bf52-b3b4-4270-aee9-77b938595078Hm",
"processingTerminalId": "1001",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Joe",
"lastName": "Bloggs",
"dateOfBirth": "1950-01-01",
"referenceNumber": "Customer-1",
"billingAddress": {
"address1": "Example Street",
"address2": "Example address2",
"address3": "Example address3",
"city": "Example Town",
"state": "California",
"country": "US",
"postalCode": "1234"
},
"shippingAddress": {
"recipientName": "Example shipping recipientName",
"address": {
"address1": "Example shipping street",
"address2": "Example shipping address2",
"address3": "Exampleshipping address3",
"city": "Example shipping city",
"state": "Texas",
"country": "US",
"postalCode": "1"
}
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"source": {
"type": "card",
"cardholderName": "Joe Bloggs",
"cardNumber": "400102******0009",
"expiryDate": "0825"
},
"token": "2967532489076298",
"status": "notValidated"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List secure tokens

GET /processing-terminals/{processingTerminalId}/secure-tokens
Return a list of secure tokens that are currently saved on the terminal.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of secure tokens that are currently saved on the terminal.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-terminals/abc123/secure-tokens
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"secureTokenId": "MREF_bd8abfe6-77ed-4e3b-be9f-91cb2f8801daJ2",
"processingTerminalId": "1001",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Joe",
"lastName": "Bloggs",
"dateOfBirth": "1950-01-01",
"referenceNumber": "Customer-1",
"billingAddress": {
"address1": "Example Street",
"address2": "Example address2",
"address3": "Example address3",
"city": "Example Town",
"state": "California",
"country": "US",
"postalCode": "1234"
},
"shippingAddress": {
"recipientName": "Example shipping recipientName",
"address": {
"address1": "Example shipping street",
"address2": "Example shipping address2",
"address3": "Exampleshipping address3",
"city": "Example shipping city",
"state": "Texas",
"country": "US",
"postalCode": "1"
}
}
},
"source": {
"type": "card",
"cardholderName": "Joe Bloggs",
"cardNumber": "500165******0000",
"expiryDate": "0825"
},
"token": "2967539621698111",
"status": "notValidated"
},
{
"secureTokenId": "MREF_dd8d2205-dae2-482c-b89a-2fc14513d7b7l7",
"processingTerminalId": "1001",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Joe",
"lastName": "Bloggs",
"dateOfBirth": "1990-01-01",
"referenceNumber": "Customer-12",
"billingAddress": {
"address1": "Example Street",
"address2": "Example address2",
"address3": "Example address3",
"city": "Example Town",
"state": "California",
"country": "US",
"postalCode": "1234"
},
"shippingAddress": {
"recipientName": "Example shipping recipientName",
"address": {
"address1": "Example shipping street",
"address2": "Example shipping address2",
"address3": "Exampleshipping address3",
"city": "Example shipping city",
"state": "Texas",
"country": "US",
"postalCode": "1"
}
}
},
"source": {
"type": "card",
"cardholderName": "Joe Bloggs",
"cardNumber": "400006******0006",
"expiryDate": "0825"
},
"token": "2967530499662487",
"status": "notValidated"
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens?limit=2&after=KLOLSOAKSL"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens?limit=2&before=HUAR33GOO6"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve secure token

GET /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}
Return a secure token and its related payment details.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the secure token and its related payment details.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-terminals/abc123/secure-tokens/abc123
Response
application/json
{
"secureTokenId": "MREF_fce7bf52-b3b4-4270-aee9-77b938595078Hm",
"processingTerminalId": "1001",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Joe",
"lastName": "Bloggs",
"dateOfBirth": "1950-01-01",
"referenceNumber": "Customer-1",
"billingAddress": {
"address1": "Example Street",
"address2": "Example address2",
"address3": "Example address3",
"city": "Example Town",
"state": "California",
"country": "US",
"postalCode": "1234"
},
"shippingAddress": {
"recipientName": "Example shipping recipientName",
"address": {
"address1": "Example shipping street",
"address2": "Example shipping address2",
"address3": "Exampleshipping address3",
"city": "Example shipping city",
"state": "Texas",
"country": "US",
"postalCode": "1"
}
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"source": {
"type": "card",
"cardholderName": "Joe Bloggs",
"cardNumber": "400102******0009",
"expiryDate": "0825"
},
"token": "2967532489076298",
"status": "notValidated"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Update secure token

PATCH /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}
Update the customer's payment details that are represented by the secure token.

Path parameters

Header parameters

Body parameters

array of objects

Response Schema

Status Code 200

Successful request. We updated the customer's payment details.
Response body
Request
curl --request patch \
--url https://api.payroc.com/v1/processing-terminals/abc123/secure-tokens/abc123 \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '[{"op":"add","path":"/a/b/c","value":["foo","bar"]},{"op":"remove","path":"/a/b/c"},{"op":"replace","path":"/a/b/c","value":42},{"op":"move","from":"/a/b/c","path":"/a/b/d"},{"op":"copy","from":"/a/b/d","path":"/a/b/e"},{"op":"test","path":"/a/b/c","value":"foo"}]'
Response
application/json
{
"secureTokenId": "MREF_fce7bf52-b3b4-4270-aee9-77b938595078Hm",
"processingTerminalId": "1001",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Joe",
"lastName": "Bloggs",
"dateOfBirth": "1950-01-01",
"referenceNumber": "Customer-1",
"billingAddress": {
"address1": "Example Street",
"address2": "Example address2",
"address3": "Example address3",
"city": "Example Town",
"state": "California",
"country": "US",
"postalCode": "1234"
},
"shippingAddress": {
"recipientName": "Example shipping recipientName",
"address": {
"address1": "Example shipping street",
"address2": "Example shipping address2",
"address3": "Exampleshipping address3",
"city": "Example shipping city",
"state": "Texas",
"country": "US",
"postalCode": "1"
}
},
"contactMethods": [
{
"type": "email",
"value": "[email protected]"
}
],
"notificationLanguage": "en"
},
"source": {
"type": "card",
"cardholderName": "Joe Bloggs",
"cardNumber": "400102******0009",
"expiryDate": "0825"
},
"token": "2967532489076298",
"status": "notValidated"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Delete secure token

DELETE /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}
Delete a secure token and its represented payment details.
Note: If you delete a token, you can't reuse its identifier.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the secure token.
Request
curl --request delete \
--url https://api.payroc.com/v1/processing-terminals/abc123/secure-tokens/abc123

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Api error
Unable to process your request.

Single use tokens

Create temporary single-use tokens.

Create single use token

POST /processing-terminals/{processingTerminalId}/single-use-tokens
Create a single-use token. The token expires after 30 minutes.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the single-use token.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/single-use-tokens \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"Carol Smith","paymentMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Joe Bloggs","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"0825","cvv":"713"}}}}'
Response
application/json
{
"processingTerminalId": "1005",
"token": "c96cb928e39c34bd05022cd821d2cbba2349f047ce0cef4f77cd2b5762be7608fb7c23e673bf014d58c64672928eb8256e38aa26911a22853143d22dd48ac9aa",
"expiresAt": "2023-05-18T23:17:34.844Z",
"cardInfo": {
"type": "Visa Credit",
"cardNumber": "453985******7062",
"country": "IS",
"currency": "ISK",
"debit": false
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Subscriptions

Subscribe customers to payment plans.

Create subscription

POST /processing-terminals/{processingTerminalId}/subscriptions
Create a new subscription.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the subscription.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"subscriptionId":"11001_subscription_cinema","paymentPlanId":"1001_payment_plan_yearly","paymentMethod":{"type":"secureToken","token":"2967533500670317"},"name":"subscription from postman","description":"created through postman for card token","setupOrder":{"amount":1010,"description":"setup order","breakdown":{"subtotal":1000,"taxes":[{"name":"VAT","rate":1}]},"orderId":"setup order"},"recurringOrder":{"amount":1010,"description":"recurring order","breakdown":{"subtotal":1000,"taxes":[{"name":"VAT","rate":1}]}},"startDate":"2023-07-01T00:00:00.000Z","endDate":"2025-07-01T00:00:00.000Z","length":2,"pauseCollectionFor":0}'
Response
application/json
{
"subscriptionId": "1001_subscription_cinema",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "1001_paymentplan_yearly",
"name": "yearly payment plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "avant-garde",
"description": "avant-garde cinema subscription",
"currency": "EUR",
"setupOrder": {
"orderId": "setup-order",
"amount": 1010,
"description": "setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"currentState": {
"status": "active",
"nextDueDate": "2023-04-25T00:00:00.000Z",
"paidInvoices": 0,
"outstandingInvoices": 3
},
"startDate": "2023-04-25T00:00:00.000Z",
"endDate": "2025-04-25T00:00:00.000Z",
"length": 24,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

List subscriptions

GET /processing-terminals/{processingTerminalId}/subscriptions
List subscriptions linked to a terminal.
To filter your results, use the query parameters.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of subscriptions.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"data": [
{
"subscriptionId": "subscription 6",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "5",
"name": "platinum plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/5"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "subscription 6",
"description": "this is description",
"currency": "EUR",
"setupOrder": {
"orderId": "order 201",
"amount": 1010,
"description": "payment plan setup order"
},
"recurringOrder": {
"amount": 100
},
"currentState": {
"status": "active",
"nextDueDate": "2024-04-11T00:00:00.000Z",
"paidInvoices": 1,
"outstandingInvoices": 10
},
"startDate": "2023-04-11T00:00:00.000Z",
"endDate": "2033-04-11T00:00:00.000Z",
"length": 0,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
},
{
"subscriptionId": "subscripion 5",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "1",
"name": "gold plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "subscription 5",
"description": "some description",
"currency": "EUR",
"setupOrder": {
"orderId": "order-509",
"amount": 1010
},
"recurringOrder": {
"amount": 100
},
"currentState": {
"status": "active",
"nextDueDate": "2024-04-11T00:00:00.000Z",
"paidInvoices": 1,
"outstandingInvoices": 10
},
"startDate": "2023-04-11T00:00:00.000Z",
"endDate": "2033-04-11T00:00:00.000Z",
"length": 0,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
}
],
"links": [
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/processing-terminals/1001/subscriptions?limit=2&after=LN3K88F1UH"
},
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/processing-terminals/1001/subscriptions?limit=2&before=DBDVNUL6RG"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve subscription

GET /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}
Retrieve a specific subscription.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested subscription.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions/abc123
Response
application/json
{
"subscriptionId": "1001_subscription_cinema",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "1001_paymentplan_yearly",
"name": "yearly payment plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "avant-garde",
"description": "avant-garde cinema subscription",
"currency": "EUR",
"setupOrder": {
"orderId": "setup-order",
"amount": 1010,
"description": "setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"currentState": {
"status": "active",
"nextDueDate": "2023-04-25T00:00:00.000Z",
"paidInvoices": 0,
"outstandingInvoices": 3
},
"startDate": "2023-04-25T00:00:00.000Z",
"endDate": "2025-04-25T00:00:00.000Z",
"length": 24,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Update subscription

PATCH /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}
Make changes to a subscription.

Path parameters

Header parameters

Body parameters

array of objects

Response Schema

Status Code 200

Successful request. We have updated the subscription.
Response body
Request
curl --request patch \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions/abc123 \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '[{"op":"add","path":"/a/b/c","value":["foo","bar"]},{"op":"remove","path":"/a/b/c"},{"op":"replace","path":"/a/b/c","value":42},{"op":"move","from":"/a/b/c","path":"/a/b/d"},{"op":"copy","from":"/a/b/d","path":"/a/b/e"},{"op":"test","path":"/a/b/c","value":"foo"}]'
Response
application/json
{
"subscriptionId": "1001_subscription_cinema",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "1001_paymentplan_yearly",
"name": "yearly payment plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "avant-garde",
"description": "avant-garde cinema subscription",
"currency": "EUR",
"setupOrder": {
"orderId": "setup-order",
"amount": 1010,
"description": "setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"currentState": {
"status": "active",
"nextDueDate": "2023-04-25T00:00:00.000Z",
"paidInvoices": 0,
"outstandingInvoices": 3
},
"startDate": "2023-04-25T00:00:00.000Z",
"endDate": "2025-04-25T00:00:00.000Z",
"length": 24,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Deactivate subscription

POST /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/deactivate
Deactivate a subscription.

Path parameters

Response Schema

Status Code 200

Successful request. We deactivated the subscription.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions/abc123/deactivate
Response
application/json
{
"subscriptionId": "1001_subscription_cinema",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "1001_paymentplan_yearly",
"name": "yearly payment plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "avant-garde",
"description": "avant-garde cinema subscription",
"currency": "EUR",
"setupOrder": {
"orderId": "setup-order",
"amount": 1010,
"description": "setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"currentState": {
"status": "cancelled",
"nextDueDate": "2023-04-25T00:00:00.000Z",
"paidInvoices": 0,
"outstandingInvoices": 3
},
"startDate": "2023-04-25T00:00:00.000Z",
"endDate": "2025-04-25T00:00:00.000Z",
"length": 24,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Re-activate subscription

POST /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/reactivate
Re-activate an existing subscription.

Path parameters

Response Schema

Status Code 200

Successful request. We re-activated the subscription.
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions/abc123/reactivate
Response
application/json
{
"subscriptionId": "1001_subscription_cinema",
"processingTerminalId": "1001",
"paymentPlan": {
"paymentPlanId": "1001_paymentplan_yearly",
"name": "yearly payment plan",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans/1001_paymentplan_yearly"
}
},
"secureToken": {
"secureTokenId": "SecureCard1001",
"customerName": "Joe Bloggs",
"token": "2967533500670317",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1001/secure-tokens/SecureCard1001"
}
},
"name": "avant-garde",
"description": "avant-garde cinema subscription",
"currency": "EUR",
"setupOrder": {
"orderId": "setup-order",
"amount": 1010,
"description": "setup order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"recurringOrder": {
"amount": 1010,
"description": "recurring order",
"breakdown": {
"subtotal": 1000,
"taxes": [
{
"name": "VAT",
"rate": 1
}
]
}
},
"currentState": {
"status": "active",
"nextDueDate": "2023-04-25T00:00:00.000Z",
"paidInvoices": 0,
"outstandingInvoices": 3
},
"startDate": "2023-04-25T00:00:00.000Z",
"endDate": "2025-04-25T00:00:00.000Z",
"length": 24,
"type": "automatic",
"frequency": "yearly",
"pauseCollectionFor": 0
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Pay manual subscription

POST /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}/pay
Process payment for a manual subscription.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We have processed the payment for the subscription.
Response headers
Response body
Request
curl --request post \
--url https://api.payroc.com/v1/processing-terminals/abc123/subscriptions/abc123/pay \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: abc123' \
--data '{"operator":"Giuseppe Green","order":{"amount":1010,"description":"manual payment","breakdown":{"subtotal":1000,"taxes":[{"name":"VAT","rate":1}]},"orderId":"manual payment orderx12s"}}'
Response
application/json
{
"subscriptionId": "1017_subscription_metro",
"processingTerminalId": "1017",
"payment": {
"paymentId": "GTZH5WVXK9",
"dateTime": "2023-07-27T22:36:03.506Z",
"amount": 1010,
"currency": "CAD",
"status": "ready",
"responseCode": "A",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/bank-transfer-payments/GTZH5WVXK9"
}
},
"secureToken": {
"secureTokenId": "MREF_465772d1-ab4e-4881-8052-5021a745ed18Df",
"customerName": "Joe Bloggs",
"token": "2967536686508441",
"status": "notValidated",
"link": {
"rel": "self",
"method": "GET",
"href": "https://api.payroc.com/v1/processing-terminals/1017/secure-tokens/MREF_465772d1-ab4e-4881-8052-5021a745ed18Df"
}
},
"currentState": {
"status": "active",
"nextDueDate": "2024-07-01T00:00:00.000Z",
"paidInvoices": 1,
"outstandingInvoices": 2
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Idempotency key missing
Idempotency key must be supplied
Idempotency key in use
Idempotency key in use
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Resource already exists
Resource already exists
Unsupported media type
The payload is in an unsupported format.
Api error
Unable to process your request.

Settlement

Settlement information

List batches

GET /batches
Retrieve batch data for a specific date.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of batches.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/batches?date=abc123'
Response
application/json
{
"limit": 2,
"count": 2,
"hasMore": true,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/batches?before=65&limit=2&date=2021-01-01"
},
{
"rel": "next",
"method": "get",
"href": "https://api.payroc.com/v1/batches?after=66&limit=2&&date=2021-01-01"
}
],
"data": [
{
"batchId": 65,
"date": "2021-01-01T00:00:00.000Z",
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"saleAmount": 100,
"heldAmount": 0,
"returnAmount": 0,
"transactionCount": 10,
"currency": "USD",
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joe Bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"links": [
{
"rel": "transactions",
"method": "get",
"href": "https://api.payroc.com/v1/transactions?batchId=65"
},
{
"rel": "authorizations",
"method": "get",
"href": "https://api.payroc.com/v1/authorizations?batchId=65"
}
]
},
{
"batchId": 66,
"date": "2021-01-01T00:00:00.000Z",
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"saleAmount": 76,
"heldAmount": 0,
"returnAmount": 12,
"transactionCount": 10,
"currency": "USD",
"merchant": {
"merchantId": "987654321",
"doingBusinessAs": "Joe Bloggs Shoes",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/987654321"
}
},
"links": [
{
"rel": "transactions",
"method": "get",
"href": "https://api.payroc.com/v1/transactions?batchId=66"
},
{
"rel": "authorizations",
"method": "get",
"href": "https://api.payroc.com/v1/authorizations?batchId=66"
}
]
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve batch

GET /batches/{batchId}
Retrieve a specific batch.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested batch.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/batches/89
Response
application/json
{
"batchId": 123,
"date": "2021-09-05T00:00:00.000Z",
"createdDate": "abc123",
"lastModifiedDate": "abc123",
"saleAmount": 89,
"heldAmount": 89,
"returnAmount": 89,
"transactionCount": 89,
"currency": "abc123",
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joes bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"links": [
{
"rel": "transactions",
"method": "get",
"href": "https://api.payroc.com/v1/transactions?batchId=123"
},
{
"rel": "authorizations",
"method": "get",
"href": "https://api.payroc.com/v1/authorizations?batchId=123"
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List transactions

GET /transactions
Retrieve a list of transactions.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of transactions.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/transactions?date=abc123&batchId=89'
Response
application/json
{
"limit": 2,
"count": 1,
"hasMore": false,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/transctions?before=65&limit=2&date=2021-01-01"
}
],
"data": [
{
"transactionId": 65,
"type": "capture",
"date": "2021-01-01T00:00:00.000Z",
"amount": 25000,
"entryMethod": "ecommerce",
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"status": "paid",
"cashbackAmount": 0,
"interchange": {
"basisPoint": "0,",
"transactionFee": 0
},
"currency": "USD",
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joe Bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"settled": {
"settledBy": "3rd party",
"achDate": "2021-09-05T13:15:00.000Z"
},
"batch": {
"batchId": 12,
"date": "2021-01-01T00:00:00.000Z",
"cycle": "am",
"link": {
"rel": "batch",
"method": "get",
"href": "https://api.payroc.com/v1/batches/12"
}
},
"card": {
"cardNumber": "12456**********4124",
"type": "visa",
"cvvPresenceIndicator": true,
"avsRequest": true,
"avsResponse": ""
},
"authorization": {
"authorizationId": 12345,
"code": "ABCDE",
"amount": 100,
"avsResponseCode": "",
"link": {
"rel": "authorization",
"method": "get",
"href": "https://api.payroc.com/v1/authorizations/12345"
}
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve transaction

GET /transactions/{transactionId}
Retrieve a specific transaction.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested transaction.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/transactions/89
Response
application/json
{
"transactionId": 12345,
"type": "capture",
"date": "2021-01-01T17:00:00.000Z",
"amount": 25000,
"entryMethod": "barcodeRead",
"createdDate": "abc123",
"lastModifiedDate": "abc123",
"status": "fullSuspense",
"cashbackAmount": 89,
"interchange": {
"basisPoint": 89,
"transactionFee": 89
},
"currency": "abc123",
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joes bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"settled": {
"settledBy": "abc123",
"achDate": "2021-09-05T00:00:00.000Z"
},
"batch": {
"batchId": 1234,
"date": "2021-09-05T00:00:00.000Z",
"cycle": "am",
"link": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
},
"card": {
"cardNumber": "123456**********4124",
"type": "visa",
"cvvPresenceIndicator": false,
"avsRequest": false,
"avsResponse": "abc123"
},
"authorization": {
"authorizationId": 12345,
"code": "abc123",
"amount": 89,
"avsResponseCode": "abc123",
"link": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List authorizations

GET /authorizations
Retrieve a list of authorizations.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of authorizations.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/authorizations?date=abc123&batchId=89'
Response
application/json
{
"limit": 2,
"count": 1,
"hasMore": false,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/authorizations?before=65&limit=2&date=2021-01-01"
}
],
"data": [
{
"authorizationId": 65,
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"authorizationResponse": "successful",
"preauthorizationRequestAmount": 10000,
"currency": "USD",
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joe Bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"batch": {
"batchId": 12,
"date": "2021-01-01T00:00:00.000Z",
"cycle": "am",
"link": {
"rel": "batch",
"method": "get",
"href": "https://api.payroc.com/v1/batches/12"
}
},
"card": {
"cardNumber": "12456**********4124",
"type": "visa",
"cvvPresenceIndicator": true,
"avsRequest": true,
"avsResponse": ""
},
"transaction": {
"transactionId": 12345,
"type": "capture",
"date": "",
"entryMethod": "swiped",
"amount": 100,
"link": {
"rel": "transaction",
"method": "get",
"href": "https://api.payroc.com/v1/transactions/12345"
}
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

Retrieve authorization

GET /authorizations/{authorizationId}
Retrieve a specific authorization.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested authorization.
Response body
Request
curl --request get \
--url https://api.payroc.com/v1/authorizations/89
Response
application/json
{
"authorizationId": 12345,
"createdDate": "abc123",
"lastModifiedDate": "abc123",
"authorizationResponse": "activityCountLimitExceeded",
"preauthorizationRequestAmount": 10000,
"currency": "abc123",
"batch": {
"batchId": 1234,
"date": "2021-09-05T00:00:00.000Z",
"cycle": "am",
"link": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
},
"card": {
"cardNumber": "123456**********4124",
"type": "visa",
"cvvPresenceIndicator": false,
"avsRequest": false,
"avsResponse": "abc123"
},
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joes bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"transaction": {
"transactionId": 12345,
"type": "capture",
"date": "2021-01-01T17:00:00.000Z",
"entryMethod": "barcodeRead",
"amount": 25000,
"link": {
"rel": "previous",
"method": "get",
"href": "<uri>"
}
}
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List disputes

GET /disputes
Retrieve a list of disputes.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of disputes.
Response body
Request
curl --request get \
--url 'https://api.payroc.com/v1/disputes?date=2022-10-01'
Response
application/json
{
"limit": 2,
"count": 1,
"hasMore": false,
"links": [
{
"rel": "previous",
"method": "get",
"href": "https://api.payroc.com/v1/disputes?before=65&limit=2&date=2021-01-01"
}
],
"data": [
{
"disputeId": 65,
"disputeType": "firstDispute",
"currentStatus": {
"disputeStatusId": 123,
"status": "new",
"statusDate": "",
"link": {
"rel": "statuses",
"method": "get",
"href": "https://api.payroc.com/v1/disputes/12345/statuses"
}
},
"createdDate": "2021-09-05T13:15:00.000Z",
"lastModifiedDate": "2021-09-06T18:00:00.000Z",
"receivedDate": "",
"description": "",
"referenceNumber": "35435435",
"disputeAmount": 1000,
"feeAmount": 100,
"firstdispute": true,
"authorizationCode": "574254",
"currency": "USD",
"merchant": {
"merchantId": "4525644354",
"doingBusinessAs": "Joe Bloggs pizza",
"link": {
"rel": "merchant",
"method": "get",
"href": "https://api.payroc.com/v1/merchants/4525644354"
}
},
"card": {
"cardNumber": "12456**********4124",
"type": "visa",
"cvvPresenceIndicator": true,
"avsRequest": true,
"avsResponse": ""
},
"transaction": {
"transactionId": 12345,
"type": "capture",
"date": "",
"entryMethod": "swiped",
"amount": 100,
"link": {
"rel": "transaction",
"method": "get",
"href": "https://api.payroc.com/v1/transactions/12345"
}
}
}
]
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not acceptable
Requested representation not supported
Api error
Unable to process your request.

List dispute statuses

GET /disputes/{disputeId}/statuses
Retrieve the status history for a specific dispute.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the status history for a specific dispute.
Response body
array of dispute statuss
Request
curl --request get \
--url https://api.payroc.com/v1/disputes/89/statuses
Response
application/json
[
{
"disputeStatusId": 12345,
"status": "prearbitrationInProcess",
"statusDate": "abc123"
}
]

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not Authorized
Your identity could not be verified
Forbidden
You do not have the required permission
Not found
Resource could not be found
Not acceptable
Requested representation not supported
Api error
Unable to process your request.