API explorer
/
Resources

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/1543 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "contactId": 1543,
  "type": "manager",
  "firstName": "Jane",
  "middleName": "Helen",
  "lastName": "Doe",
  "identifiers": [
    {
      "type": "nationalId",
      "value": "xxxxx4320"
    }
  ],
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    },
    {
      "type": "phone",
      "value": "2025550164"
    },
    {
      "type": "mobile",
      "value": "8445557624"
    },
    {
      "type": "fax",
      "value": "2025550110"
    }
  ]
}

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/1543 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"type":"manager","firstName":"Jane","middleName":"Helen","lastName":"Doe","identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}]}'

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/1543 \
	--header 'Authorization: Bearer <access token>'

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 platforms

A merchant platform is an entity that represents a business and includes its legal information and all processing accounts.

After you create a merchant platform for a business, you can do the following: For more information about boarding a merchant, go to our Board a merchant guide.

Create merchant platform

POST /merchant-platforms
Use this method to create the entity that represents a business, including its legal information and all its processing accounts.
Note: To add a processing account to an existing merchant platform, go to Create a processing account.
The response contains some fields that we require for other methods:
  • merchantPlatformId - Unique identifier that we assign to the merchant platform. Use the merchantPlatformId to retrieve and update information about the merchant platform.
  • processingAccountId- Unique identifier that we assign to each processing account. Use the processingAccountId to retrieve and update information about the processing account.
For more information about how to create a merchant platform, go to 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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"business":{"name":"Example Corp","taxId":"12-3456789","organizationType":"privateCorporation","countryOfOperation":"US","addresses":[{"type":"legalAddress","address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}]},"processingAccounts":[{"doingBusinessAs":"Pizza Doe","owners":[{"firstName":"Jane","middleName":"Helen","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"relationship":{"equityPercentage":48.5,"title":"CFO","isControlProng":true,"isAuthorizedSignatory":false}}],"website":"www.example.com","businessType":"restaurant","categoryCode":5999,"merchandiseOrServiceSold":"Pizza","businessStartDate":"2020-01-01","timezone":"America/Chicago","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"processing":{"transactionAmounts":{"average":5000,"highest":10000},"monthlyAmounts":{"average":50000,"highest":100000},"volumeBreakdown":{"cardPresentKeyed":47,"cardPresentSwiped":30,"mailOrTelephone":3,"ecommerce":20},"isSeasonal":true,"monthsOfOperation":["jan","feb"],"ach":{"naics":"5812","previouslyTerminatedForAch":false,"refunds":{"writtenRefundPolicy":true,"refundPolicyUrl":"www.example.com/refund-poilcy-url"},"estimatedMonthlyTransactions":3000,"limits":{"singleTransaction":10000,"dailyDeposit":200000,"monthlyDeposit":6000000},"transactionTypes":["prearrangedPayment","other"],"transactionTypesOther":"anotherTransactionType"},"cardAcceptance":{"debitOnly":false,"hsaFsa":false,"cardsAccepted":["visa","mastercard"],"specialityCards":{"americanExpressDirect":{"enabled":true,"merchantNumber":"abc1234567"},"electronicBenefitsTransfer":{"enabled":true,"fnsNumber":"6789012"},"other":{"wexMerchantNumber":"abc1234567","voyagerMerchantId":"abc1234567","fleetMerchantId":"abc1234567"}}}},"funding":{"fundingSchedule":"nextday","acceleratedFundingFee":1999,"dailyDiscount":false,"fundingAccounts":[{"type":"checking","use":"creditAndDebit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"yourCustomField":"abc123"}}]},"pricing":{"type":"intent","pricingIntentId":6123},"signature":"requestedViaDirectLink","contacts":[{"type":"manager","firstName":"Jane","middleName":"Helen","lastName":"Doe","identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}]}],"metadata":{"customerId":"2345"}}],"metadata":{"customerId":"2345"}}'
Response
application/json
{
  "merchantPlatformId": "12345",
  "createdDate": "2024-07-02T12:00:00.000Z",
  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
  "business": {
    "name": "Example Corp",
    "taxId": "xxxxx6789",
    "organizationType": "privateCorporation",
    "countryOfOperation": "US",
    "addresses": [
      {
        "type": "legalAddress",
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    ],
    "contactMethods": [
      {
        "type": "email",
        "value": "jane.doe@example.com"
      }
    ]
  },
  "processingAccounts": [
    {
      "processingAccountId": "38765",
      "doingBusinessAs": "Pizza Doe",
      "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.
Cannot select Daily Discount and RewardPayChoice at the same time.
You can't select Daily Discount with a RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan.
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
Use this method to retrieve a paginated list of the merchant platforms that are linked to the ISV's account.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of merchant platforms associated with the ISV's account.
Response body
Request
curl --request get \
	--url https://api.payroc.com/v1/merchant-platforms \
	--header 'Authorization: Bearer <access token>'
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": "2024-07-02T12:00:00.000Z",
      "lastModifiedDate": "2024-07-02T12:00:00.000Z",
      "business": {
        "name": "Example Corp",
        "taxId": "xxxxx6789",
        "organizationType": "privateCorporation",
        "countryOfOperation": "US",
        "addresses": [
          {
            "type": "legalAddress",
            "address1": "1 Example Ave.",
            "address2": "Example Address Line 2",
            "address3": "Example Address Line 3",
            "city": "Chicago",
            "state": "Illinois",
            "country": "US",
            "postalCode": "60056"
          }
        ],
        "contactMethods": [
          {
            "type": "email",
            "value": "example-corp@example.com"
          },
          {
            "type": "phone",
            "value": "123 456 7890"
          }
        ]
      },
      "processingAccounts": [
        {
          "processingAccountId": "38765",
          "doingBusinessAs": "Pizza Doe",
          "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"
            }
          }
        }
      ]
    },
    {
      "merchantPlatformId": "12346",
      "createdDate": "2024-07-02T12:00:00.000Z",
      "lastModifiedDate": "2024-07-02T12:00:00.000Z",
      "business": {
        "name": "Example Corp",
        "taxId": "xxxxx6789",
        "organizationType": "privateCorporation",
        "countryOfOperation": "US",
        "addresses": [
          {
            "type": "legalAddress",
            "address1": "1 Example Ave.",
            "address2": "Example Address Line 2",
            "address3": "Example Address Line 3",
            "city": "Chicago",
            "state": "Illinois",
            "country": "US",
            "postalCode": "60056"
          }
        ],
        "contactMethods": [
          {
            "type": "email",
            "value": "example-corp@example.com"
          },
          {
            "type": "phone",
            "value": "123 456 7890"
          }
        ]
      },
      "processingAccounts": [
        {
          "processingAccountId": "38766",
          "doingBusinessAs": "Doe Hot Dogs",
          "status": "pending",
          "link": {
            "rel": "processingAccount",
            "href": "https://api.payroc.com/v1/processing-accounts/38766",
            "method": "get"
          },
          "signature": {
            "type": "requestedViaDirectLink",
            "link": {
              "rel": "agreement",
              "href": "https://us.agreementexpress.net/mv2/viewer2.jsp?docId=00000000-0000-0000-0000-000000000001",
              "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}
Use this method to retrieve information about a merchant platform, including its legal information and processing accounts. Include the merchantPlatformId that we sent you when you created the 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/12345 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "merchantPlatformId": "12345",
  "createdDate": "2024-07-02T12:00:00.000Z",
  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
  "business": {
    "name": "Example Corp",
    "taxId": "xxxxx6789",
    "organizationType": "privateCorporation",
    "countryOfOperation": "US",
    "addresses": [
      {
        "type": "legalAddress",
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    ],
    "contactMethods": [
      {
        "type": "email",
        "value": "jane.doe@example.com"
      }
    ]
  },
  "processingAccounts": [
    {
      "processingAccountId": "38765",
      "doingBusinessAs": "Pizza Doe",
      "status": "approved",
      "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"
        }
      }
    }
  ],
  "metadata": {
    "customerId": "2345"
  },
  "links": []
}

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 merchant platform's processing accounts

GET /merchant-platforms/{merchantPlatformId}/processing-accounts
Use this method to retrieve a paginated list of processing accounts associated with a merchant platform. When you created the merchant platform, we sent you its merchantPlatformId in the response. Send this merchantPlatformId as a path parameter in your endpoint.
Note: By default, we return only open processing accounts. To include closed processing accounts, send a value of true for the includeClosed query parameter.

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/12345/processing-accounts \
	--header 'Authorization: Bearer <access token>'
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=38765&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/merchant-platforms/12345/processing-accounts?after=38766&limit=2"
    }
  ],
  "data": [
    {
      "processingAccountId": "38765",
      "createdDate": "2024-07-02T12:00:00.000Z",
      "lastModifiedDate": "2024-07-02T12:00:00.000Z",
      "status": "approved",
      "doingBusinessAs": "Pizza Doe",
      "owners": [
        {
          "ownerId": 4564,
          "firstName": "Jane",
          "lastName": "Doe",
          "link": {
            "rel": "owner",
            "href": "https://api.payroc.com/v1/owners/4564",
            "method": "get"
          }
        }
      ],
      "website": "www.example.com",
      "businessType": "restaurant",
      "categoryCode": 5999,
      "merchandiseOrServiceSold": "Food",
      "businessStartDate": "2020-01-01",
      "timezone": "America/Chicago",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "contactMethods": [
        {
          "type": "email",
          "value": "example-corp@example.com"
        },
        {
          "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": "5812",
          "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,
          "hsaFsa": 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": 1543,
          "firstName": "Jane",
          "lastName": "Doe",
          "link": {
            "rel": "owner",
            "href": "https://api.payroc.com/v1/contacts/1543",
            "method": "get"
          }
        }
      ]
    },
    {
      "processingAccountId": "38766",
      "createdDate": "2024-07-02T12:00:00.000Z",
      "lastModifiedDate": "2024-07-02T12:00:00.000Z",
      "status": "approved",
      "doingBusinessAs": "Doe Hot Dogs",
      "owners": [
        {
          "ownerId": 4564,
          "firstName": "Jane",
          "lastName": "Doe",
          "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": "3 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "contactMethods": [
        {
          "type": "email",
          "value": "jane.doe@example.com"
        },
        {
          "type": "phone",
          "value": "555 555 3456"
        }
      ],
      "processing": {
        "merchantId": "444412365478966",
        "transactionAmounts": {
          "average": 2000,
          "highest": 300000
        },
        "monthlyAmounts": {
          "average": 2000000,
          "highest": 300000000
        },
        "volumeBreakdown": {
          "cardPresentKeyed": 0,
          "cardPresentSwiped": 0,
          "mailOrTelephone": 0,
          "ecommerce": 100
        },
        "isSeasonal": true
      },
      "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": 1543,
          "firstName": "Jane",
          "lastName": "Doe",
          "link": {
            "rel": "owner",
            "href": "https://api.payroc.com/v1/contacts/1543",
            "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
Use this method to create a processing account and add it to a merchant platform.
Note: You can create and add a processing account only to an existing merchant platform. If you have not already created a merchant platform, go to Create a merchant platform.
In the response we return a processingAccountId for the processing account, which you need for the following methods.

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/12345/processing-accounts \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"doingBusinessAs":"Pizza Doe","owners":[{"firstName":"Jane","middleName":"Helen","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"relationship":{"equityPercentage":51.5,"title":"CFO","isControlProng":true,"isAuthorizedSignatory":false}}],"website":"www.example.com","businessType":"restaurant","categoryCode":5999,"merchandiseOrServiceSold":"Pizza","businessStartDate":"2020-01-01","timezone":"America/Chicago","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"processing":{"transactionAmounts":{"average":5000,"highest":10000},"monthlyAmounts":{"average":50000,"highest":100000},"volumeBreakdown":{"cardPresentKeyed":47,"cardPresentSwiped":30,"mailOrTelephone":3,"ecommerce":20},"isSeasonal":true,"monthsOfOperation":["jan","feb"],"ach":{"naics":"5812","previouslyTerminatedForAch":false,"refunds":{"writtenRefundPolicy":true,"refundPolicyUrl":"www.example.com/refund-poilcy-url"},"estimatedMonthlyTransactions":3000,"limits":{"singleTransaction":10000,"dailyDeposit":200000,"monthlyDeposit":6000000},"transactionTypes":["prearrangedPayment","other"],"transactionTypesOther":"anotherTransactionType"},"cardAcceptance":{"debitOnly":false,"hsaFsa":false,"cardsAccepted":["visa","mastercard"],"specialityCards":{"americanExpressDirect":{"enabled":true,"merchantNumber":"abc1234567"},"electronicBenefitsTransfer":{"enabled":true,"fnsNumber":"6789012"},"other":{"wexMerchantNumber":"abc1234567","voyagerMerchantId":"abc1234567","fleetMerchantId":"abc1234567"}}}},"funding":{"fundingSchedule":"nextday","acceleratedFundingFee":1999,"dailyDiscount":false,"fundingAccounts":[{"type":"checking","use":"creditAndDebit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"yourCustomField":"abc123"}}]},"pricing":{"type":"intent","pricingIntentId":6123},"signature":"requestedViaDirectLink","contacts":[{"type":"manager","firstName":"Jane","middleName":"Helen","lastName":"Doe","identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}]}],"metadata":{"customerId":"2345"}}'
Response
application/json
{
  "processingAccountId": "38765",
  "createdDate": "2024-07-02T12:00:00.000Z",
  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
  "status": "entered",
  "doingBusinessAs": "Pizza Doe",
  "owners": [
    {
      "ownerId": 4564,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "owner",
        "href": "https://api.payroc.com/v1/owners/4564",
        "method": "get"
      }
    }
  ],
  "website": "www.example.com",
  "businessType": "restaurant",
  "categoryCode": 5999,
  "merchandiseOrServiceSold": "Pizza",
  "businessStartDate": "2020-01-01",
  "timezone": "America/Chicago",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    }
  ],
  "processing": {
    "transactionAmounts": {
      "average": 5000,
      "highest": 10000
    },
    "monthlyAmounts": {
      "average": 50000,
      "highest": 100000
    },
    "volumeBreakdown": {
      "cardPresentKeyed": 47,
      "cardPresentSwiped": 30,
      "mailOrTelephone": 3,
      "ecommerce": 20
    },
    "isSeasonal": true,
    "monthsOfOperation": [
      "jan",
      "feb"
    ],
    "ach": {
      "naics": "5812",
      "previouslyTerminatedForAch": false,
      "refunds": {
        "writtenRefundPolicy": true,
        "refundPolicyUrl": "www.example.com/refund-poilcy-url"
      },
      "estimatedMonthlyTransactions": 3000,
      "limits": {
        "singleTransaction": 10000,
        "dailyDeposit": 200000,
        "monthlyDeposit": 6000000
      },
      "transactionTypes": [
        "prearrangedPayment",
        "other"
      ],
      "transactionTypesOther": "anotherTransactionType"
    },
    "cardAcceptance": {
      "debitOnly": false,
      "hsaFsa": false,
      "cardsAccepted": [
        "visa",
        "mastercard"
      ],
      "specialityCards": {
        "americanExpressDirect": {
          "enabled": true,
          "merchantNumber": "abc1234567"
        },
        "electronicBenefitsTransfer": {
          "enabled": true,
          "fnsNumber": "6789012"
        },
        "other": {
          "wexMerchantNumber": "abc1234567",
          "voyagerMerchantId": "abc1234567",
          "fleetMerchantId": "abc1234567"
        }
      }
    }
  },
  "funding": {
    "status": "enabled",
    "fundingSchedule": "nextday",
    "acceleratedFundingFee": 1999,
    "dailyDiscount": false,
    "fundingAccounts": [
      {
        "fundingAccountId": 123,
        "status": "pending",
        "link": {
          "rel": "fundingAccount",
          "method": "get",
          "href": "https://api.payroc.com/v1/funding-account/123"
        }
      }
    ]
  },
  "pricing": {
    "link": {
      "rel": "pricing",
      "href": "https://api.payroc.com/v1/processing-account/12345/pricing",
      "method": "get"
    }
  },
  "contacts": [
    {
      "contactId": 1543,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "contact",
        "href": "https://api.payroc.com/v1/contacts/1543",
        "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"
  }
}

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.
Cannot select Daily Discount and RewardPayChoice at the same time.
You can't select Daily Discount with a RewardPayChoice pricing plan. To select Daily Discount, choose a different pricing plan.
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/4564 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "ownerId": 4564,
  "firstName": "Jane",
  "middleName": "Helen",
  "lastName": "Doe",
  "dateOfBirth": "1964-03-22",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "identifiers": [
    {
      "type": "nationalId",
      "value": "xxxxx4320"
    }
  ],
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    }
  ],
  "relationship": {
    "equityPercentage": 48.5,
    "title": "CFO",
    "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/4564 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"firstName":"Jane","middleName":"Helen","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"relationship":{"equityPercentage":48.5,"title":"CFO","isControlProng":true,"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/4564 \
	--header 'Authorization: Bearer <access token>'

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 \
	--header 'Authorization: Bearer <access token>'
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": "2024-07-02T09:00:00",
      "lastUpdatedDate": "2024-07-02T09:00:00",
      "status": "pendingReview",
      "key": "base",
      "country": "US",
      "version": "5.0",
      "base": {
        "addressVerification": 5,
        "annualFee": {
          "billInMonth": "june",
          "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
        }
      },
      "services": [
        {
          "name": "hardwareAdvantagePlan",
          "enabled": true
        }
      ]
    }
  ]
}

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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"key":"Your-Unique-Identifier","metadata":{"yourCustomField":"abc123"},"country":"US","version":"5.0","base":{"addressVerification":5,"annualFee":{"billInMonth":"june","amount":9900},"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":0.12,"transaction":0},"amex":{"type":"optBlue","volume":0.12,"transaction":0}}}},"services":[{"name":"hardwareAdvantagePlan","enabled":true}]}'
Response
application/json
{
  "id": "5",
  "createdDate": "2024-07-02T09:00:00",
  "lastUpdatedDate": "2024-07-02T09:00:00",
  "status": "pendingReview",
  "key": "string",
  "metadata": {
    "yourCustomField": "abc123"
  },
  "country": "US",
  "version": "5.0",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "june",
      "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
    }
  },
  "services": [
    {
      "name": "hardwareAdvantagePlan",
      "enabled": true
    }
  ]
}

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/5 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "id": "5",
  "createdDate": "2024-07-02T09:00:00",
  "lastUpdatedDate": "2024-07-02T09:00:00",
  "status": "pendingReview",
  "key": "string",
  "metadata": {
    "yourCustomField": "abc123"
  },
  "country": "US",
  "version": "5.0",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "june",
      "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
    }
  },
  "services": [
    {
      "name": "hardwareAdvantagePlan",
      "enabled": true
    }
  ]
}

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/5 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"key":"Your-Unique-Identifier","metadata":{"yourCustomField":"abc123"},"country":"US","version":"5.0","base":{"addressVerification":5,"annualFee":{"billInMonth":"june","amount":9900},"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":5},"amex":{"type":"optBlue","volume":1.25,"transaction":5},"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":5,"returns":400,"unauthorizedReturn":1999,"statement":800,"monthlyMinimum":20000,"accountVerification":10,"discountRateUnder10000":5.25,"discountRateAbove10000":10}}},"gateway":{"fees":{"monthly":2000,"setup":5000,"perTransaction":2000,"perDeviceMonthly":10}},"services":[{"name":"hardwareAdvantagePlan","enabled":true}]}'

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 an existing pricing intent. Structure your request to follow the RFC 6902 standard.

Path parameters

Header parameters

Body parameters

array of Patch Operations
Type

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/5 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '[{"op":"replace","path":"/processor/card/fees/mastercardVisaDiscover/volume","value":1.5},{"op":"replace","path":"/gateway/fees/additionalServiceMonthly","value":16},{"op":"replace","path":"/base/addressVerification","value":6}]'
Response
application/json
{
  "id": "5",
  "createdDate": "2024-07-02T09:00:00",
  "lastUpdatedDate": "2024-07-02T09:00:00",
  "status": "pendingReview",
  "key": "string",
  "metadata": {
    "yourCustomField": "abc123"
  },
  "country": "US",
  "version": "5.0",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "june",
      "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
    }
  },
  "services": [
    {
      "name": "hardwareAdvantagePlan",
      "enabled": true
    }
  ]
}

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/5 \
	--header 'Authorization: Bearer <access token>'

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 accounts

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/38765 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "processingAccountId": "38765",
  "createdDate": "2024-07-02T12:00:00.000Z",
  "lastModifiedDate": "2024-07-02T12:00:00.000Z",
  "status": "approved",
  "doingBusinessAs": "Pizza Doe",
  "owners": [
    {
      "ownerId": 4564,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "owner",
        "href": "https://api.payroc.com/v1/owners/1543",
        "method": "get"
      }
    }
  ],
  "website": "www.example.com",
  "businessType": "restaurant",
  "categoryCode": 5999,
  "merchandiseOrServiceSold": "Pizza",
  "businessStartDate": "2020-01-01",
  "timezone": "America/Chicago",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    }
  ],
  "processing": {
    "merchantId": "444412365478965",
    "transactionAmounts": {
      "average": 5000,
      "highest": 10000
    },
    "monthlyAmounts": {
      "average": 50000,
      "highest": 100000
    },
    "volumeBreakdown": {
      "cardPresentKeyed": 47,
      "cardPresentSwiped": 30,
      "mailOrTelephone": 3,
      "ecommerce": 20
    },
    "isSeasonal": true,
    "monthsOfOperation": [
      "jan",
      "feb"
    ],
    "ach": {
      "naics": "5812",
      "previouslyTerminatedForAch": false,
      "refunds": {
        "writtenRefundPolicy": true,
        "refundPolicyUrl": "www.example.com/refund-poilcy-url"
      },
      "estimatedMonthlyTransactions": 3000,
      "limits": {
        "singleTransaction": 10000,
        "dailyDeposit": 200000,
        "monthlyDeposit": 6000000
      },
      "transactionTypes": [
        "prearrangedPayment",
        "other"
      ],
      "transactionTypesOther": "anotherTransactionType"
    },
    "cardAcceptance": {
      "debitOnly": false,
      "hsaFsa": false,
      "cardsAccepted": [
        "visa",
        "mastercard"
      ],
      "specialityCards": {
        "americanExpressDirect": {
          "enabled": true,
          "merchantNumber": "abc1234567"
        },
        "electronicBenefitsTransfer": {
          "enabled": true,
          "fnsNumber": "6789012"
        },
        "other": {
          "wexMerchantNumber": "abc1234567",
          "voyagerMerchantId": "abc1234567",
          "fleetMerchantId": "abc1234567"
        }
      }
    }
  },
  "funding": {
    "status": "enabled",
    "fundingSchedule": "nextday",
    "acceleratedFundingFee": 1999,
    "dailyDiscount": false,
    "fundingAccounts": [
      {
        "fundingAccountId": 123,
        "status": "pending",
        "link": {
          "rel": "fundingAccount",
          "method": "get",
          "href": "https://api.payroc.com/v1/funding-account/123"
        }
      }
    ]
  },
  "pricing": {
    "link": {
      "rel": "pricing",
      "href": "https://api.payroc.com/v1/processing-account/38765/pricing",
      "method": "get"
    }
  },
  "contacts": [
    {
      "contactId": 1543,
      "firstName": "Jane",
      "lastName": "Doe",
      "link": {
        "rel": "contact",
        "href": "https://api.payroc.com/v1/contacts/1543",
        "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"
  }
}

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/38765/funding-accounts \
	--header 'Authorization: Bearer <access token>'
Response
application/json
[
  {
    "fundingAccountId": 123,
    "createdDate": "2024-07-02T12:00:00.000Z'",
    "lastModifiedDate": "2024-07-02T12:00:00.000Z",
    "status": "approved",
    "type": "checking",
    "use": "creditAndDebit",
    "nameOnAccount": "Jane Doe",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****6789",
          "accountNumber": "******7890"
        }
      }
    ],
    "metadata": {
      "yourCustomField": "abc123"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/processing-accounts/38765",
        "method": "get"
      }
    ]
  },
  {
    "fundingAccountId": 124,
    "createdDate": "2024-07-02T12:00:00.000Z",
    "lastModifiedDate": "2024-07-02T12:00:00.000Z",
    "status": "pending",
    "type": "checking",
    "use": "creditAndDebit",
    "nameOnAccount": "Jane Doe",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****8725",
          "accountNumber": "******3491"
        }
      }
    ],
    "metadata": {
      "yourCustomField": "abc123"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/processing-accounts/38765",
        "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/38765/contacts \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-accounts/38765/contacts?before=1543&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-accounts/38765/contacts?after=87926&limit=2"
    }
  ],
  "data": [
    {
      "contactId": 1543,
      "type": "manager",
      "firstName": "Jane",
      "middleName": "Helen",
      "lastName": "Doe",
      "identifiers": [
        {
          "type": "nationalId",
          "value": "xxxxx4320"
        }
      ],
      "contactMethods": [
        {
          "type": "phone",
          "value": "2025550164"
        },
        {
          "type": "mobile",
          "value": "8445557624"
        },
        {
          "type": "email",
          "value": "jane.doe@example.com"
        }
      ]
    },
    {
      "contactId": 87926,
      "type": "representative",
      "firstName": "Fred",
      "middleName": "Jim",
      "lastName": "Nerk",
      "identifiers": [
        {
          "type": "nationalId",
          "value": "xxxxx9876"
        }
      ],
      "contactMethods": [
        {
          "type": "phone",
          "value": "2025550110"
        },
        {
          "type": "mobile",
          "value": "85655587451"
        },
        {
          "type": "email",
          "value": "fred.nerk@example.com"
        }
      ]
    }
  ]
}

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
Type
Request
curl --request get \
	--url https://api.payroc.com/v1/processing-accounts/38765/pricing \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "country": "US",
  "version": "5.0",
  "base": {
    "addressVerification": 5,
    "annualFee": {
      "billInMonth": "december",
      "amount": 9900
    },
    "regulatoryAssistanceProgram": 15,
    "pciNonCompliance": 4995,
    "merchantAdvantage": 10,
    "platinumSecurity": {
      "billingFrequency": "monthly",
      "amount": 1295
    },
    "maintenance": 500,
    "minimum": 100,
    "voiceAuthorization": 95,
    "chargeback": 2500,
    "retrieval": 1500,
    "batch": 5,
    "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
    }
  }
}

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/38765/owners \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-accounts/38765/owners?before=4564&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-accounts/38765/owners?after=12346&limit=2"
    }
  ],
  "data": [
    {
      "ownerId": 4564,
      "firstName": "Jane",
      "middleName": "Helen",
      "lastName": "Doe",
      "dateOfBirth": "1964-03-22",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "identifiers": [
        {
          "type": "nationalId",
          "value": "xxxxx4320"
        }
      ],
      "contactMethods": [
        {
          "type": "email",
          "value": "jane.doe@example.com"
        },
        {
          "type": "phone",
          "value": "2025550164"
        }
      ],
      "relationship": {
        "equityPercentage": 48.5,
        "title": "CFO",
        "isControlProng": true,
        "isAuthorizedSignatory": false
      }
    },
    {
      "ownerId": 12346,
      "firstName": "Fred",
      "middleName": "Jim",
      "lastName": "Nerk",
      "dateOfBirth": "1980-01-19",
      "address": {
        "address1": "2 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "identifiers": [
        {
          "type": "nationalId",
          "value": "xxxxx9876"
        }
      ],
      "contactMethods": [
        {
          "type": "email",
          "value": "fred.nerk@example.com"
        }
      ],
      "relationship": {
        "equityPercentage": 51.5,
        "title": "CEO",
        "isControlProng": false,
        "isAuthorizedSignatory": true
      }
    }
  ]
}

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.

Create reminder for processing account

POST /processing-accounts/{processingAccountId}/reminders
When you create a processing account, we send a copy of the pricing agreement to the merchant to sign. You can choose to send them a copy of the pricing agreement by email, or you can generate a link to the pricing agreement.

If you requested the merchant's signature by email and they don't respond, use our Reminders endpoint to create a reminder and to send another email.

Note: You can use the Reminders endpoint only if you request the merchant's signature by email. If you generate a link to the pricing agreement, you can't use the Reminders endpoint.

Path parameters

Body parameters

Response Schema

Status Code 201

Successful request. We sent the email to the merchant.
Response body
Request
curl --request post \
	--url https://api.payroc.com/v1/processing-accounts/38765/reminders \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"type":"pricingAgreement"}'
Response
application/json
{
  "reminderId": "1234567",
  "type": "pricingAgreement"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
Not requested by email
We couldn't resend the email to the merchant because you didn't originally choose to send the information by email.
Contract already signed
We couldn’t resend the email because the merchant already signed the contract.
No pricing agreement exists for the processing account
We couldn’t resend the email because there is no pricing agreement for the processing account.
Forbidden
You do not have the required permission
Not found
Resource could not be found
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 \
	--header 'Authorization: Bearer <access token>'
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": "2024-07-02T15:30:00Z",
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "status": "approved",
      "type": "checking",
      "use": "credit",
      "nameOnAccount": "Jane Doe",
      "paymentMethods": [
        {
          "type": "ach",
          "value": {
            "routingNumber": "*****6789",
            "accountNumber": "******7890"
          }
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "links": [
        {
          "rel": "parent",
          "href": "https://api.payroc.com/v1/merchants/4525644354",
          "method": "get"
        }
      ]
    },
    {
      "fundingAccountId": 124,
      "createdDate": "2024-07-02T15:30:00Z",
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "status": "pending",
      "type": "checking",
      "use": "debit",
      "nameOnAccount": "Jane Doe",
      "paymentMethods": [
        {
          "type": "ach",
          "value": {
            "routingNumber": "*****8725",
            "accountNumber": "******3491"
          }
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "links": [
        {
          "rel": "parent",
          "href": "https://api.payroc.com/v1/funding-recipient/234",
          "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/123 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "fundingAccountId": 123,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "pending",
  "type": "checking",
  "use": "credit",
  "nameOnAccount": "Jane Doe",
  "paymentMethods": [
    {
      "type": "ach",
      "value": {
        "routingNumber": "*****6789",
        "accountNumber": "******7890"
      }
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  },
  "links": [
    {
      "rel": "parent",
      "href": "https://api.payroc.com/v1/merchants/4525644354",
      "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/123 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"type":"checking","use":"credit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"yourCustomField":"abc123"}}'

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/123 \
	--header 'Authorization: Bearer <access token>'

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 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-balance?before=4525644354&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-balance?after=9876543219&limit=2"
    }
  ],
  "data": [
    {
      "merchantId": "4525644354",
      "funds": 120000,
      "pending": 50050,
      "available": 69950,
      "currency": "USD"
    },
    {
      "merchantId": "9876543219",
      "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=2024-07-02&dateTo=2024-07-03' \
	--header 'Authorization: Bearer <access token>'
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=2024-07-01&dateto=2024-07-03"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2024-07-01&dateto=2024-07-03"
    }
  ],
  "data": [
    {
      "id": 11,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "description": "sales",
      "type": "credit",
      "amount": 4999,
      "currency": "USD"
    },
    {
      "id": 12,
      "date": "2024-07-02T19:32:00.000Z",
      "merchant": "Pizza Doe",
      "description": "sales",
      "type": "credit",
      "amount": 3999,
      "currency": "USD"
    },
    {
      "id": 13,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "description": "sales",
      "type": "credit",
      "amount": 3299,
      "currency": "USD"
    },
    {
      "id": 14,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Payroc",
      "description": "Interchange Fees",
      "type": "debit",
      "amount": 50,
      "currency": "USD"
    },
    {
      "id": 15,
      "date": "2024-07-02T09:10:00.000Z",
      "merchant": "Pizza Doe",
      "description": "sales",
      "type": "credit",
      "amount": 4999,
      "currency": "USD"
    },
    {
      "id": 16,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Doe Hot Dogs",
      "description": "Adjustment",
      "type": "credit",
      "amount": 750,
      "currency": "USD"
    },
    {
      "id": 17,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Doe Hot Dogs",
      "recipient": "Payroc",
      "description": "Interchange Fees",
      "type": "debit",
      "amount": 5,
      "currency": "USD"
    },
    {
      "id": 18,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Payroc",
      "description": "Charge back",
      "type": "debit",
      "amount": 1000,
      "currency": "USD"
    },
    {
      "id": 19,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "description": "sales",
      "type": "credit",
      "amount": 5999,
      "currency": "USD"
    },
    {
      "id": 20,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "payment",
      "type": "debit",
      "amount": 1000,
      "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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"merchants":[{"merchantId":"4525644354","recipients":[{"fundingAccountId":123,"paymentMethod":"ACH","amount":{"value":120000,"currency":"USD"},"metadata":{"yourCustomField":"abc123"}}]}],"metadata":{"yourCustomField":"abc123"}}'
Response
application/json
{
  "instructionId": 64643131,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "status": "accepted",
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "yourCustomField": "abc123"
          },
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/123"
          }
        }
      ],
      "link": {
        "rel": "merchant",
        "method": "get",
        "href": "https://api.payroc.com/v1/merchants/4525644354"
      }
    }
  ],
  "metadata": {
    "instructionRef": "abc123"
  }
}

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=2024-07-01&dateTo=2024-07-03' \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-instructions?before=64643131&limit=2&datefrom=2024-07-01&dateto=2024-07-03"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-instructions?after=64643132&limit=2&datefrom=2024-07-01&dateto=2024-07-03"
    }
  ],
  "data": [
    {
      "instructionId": 64643131,
      "createdDate": "2024-07-02T15:30:00Z",
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "status": "completed",
      "merchants": [
        {
          "merchantId": "4525644354",
          "recipients": [
            {
              "status": "funded",
              "fundingAccountId": 123,
              "paymentMethod": "ACH",
              "amount": {
                "value": 120000,
                "currency": "USD"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/123"
              }
            },
            {
              "status": "rejected",
              "fundingAccountId": 124,
              "paymentMethod": "ACH",
              "amount": {
                "value": 50050,
                "currency": "USD"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/124"
              }
            }
          ],
          "link": {
            "rel": "merchant",
            "method": "get",
            "href": "https://api.payroc.com/v1/merchants/4525644354"
          }
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "link": {
        "rel": "fundingInstruction",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-instructions/64643131"
      }
    },
    {
      "instructionId": 64643132,
      "createdDate": "2024-07-02T15:30:00Z",
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "status": "accepted",
      "merchants": [
        {
          "merchantId": "4525644354",
          "recipients": [
            {
              "status": "accepted",
              "fundingAccountId": 123,
              "paymentMethod": "ACH",
              "amount": {
                "value": 5000,
                "currency": "USD"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/123"
              }
            }
          ],
          "link": {
            "rel": "merchant",
            "method": "get",
            "href": "https://api.payroc.com/v1/merchants/4525644354"
          }
        },
        {
          "merchantId": "4525644354",
          "recipients": [
            {
              "status": "accepted",
              "fundingAccountId": 124,
              "paymentMethod": "ACH",
              "amount": {
                "value": 1000,
                "currency": "USD"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "link": {
                "rel": "fundingAccount",
                "method": "get",
                "href": "https://api.payroc.com/v1/funding-accounts/124"
              }
            }
          ],
          "link": {
            "rel": "merchant",
            "method": "get",
            "href": "https://api.payroc.com/v1/merchants/4525644354"
          }
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "link": {
        "rel": "fundingInstruction",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-instructions/64643132"
      }
    }
  ]
}

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/64643131 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "instructionId": 64643131,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "status": "accepted",
          "metadata": {
            "yourCustomField": "abc123"
          },
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/123"
          }
        }
      ],
      "link": {
        "rel": "merchant",
        "method": "get",
        "href": "https://api.payroc.com/v1/merchants/4525644354"
      }
    }
  ],
  "metadata": {
    "yourCustomField": "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.

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/64643131 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"merchants":[{"merchantId":"4525644354","recipients":[{"fundingAccountId":123,"paymentMethod":"ACH","amount":{"value":120000,"currency":"USD"},"metadata":{"yourCustomField":"abc123"}}]}],"metadata":{"yourCustomField":"abc123"}}'

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/64643131 \
	--header 'Authorization: Bearer <access token>'

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 recipients

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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"recipientType":"privateCorporation","taxId":"12-3456789","charityId":"abc123","doingBusinessAs":"abc123","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"metadata":{"yourCustomField":"abc123"},"owners":[{"firstName":"Jane","middleName":"Helen","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxxxx4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"relationship":{"equityPercentage":48.5,"title":"CFO","isControlProng":true,"isAuthorizedSignatory":false}}],"fundingAccounts":[{"type":"checking","use":"credit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"yourCustomField":"abc123"}}]}'
Response
application/json
{
  "recipientId": 234,
  "status": "approved",
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "charityId": "abc123",
  "doingBuinessAs": "abc123",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  },
  "owners": [
    {
      "ownerId": 4564,
      "link": {
        "rel": "owner",
        "href": "https://api.payroc.com/v1/owners/4564",
        "method": "get"
      }
    }
  ],
  "fundingAccounts": [
    {
      "fundingAccountId": 123,
      "status": "approved",
      "link": {
        "rel": "fundingAccount",
        "href": "https://api.payroc.com/v1/funding-accounts/123",
        "method": "get"
      }
    },
    {
      "fundingAccountId": 124,
      "status": "rejected",
      "link": {
        "rel": "fundingAccount",
        "href": "https://api.payroc.com/v1/funding-accounts/124",
        "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 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 10,
  "count": 1,
  "hasMore": false,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-recipients?before=234&limit=10"
    }
  ],
  "data": [
    {
      "recipientId": 234,
      "status": "approved",
      "createdDate": "2024-07-02T15:30:00Z",
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "recipientType": "privateCorporation",
      "taxId": "12-3456789",
      "doingBuinessAs": "Pizza Doe",
      "address": {
        "address1": "1 Example Ave.",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "contactMethods": [
        {
          "type": "phone",
          "value": "2025550164"
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "owners": [
        {
          "ownerId": 4564,
          "link": {
            "rel": "owner",
            "method": "get",
            "href": "https://api.payroc.com/v1/owners/4564"
          }
        }
      ],
      "fundingAccounts": [
        {
          "fundingAccountId": 123,
          "status": "approved",
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/123"
          }
        },
        {
          "fundingAccountId": 124,
          "status": "hold",
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/124"
          }
        }
      ]
    }
  ]
}

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/234 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "recipientId": 234,
  "status": "approved",
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "doingBuinessAs": "Pizza Doe",
  "address": {
    "address1": "1 Example Ave.",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "contactMethods": [
    {
      "type": "phone",
      "value": "2025550164"
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  },
  "owners": [
    {
      "ownerId": 4564,
      "link": {
        "rel": "owner",
        "method": "get",
        "href": "https://api.payroc.com/v1/owners/4564"
      }
    }
  ],
  "fundingAccounts": [
    {
      "fundingAccountId": 123,
      "status": "approved",
      "link": {
        "rel": "fundingAccount",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-accounts/123"
      }
    },
    {
      "fundingAccountId": 124,
      "status": "hold",
      "link": {
        "rel": "fundingAccount",
        "method": "get",
        "href": "https://api.payroc.com/v1/funding-accounts/124"
      }
    }
  ]
}

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/234 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"recipientType":"privateCorporation","taxId":"12-3456789","charityId":"abc123","doingBuinessAs":"abc123","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"metadata":{"yourCustomField":"abc123"}}'

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/234 \
	--header 'Authorization: Bearer <access token>'

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/234/funding-accounts \
	--header 'Authorization: Bearer <access token>'
Response
application/json
[
  {
    "fundingAccountId": 123,
    "createdDate": "2024-07-02T15:30:00Z",
    "lastModifiedDate": "2024-07-02T15:30:00Z",
    "status": "approved",
    "type": "checking",
    "use": "credit",
    "nameOnAccount": "Jane Doe",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****6789",
          "accountNumber": "******7890"
        }
      }
    ],
    "metadata": {
      "yourCustomField": "abc123"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/funding-recipient/234",
        "method": "get"
      }
    ]
  },
  {
    "fundingAccountId": 124,
    "createdDate": "2024-07-02T15:30:00Z",
    "lastModifiedDate": "2024-07-02T15:30:00Z",
    "status": "pending",
    "type": "checking",
    "use": "debit",
    "nameOnAccount": "Jane Doe",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****8725",
          "accountNumber": "******3491"
        }
      }
    ],
    "metadata": {
      "yourCustomField": "abc123"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/funding-recipient/235",
        "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/234/funding-accounts \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"type":"checking","use":"credit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}],"metadata":{"yourCustomField":"abc123"}}'
Response
application/json
{
  "fundingAccountId": 123,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "approved",
  "type": "checking",
  "use": "credit",
  "nameOnAccount": "Jane Doe",
  "paymentMethods": [
    {
      "type": "ach",
      "value": {
        "routingNumber": "*****6789",
        "accountNumber": "******7890"
      }
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  },
  "links": [
    {
      "rel": "parent",
      "href": "https://api.payroc.com/v1/funding-recipient/234",
      "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 funding recipient owners

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/234/owners \
	--header 'Authorization: Bearer <access token>'
Response
application/json
[
  {
    "ownerId": 4564,
    "firstName": "Jane",
    "middleName": "Helen",
    "lastName": "Doe",
    "dateOfBirth": "1964-03-22",
    "address": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "identifiers": [
      {
        "type": "nationalId",
        "value": "xxxxx4320"
      }
    ],
    "contactMethods": [
      {
        "type": "email",
        "value": "jane.doe@example.com"
      }
    ],
    "relationship": {
      "equityPercentage": 48.5,
      "title": "CFO",
      "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 funding recipient 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/234/owners \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"firstName":"Jane","middleName":"Helen","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"xxxxx4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"}],"relationship":{"equityPercentage":48.5,"title":"CFO","isControlProng":true,"isAuthorizedSignatory":false}}'
Response
application/json
{
  "ownerId": 4564,
  "firstName": "Jane",
  "middleName": "Helen",
  "lastName": "Doe",
  "dateOfBirth": "1964-03-22",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "identifiers": [
    {
      "type": "nationalId",
      "value": "xxxxx4320"
    }
  ],
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    }
  ],
  "relationship": {
    "equityPercentage": 48.5,
    "title": "CFO",
    "isControlProng": true,
    "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.

Event Subscriptions

Create an event subscription so that we notify you when certain events occur, for example, when we change the status of a processing account.
When you subscribe to an event, provide the following information:
  • Event type - The events that we should notify you about. You can subscribe to more than one event within the same request. For a list of events that you can subscribe to, go to Events.
  • Notification method - The endpoint that we send a notification to if an event occurs. We send notifications by webhook request.
  • Event status - The status of the event subscription.
  • Support email address - Email address that we contact if we can't deliver notifications.

Use our event subscriptions endpoint to do the following:

List event subscriptions

GET /event-subscriptions
Use this method to retrieve a paginated list of event subscriptions that are linked to the ISV's account.

Query parameters

Response Schema

Status Code 200

Successful request. Returns a list of event subscriptions.
Response body
Request
curl --request get \
	--url https://api.payroc.com/v1/event-subscriptions \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 10,
  "count": 2,
  "hasMore": false,
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/event-subscriptions?after=10&limit=10"
    }
  ],
  "data": [
    {
      "id": 2565435189324,
      "enabled": true,
      "status": "registered",
      "eventTypes": [
        "processingAccount.status.changed"
      ],
      "notifications": [
        {
          "type": "webhook",
          "uri": "https://my-service/notification/endpoint",
          "secret": "**********NoP3456",
          "supportEmailAddress": "jane.doe@example.com"
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      }
    },
    {
      "id": 2565435189325,
      "enabled": true,
      "status": "registered",
      "eventTypes": [
        "processingAccount.riskStatus.changed"
      ],
      "notifications": [
        {
          "type": "webhook",
          "uri": "https://my-service/notification/endpoint",
          "secret": "**********NoP3456",
          "supportEmailAddress": "jane.doe@example.com"
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      }
    }
  ]
}

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
Api error
Unable to process your request.

Create event subscription

POST /event-subscriptions
Use this method to subscribe to events that you want us to notify you about, for example, when we change the status of a processing account. You can subscribe to more than one event in the request. For a complete list of events you can subscribe to, go to Events.
In the response we return the ID of the event subscription, which you need for the following methods:

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the event subscription.
Response headers
Response body
Request
curl --request post \
	--url https://api.payroc.com/v1/event-subscriptions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"enabled":true,"eventTypes":["processingAccount.status.changed"],"notifications":[{"type":"webhook","uri":"https://my-server/notification/endpoint","secret":"aBcD1234eFgH5678iJkL9012mNoP3456","supportEmailAddress":"jane.doe@example.com"}],"metadata":{"yourCustomField":"abc123"}}'
Response
application/json
{
  "id": 2565435189324,
  "enabled": true,
  "status": "registered",
  "eventTypes": [
    "processingAccount.status.changed"
  ],
  "notifications": [
    {
      "type": "webhook",
      "uri": "https://my-service/notification/endpoint",
      "secret": "**********NoP3456",
      "supportEmailAddress": "jane.doe@example.com"
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}

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.

Retrieve event subscription

GET /event-subscriptions/{subscriptionId}
Use this method to retrieve the details of an event subscription. In your request, include the subscriptionId that we sent to you when we created the event subscription. Note: If you don't know the subscriptionId of the event subscription, go to List event subscriptions.

Path parameters

Response Schema

Status Code 200

Returns the event subscription object.
Response body
Request
curl --request get \
	--url https://api.payroc.com/v1/event-subscriptions/7654 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "id": 2565435189324,
  "enabled": true,
  "status": "registered",
  "eventTypes": [
    "processingAccount.status.changed"
  ],
  "notifications": [
    {
      "type": "webhook",
      "uri": "https://my-service/notification/endpoint",
      "secret": "**********NoP3456",
      "supportEmailAddress": "jane.doe@example.com"
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}

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
Api error
Unable to process your request.

Update event subscription

PUT /event-subscriptions/{subscriptionId}
Use this method to update an event subscription.
You can make the following updates to the event subscription:
  • Event types - Add or remove events that you have subscribed to.
  • Notification methods - Update information about your endpoint and who we email if we can't contact your endpoint.
Include the subscriptionId that we sent you when you created the event subscription. We returned this in the id field. Note: If you don't know the subscriptionId, go to List event subscriptions

Path parameters

Body parameters

Response Schema

Status Code 204

Successful request. We updated the event subscription.
Request
curl --request put \
	--url https://api.payroc.com/v1/event-subscriptions/7654 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"enabled":true,"eventTypes":["processingAccount.status.changed"],"notifications":[{"type":"webhook","uri":"https://my-server/notification/endpoint","secret":"aBcD1234eFgH5678iJkL9012mNoP3456","supportEmailAddress":"jane.doe@example.com"}],"metadata":{"yourCustomField":"abc123"}}'

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.

Partially update event subscription

PATCH /event-subscriptions/{subscriptionId}
Use this method to partially update an event subscription. You can make the following updates to the event subscription:
  • Add or remove events that you have subscribed to.
  • Update information about your endpoint and who we email if we can't contact your endpoint.
  • Turn on or turn off notifications for the event.
Structure your request to follow the RFC 6902 standard. Note: You need the subscriptionId that we sent you when you created the event subscription. If you don't know the subscriptionId, go to List event subscriptions.

Path parameters

Body parameters

array of Patch Operations
Type

Response Schema

Status Code 200

Successful request. We updated the event subscription.
Response body
Request
curl --request patch \
	--url https://api.payroc.com/v1/event-subscriptions/7654 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '[{"op":"replace","path":"/enabled","value":false}]'
Response
application/json
{
  "id": 2565435189324,
  "enabled": false,
  "status": "registered",
  "eventTypes": [
    "processingAccount.status.changed"
  ],
  "notifications": [
    {
      "type": "webhook",
      "uri": "https://my-service/notification/endpoint",
      "secret": "**********NoP3456",
      "supportEmailAddress": "jane.doe@example.com"
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}

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.

Delete event subscription

DELETE /event-subscriptions/{subscriptionId}
Use this method to delete an event subscription.

Path parameters

Response Schema

Status Code 204

Successful request. We deleted the event subscription.
Request
curl --request delete \
	--url https://api.payroc.com/v1/event-subscriptions/7654 \
	--header 'Authorization: Bearer <access token>'

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
Api error
Unable to process your request.

Apple Pay session

An Apple Pay session authenticates the merchant's domain with Apple. After you start an Apple Pay session, you can use the Apple Pay JS API to retrieve the cardholder's encrypted payment details.

Start Apple Pay session

POST /processing-terminals/{processingTerminalId}/apple-pay-sessions
Use this method to start an Apple Pay session for your merchant. In the response, we return the startSessionObject that you send to Apple when you retrieve the cardholder's encrypted payment details.

Path parameters

Body parameters

Response Schema

Status Code 200

Successful request. We started the Apple Pay session.
Response body
Request
curl --request post \
	--url https://api.payroc.com/v1/processing-terminals/1234001/apple-pay-sessions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"appleDomainId":"DUHDZJHGYY","appleValidationUrl":"https://apple-pay-gateway.apple.com/paymentservices/startSession"}'
Response
application/json
{
  "startSessionResponse": "{\n  \"epochTimestamp\": 1736264582447,\n  \"expiresAt\": 1736268182447,\n  \"merchantSessionIdentifier\": \"SSHE464E2B91B714F18BFD19D46D0F582BF_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24\",\n  \"nonce\": \"e5775127\",\n  \"merchantIdentifier\": \"BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503\",\n  \"domainName\": \"store.com\",\n  \"displayName\": \"Store One\",\n  \"signature\": \"308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e43082038ba003020102020859d8a1bcaaf4e3cd300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3231303432303139333730305a170d3236303431393139333635395a30623128302606035504030c1f6563632d736d702d62726f6b65722d7369676e5f5543342d53414e44424f5831143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d030107034200048230fdabc39cf75e202c50d99b4512e637e2a901dd6cb3e0b1cd4b526798f8cf4ebde81a25a8c21e4c33ddce8e2a96c2f6afa1930345c4e87a4426ce951b1295a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d657320616363657074616e6365206f6620746865207468656e206170706c696361626c65207374616e64617264207465726d7320616e6420636f6e646974696f6e73206f66207573652c20636572746966696361746520706f6c69637920616e642063657274696669636174696f6e2070726163746963652073746174656d656e74732e303606082b06010505070201162a687474703a2f2f7777772e6170706c652e636f6d2f6365727469666963617465617574686f726974792f30340603551d1f042d302b3029a027a0258623687474703a2f2f63726c2e6170706c652e636f6d2f6170706c6561696361332e63726c301d0603551d0e041604140224300b9aeeed463197a4a65a299e4271821c45300e0603551d0f0101ff040403020780300f06092a864886f76364061d04020500300a06082a8648ce3d0403020347003044022074a1b324db4249430dd3274c5074c4808d9a1f480e3a85c5c1362566325fbca3022069369053abf50b5a52f9f6004dc58aad6c50a7d608683790e0a73ad01e4ad981308202ee30820275a0030201020208496d2fbf3a98da97300a06082a8648ce3d0403023067311b301906035504030c124170706c6520526f6f74204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3134303530363233343633305a170d3239303530363233343633305a307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004f017118419d76485d51a5e25810776e880a2efde7bae4de08dfc4b93e13356d5665b35ae22d097760d224e7bba08fd7617ce88cb76bb6670bec8e82984ff5445a381f73081f4304606082b06010505070101043a3038303606082b06010505073001862a687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65726f6f7463616733301d0603551d0e0416041423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b300f0603551d130101ff040530030101ff301f0603551d23041830168014bbb0dea15833889aa48a99debebdebafdacb24ab30370603551d1f0430302e302ca02aa0288626687474703a2f2f63726c2e6170706c652e636f6d2f6170706c65726f6f74636167332e63726c300e0603551d0f0101ff0404030201063010060a2a864886f7636406020e04020500300a06082a8648ce3d040302036700306402303acf7283511699b186fb35c356ca62bff417edd90f754da28ebef19c815e42b789f898f79b599f98d5410d8f9de9c2fe0230322dd54421b0a305776c5df3383b9067fd177c2c216d964fc6726982126f54f87a7d1b99cb9b0989216106990f09921d00003182018930820185020101308186307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553020859d8a1bcaaf4e3cd300b0609608648016503040201a08193301806092a864886f70d010903310b06092a864886f70d010701301c06092a864886f70d010905310f170d3235303130373135343330325a302806092a864886f70d010934311b3019300b0609608648016503040201a10a06082a8648ce3d040302302f06092a864886f70d010904312204209a4e5d8d01ad895c444f1dc7d92737c013db0837955996dc633fb44c096dfcb3300a06082a8648ce3d04030204483046022100aef85f669578d5e2628d7e570b41558dd8504fd0050ca0e9d82db9b1120a8319022100cdbfba17f0873be9be029786e84d4e6cef99cc5c79f32d61ee73aafc157296aa000000000000\",\n  \"operationalAnalyticsIdentifier\": \"Store One:BFB110EE83BE2AF4AA7468926C926CCFC57F4A541CCE6E7F3BEFD05002ECE503\",\n  \"retries\": 0,\n  \"pspId\": \"17D4AAA8D9357D26D771ABA0DAA0B9D3BB462AD1585492E1FE688AF8BB9558E5\"\n}\n"
}

Errors

ErrorDescription
Bad Request
One or more validation errors occurred
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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"processingTerminalId":"1234001","bankAccount":{"type":"pad","accountType":"checking","nameOnAccount":"Sarah Hazel Hopper","accountNumber":"1234567890","routingNumber":"123456789","transitNumber":"76543","institutionNumber":"543"}}'
Response
application/json
{
  "processingTerminalId": "1234001",
  "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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","description":"Large Pepperoni Pizza","amount":4999,"currency":"USD","breakdown":{"subtotal":4347,"tip":{"type":"percentage","percentage":10},"taxes":[{"name":"Sales Tax","rate":5}]}},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"joe@blogssoftware.com"}]},"credentialOnFile":{"tokenize":true},"paymentMethod":{"type":"ach","accountType":"checking","nameOnAccount":"Sarah Hazel Hopper","accountNumber":"32183159","routingNumber":"063100277","secCode":"web"},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1017",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD",
    "breakdown": {
      "subtotal": 4347,
      "tip": {
        "type": "percentage",
        "amount": 435,
        "percentage": 10
      },
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5,
          "amount": 217
        }
      ]
    }
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "ach",
    "secCode": "web",
    "accountType": "checking",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****3159",
    "routingNumber": "063100277",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "ready",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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=1234001' \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "paymentId": "M2MJOG6O2Y",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef6543",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Large Pepperoni Pizza",
        "amount": 4999,
        "currency": "USD",
        "breakdown": {
          "subtotal": 4347,
          "tip": {
            "type": "percentage",
            "amount": 435,
            "percentage": 10
          },
          "taxes": [
            {
              "name": "Sales Tax",
              "rate": 5,
              "amount": 217
            }
          ]
        }
      },
      "customer": {
        "contactMethods": [
          {
            "type": "email",
            "value": "sarah.hopper@example.com"
          }
        ],
        "notificationLanguage": "en"
      },
      "bankAccount": {
        "type": "pad",
        "nameOnAccount": "Sarah Hazel Hopper",
        "accountNumber": "*******3159",
        "transitNumber": "76543",
        "institutionNumber": "543"
      },
      "transactionResult": {
        "type": "payment",
        "status": "ready",
        "authorizedAmount": 4999,
        "currency": "USD",
        "responseCode": "A"
      }
    },
    {
      "paymentId": "E29U8OU8Q4",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef7654",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "test",
        "amount": 3999,
        "currency": "USD",
        "breakdown": {
          "subtotal": 3477,
          "tip": {
            "type": "percentage",
            "amount": 348,
            "percentage": 10
          },
          "taxes": [
            {
              "name": "Sales Tax",
              "rate": 5,
              "amount": 174
            }
          ]
        }
      },
      "customer": {
        "contactMethods": [
          {
            "type": "email",
            "value": "sarah.hopper@example.com"
          }
        ],
        "notificationLanguage": "en"
      },
      "bankAccount": {
        "type": "pad",
        "nameOnAccount": "Sarah Hazel Hopper",
        "accountNumber": "*******7890",
        "transitNumber": "76543",
        "institutionNumber": "543"
      },
      "transactionResult": {
        "type": "payment",
        "status": "ready",
        "authorizedAmount": 3999,
        "currency": "USD",
        "responseCode": "A"
      },
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/bank-transfer-payments?limit=2&processingTerminalId=1234001&after=E29U8OU8Q4"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1//bank-transfer-payments?limit=2&processingTerminalId=1234001&before=M2MJOG6O2Y"
    }
  ]
}

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/M2MJOG6O2Y \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1017",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD",
    "breakdown": {
      "subtotal": 4347,
      "tip": {
        "type": "percentage",
        "amount": 435,
        "percentage": 10
      },
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5,
          "amount": 217
        }
      ]
    }
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "ach",
    "secCode": "web",
    "accountType": "checking",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****3159",
    "routingNumber": "063100277",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "ready",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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.

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/M2MJOG6O2Y/reverse \
	--header 'Authorization: Bearer <access token>' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD",
    "breakdown": {
      "subtotal": 4347,
      "tip": {
        "type": "percentage",
        "percentage": 10
      },
      "taxes": [
        {
          "name": "VAT",
          "rate": 5,
          "amount": 217
        }
      ]
    }
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "pad",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "*******7890",
    "transitNumber": "76543",
    "institutionNumber": "543"
  },
  "transactionResult": {
    "type": "payment",
    "status": "reversal",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/M2MJOG6O2Y/refund \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"amount":4999,"description":"amount to refund"}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "breakdown": {
      "subtotal": 4347,
      "tip": {
        "type": "percentage",
        "amount": 435,
        "percentage": 10
      },
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5,
          "amount": 217
        }
      ]
    }
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "pad",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****7890",
    "transitNumber": "76543",
    "institutionNumber": "543",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "reversal",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/M2MJOG6O2Y/represent \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"paymentMethod":{"type":"ach","accountType":"checking","nameOnAccount":"Sarah Hopper","accountNumber":"32183159","routingNumber":"063100277","secCode":"tel"}}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1017",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD",
    "breakdown": {
      "subtotal": 4347,
      "tip": {
        "type": "percentage",
        "amount": 435,
        "percentage": 10
      },
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5,
          "amount": 217
        }
      ]
    }
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "ach",
    "secCode": "web",
    "accountType": "checking",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****3159",
    "routingNumber": "063100277",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "ready",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","description":"Refund for order OrderRef6543","amount":4999,"currency":"USD"},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"sarah.hopper@example.com"}]},"refundMethod":{"type":"ach","secCode":"web","accountType":"checking","nameOnAccount":"Sarah Hazel Hopper","accountNumber":"1234567890","routingNumber":"123456789"},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "ach",
    "secCode": "web",
    "accountType": "checking",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****7890",
    "routingNumber": "*****6789"
  },
  "transactionResult": {
    "type": "unreferencedRefund",
    "status": "ready",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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=1234001' \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "refundId": "CD3HN88U9F",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef6543",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "refund example",
        "amount": 4999,
        "currency": "USD"
      },
      "customer": {
        "contactMethods": [
          {
            "type": "email",
            "value": "sarah.hopper@example.com"
          }
        ],
        "notificationLanguage": "en"
      },
      "bankAccount": {
        "type": "ach",
        "secCode": "web",
        "accountType": "checking",
        "nameOnAccount": "Sarah Hazel Hopper",
        "accountNumber": "****3159",
        "routingNumber": "*****0277"
      },
      "transactionResult": {
        "type": "unreferencedRefund",
        "status": "ready",
        "authorizedAmount": -4999,
        "currency": "USD",
        "responseCode": "A",
        "responseMessage": "NoError",
        "processorResponseCode": "0"
      }
    },
    {
      "refundId": "B6ZOFZNVOP",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef7654",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Refund for order OrderRef7654",
        "amount": 3999,
        "currency": "USD"
      },
      "customer": {
        "contactMethods": [
          {
            "type": "email",
            "value": "sarah.hopper@example.com"
          }
        ],
        "notificationLanguage": "en"
      },
      "bankAccount": {
        "type": "ach",
        "secCode": "web",
        "accountType": "checking",
        "nameOnAccount": "Sarah Hazel Hopper",
        "accountNumber": "****3159",
        "routingNumber": "*****0277"
      },
      "transactionResult": {
        "type": "unreferencedRefund",
        "status": "ready",
        "authorizedAmount": -3999,
        "currency": "USD",
        "responseCode": "A",
        "responseMessage": "NoError",
        "processorResponseCode": "0"
      },
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/bank-transfer-refunds?limit=2&processingTerminalId=1234001&after=B6ZOFZNVOP"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/bank-transfer-refunds?processingTerminalId=1234001&limit=2&before=CD3HN88U9F"
    }
  ]
}

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/CD3HN88U9F \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "ach",
    "secCode": "web",
    "accountType": "checking",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****7890",
    "routingNumber": "*****6789"
  },
  "transactionResult": {
    "type": "unreferencedRefund",
    "status": "ready",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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.

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/CD3HN88U9F/reverse \
	--header 'Authorization: Bearer <access token>' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "bankAccount": {
    "type": "ach",
    "secCode": "web",
    "accountType": "checking",
    "nameOnAccount": "Sarah Hazel Hopper",
    "accountNumber": "****3159",
    "routingNumber": "*****0277"
  },
  "transactionResult": {
    "type": "unreferencedRefund",
    "status": "reversal",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"operator":"Jane","processingTerminalId":"1234001","card":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Sarah Hazel Hopper","cardholderSignature":"a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1225"}}}}'
Response
application/json
{
  "operator": "Jane",
  "processingTerminalId": "1234001",
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardholderName": "Sarah Hazel Hopper",
    "cardholderSignature": "a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"operator":"Jane","processingTerminalId":"1234001","currency":"USD","card":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Sarah Hazel Hopper","cardholderSignature":"a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1225","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": "Jane",
  "processingTerminalId": "1234001",
  "card": {
    "type": "Common Benefit Identification Card",
    "entryMethod": "keyed",
    "cardholderName": "Sarah Hazel Hopper",
    "cardholderSignature": "a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"operator":"Jane","processingTerminalId":"1234001","card":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Sarah Hazel Hopper","cardholderSignature":"a1b1c012345678a000b000c0012345d0e0f010g10061a031i001j071k0a1b0c1d0e1234567890120f1g0h1i0j1k0a1b0123451c012d0e1f0g1h0i1j123k1a1b1c1d1e1f1g123h1i1j1k1a1b1c1d1e1f1g123h123i1j123k12340a120a12345b012c0123012d0d1e0f1g0h1i123j123k10000","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1225"}}}}'
Response
application/json
{
  "type": "MASTERCARD",
  "cardNumber": "453985******7062",
  "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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--data '{"channel":"web","operator":"Jane","processingTerminalId":"1234001","baseAmount":10000,"baseCurrency":"USD","paymentMethod":{"type":"card","accountType":"checking","cardDetails":{"entryMethod":"keyed","cardholderName":"Sarah Hazel Hopper","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1225"}}}}'
Response
application/json
{
  "processingTerminalId": "1234001",
  "operator": "Jane",
  "baseAmount": 10000,
  "baseCurrency": "USD",
  "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": "453985******7062"
  }
}

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.

Hosted Fields

Create a Hosted Fields session.

Create session

POST /processing-terminals/{processingTerminalId}/hosted-fields-sessions
Use this method to create a session token that you use to authenticate a Hosted Fields session. When you create an instance of Hosted Fields on a webpage, include the session token in the config object. For more information about how to set up Hosted Fields, see Set up Hosted Fields. Note: You need to generate a new session token each time you load Hosted Fields on a webpage.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We created the session and returned a session token.
Response headers
Response body
Request
curl --request post \
	--url https://api.payroc.com/v1/processing-terminals/1234001/hosted-fields-sessions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"libVersion":"1.1.0.123456","scenario":"payment"}'
Response
application/json
{
  "processingTerminalId": "1234001",
  "token": "abcdef1234567890abcdef1234567890",
  "expiresAt": "2025-07-02T15:30:00.000+02:00"
}

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.

Payment links

Create and share payment links.

Create payment link

POST /processing-terminals/{processingTerminalId}/payment-links
Create links to a hosted payment page where a customer can securely pay.

Path parameters

Header parameters

Body parameters

Type

Response Schema

Status Code 201

Successful request. We created the payment link.
Response headers
Response body
Type
Request
curl --request post \
	--url https://api.payroc.com/v1/processing-terminals/1234001/payment-links \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"type":"multiUse","merchantReference":"LinkRef6543","order":{"description":"Pie It Forward charitable trust donation","charge":{"type":"prompt","currency":"USD"}},"authType":"sale","paymentMethods":["card","bankTransfer"],"customLabels":[{"element":"paymentButton","label":"SUPPORT US"}]}'
Response
application/json
{
  "type": "multiUse",
  "paymentLinkId": "JZURRJBUPS",
  "merchantReference": "LinkRef6543",
  "order": {
    "description": "Pie It Forward charitable trust donation",
    "charge": {
      "type": "prompt",
      "currency": "USD"
    }
  },
  "authType": "sale",
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    }
  ],
  "assets": {
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d",
    "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d\" \ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif; \ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">SUPPORT US</a>\n"
  },
  "status": "active",
  "createdOn": "2024-09-24"
}

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.

List payment links

GET /processing-terminals/{processingTerminalId}/payment-links
List payment links 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 payment links.
Response body
Request
curl --request get \
	--url https://api.payroc.com/v1/processing-terminals/1234001/payment-links \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "type": "multiUse",
      "paymentLinkId": "JZURRJBUPS",
      "merchantReference": "LinkRef6543",
      "order": {
        "description": "Pie It Forward charitable trust donation",
        "charge": {
          "type": "prompt",
          "currency": "USD"
        }
      },
      "authType": "sale",
      "paymentMethods": [
        "card",
        "bankTransfer"
      ],
      "customLabels": [
        {
          "element": "paymentButton",
          "label": "SUPPORT US"
        }
      ],
      "assets": {
        "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d",
        "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d\" \ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif; \ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">SUPPORT US</a>\n"
      },
      "status": "active",
      "createdOn": "2024-07-02"
    },
    {
      "type": "singleUse",
      "paymentLinkId": "CKHP6VVWYT",
      "merchantReference": "LinkRef7654",
      "order": {
        "orderId": "OrderRef7654",
        "description": "Large Pepperoni Pizza",
        "charge": {
          "type": "preset",
          "amount": 4999,
          "currency": "USD"
        }
      },
      "authType": "sale",
      "paymentMethods": [
        "card"
      ],
      "assets": {
        "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=7c2fc08c-cb0e-44ba-8bcd-cf6de6eb3206",
        "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=7c2fc08c-cb0e-44ba-8bcd-cf6de6eb3206\" \ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif; \ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">Pay Now</a>\n"
      },
      "status": "active",
      "createdOn": "2024-09-24",
      "expiresOn": "2024-10-24"
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1001/payment-links?limit=2&after=CKHP6VVWYT"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1001/payment-links?limit=2&before=JZURRJBUPS"
    }
  ]
}

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.

Retrieve payment link

GET /payment-links/{paymentLinkId}
Retrieve a specific payment link.

Path parameters

Response Schema

Status Code 200

Successful request. Returns the requested payment link.
Response body
Type
Request
curl --request get \
	--url https://api.payroc.com/v1/payment-links/JZURRJBUPS \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "type": "multiUse",
  "paymentLinkId": "JZURRJBUPS",
  "merchantReference": "LinkRef6543",
  "order": {
    "description": "Pie It Forward charitable trust donation",
    "charge": {
      "type": "prompt",
      "currency": "USD"
    }
  },
  "authType": "sale",
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    }
  ],
  "assets": {
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d",
    "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d\" \ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif; \ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">SUPPORT US</a>\n"
  },
  "status": "active",
  "createdOn": "2024-09-24"
}

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 link

PATCH /payment-links/{paymentLinkId}
Make changes to an existing payment link. Structure your request to follow the RFC 6902 standard.

Path parameters

Header parameters

Body parameters

array of Patch Operations
Type

Response Schema

Status Code 200

Successful request. We updated the payment link.
Response body
Type
Request
curl --request patch \
	--url https://api.payroc.com/v1/payment-links/JZURRJBUPS \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '[{"op":"replace","path":"/expiresOn","value":"2024-10-25"}]'
Response
application/json
{
  "type": "multiUse",
  "paymentLinkId": "JZURRJBUPS",
  "merchantReference": "LinkRef6543",
  "order": {
    "description": "Pie It Forward charitable trust donation",
    "charge": {
      "type": "prompt",
      "currency": "USD"
    }
  },
  "authType": "sale",
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    }
  ],
  "assets": {
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d",
    "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d\" \ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif; \ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">SUPPORT US</a>\n"
  },
  "status": "active",
  "createdOn": "2024-09-24"
}

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.

Deactivate payment link

POST /payment-links/{paymentLinkId}/deactivate
Deactivate a payment link. This operation is irreversible.

Path parameters

Response Schema

Status Code 200

Successful request. We deactivated the payment link.
Response body
Type
Request
curl --request post \
	--url https://api.payroc.com/v1/payment-links/JZURRJBUPS/deactivate \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "type": "multiUse",
  "paymentLinkId": "JZURRJBUPS",
  "merchantReference": "LinkRef6543",
  "order": {
    "description": "Pie It Forward charitable trust donation",
    "charge": {
      "type": "prompt",
      "currency": "USD"
    }
  },
  "authType": "sale",
  "paymentMethods": [
    "card",
    "bankTransfer"
  ],
  "customLabels": [
    {
      "element": "paymentButton",
      "label": "SUPPORT US"
    }
  ],
  "assets": {
    "paymentUrl": "https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d",
    "paymentButton": "<a href=\"https://payments.payroc.com/merchant/pay-by-link?token=02ada211-ff51-4845-b0b5-e685aeb4b19d\" \ntarget=\"_blank\" style=\"color: #ffffff; background-color: #6C7A89; font-size: 18px; font-family: Helvetica, Arial, sans-serif; \ntext-decoration: none; border-radius: 30px; padding: 14px 28px; display: inline-block;\">SUPPORT US</a>\n"
  },
  "status": "deactivated",
  "createdOn": "2024-07-24"
}

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
Api error
Unable to process your request.

Share payment link

POST /payment-links/{paymentLinkId}/sharing-events
Share a payment link with customers.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 201

Successful request. We shared the payment link.
Response body
Request
curl --request post \
	--url https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"sharingMethod":"email","merchantCopy":true,"message":"Dear Sarah,\n\nYour insurance is expiring this month.\nPlease, pay the renewal fee by the end of the month to renew it.\n","recipients":[{"name":"Sarah Hazel Hopper","email":"sarah.hopper@example.com"}]}'
Response
application/json
{
  "sharingMethod": "email",
  "sharingEventId": "GTZH5WVXK9",
  "dateTime": "2024-07-02T15:30:00Z",
  "message": "Dear Sarah,\n\nYou can pay for your order via the link below.\n",
  "recipients": [
    {
      "name": "Sarah Hazel Hopper",
      "email": "sarah.hopper@example.com"
    }
  ]
}

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.

List payment link sharing events.

GET /payment-links/{paymentLinkId}/sharing-events
List sharing events linked to a payment link.
To filter your results, use the query parameters.

Path parameters

Query parameters

Response Schema

Status Code 200

Successful request. Returns a paginated list of sharing events.
Response body
Request
curl --request get \
	--url https://api.payroc.com/v1/payment-links/JZURRJBUPS/sharing-events \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "sharingMethod": "email",
      "sharingEventId": "GKB49GZ6DL",
      "dateTime": "2024-07-02T15:30:00Z",
      "message": "Dear Sarah,\n\nYou can pay for your order via the link below.\n",
      "recipients": [
        {
          "name": "Sarah Hazel Hopper",
          "email": "sarah.hopper@example.com"
        }
      ]
    },
    {
      "sharingMethod": "email",
      "sharingEventId": "GTZH5WVXK9",
      "dateTime": "2024-07-02T15:30:00Z",
      "message": "Dear Sarah,\n\nThank you for continuing to support our Pie It Forward charitable trust.\nYou can make your payment via the link below.\n",
      "recipients": [
        {
          "name": "Sarah Hazel Hopper",
          "email": "sarah.hopper@example.com"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/payment-links/CKHP6VVWYT/sharing-events?limit=2&after=GTZH5WVXK9"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/payment-links/CKHP6VVWYT/sharing-events?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 found
Resource could not be found
Not acceptable
Requested representation not supported
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/1234001/payment-plans \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"paymentPlanId":"PlanRef8765","name":"Premium Club","description":"Monthly Premium Club subscription","currency":"USD","setupOrder":{"amount":4999,"description":"Initial setup fee for Premium Club subscription","breakdown":{"subtotal":4347,"taxes":[{"name":"Sales Tax","rate":5}]}},"recurringOrder":{"amount":4999,"description":"Monthly Premium Club subscription","breakdown":{"subtotal":4347,"taxes":[{"name":"Sales Tax","rate":5}]}},"length":12,"type":"automatic","frequency":"monthly","onUpdate":"continue","onDelete":"complete","customFieldNames":["yourCustomField"]}'
Response
application/json
{
  "paymentPlanId": "PlanRef8765",
  "processingTerminalId": "1234001",
  "name": "Premium Club",
  "description": "Monthly Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Monthly Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    }
  },
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "onUpdate": "continue",
  "onDelete": "complete",
  "customFieldNames": [
    "yourCustomField"
  ]
}

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/1234001/payment-plans \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "paymentPlanId": "PlanRef8765",
      "processingTerminalId": "1234001",
      "name": "Premium Club",
      "description": "Monthly Premium Club subscription",
      "currency": "USD",
      "length": 12,
      "type": "automatic",
      "frequency": "monthly",
      "onUpdate": "continue",
      "onDelete": "complete"
    },
    {
      "paymentPlanId": "PlanRef8766",
      "processingTerminalId": "1234001",
      "name": "Pie It Forward",
      "description": "Pie It Forward charitable trust donation",
      "currency": "USD",
      "length": 0,
      "type": "automatic",
      "frequency": "yearly",
      "onUpdate": "continue",
      "onDelete": "complete",
      "customFieldNames": [
        "yourCustomField"
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&after=PlanRef8766"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1001/payment-plans?limit=2&before=PlanRef8765"
    }
  ]
}

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/1234001/payment-plans/PlanRef8765 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "paymentPlanId": "PlanRef8765",
  "processingTerminalId": "1234001",
  "name": "Premium Club",
  "description": "Monthly Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Monthly Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    }
  },
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "onUpdate": "continue",
  "onDelete": "complete",
  "customFieldNames": [
    "yourCustomField"
  ]
}

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. Structure your request to follow the RFC 6902 standard.

Path parameters

Header parameters

Body parameters

array of Patch Operations
Type

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/1234001/payment-plans/PlanRef8765 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '[{"op":"replace","path":"/currency","value":"USD"},{"op":"replace","path":"/setupOrder/amount","value":2999},{"op":"replace","path":"/frequency","value":"yearly"}]'
Response
application/json
{
  "paymentPlanId": "PlanRef8765",
  "processingTerminalId": "1234001",
  "name": "Premium Club",
  "description": "Monthly Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Monthly Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    }
  },
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "onUpdate": "continue",
  "onDelete": "complete",
  "customFieldNames": [
    "yourCustomField"
  ]
}

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/1234001/payment-plans/PlanRef8765 \
	--header 'Authorization: Bearer <access token>'

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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"channel":"web","processingTerminalId":"1234001","operator":"Postman","order":{"orderId":"OrderRef6543","description":"Large Pepperoni Pizza","currency":"USD","amount":4999},"customer":{"firstName":"Sarah","lastName":"Hopper","billingAddress":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"shippingAddress":{"recipientName":"Sarah Hopper","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"}}},"paymentMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"model":"paxA80","serialNumber":"WPC202833004712"},"expiryDate":"1225","cardNumber":"4539858876047062"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Postman",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "paymentId": "M2MJOG6O2Y",
      "processingTerminalId": "1234001",
      "operator": "Automatic Payment",
      "order": {
        "orderId": "OrderRef6543",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Monthly Premium Club subscription",
        "amount": 4999,
        "currency": "USD"
      },
      "card": {
        "type": "Visa Credit",
        "cardholderName": "Sarah Hopper",
        "cardNumber": "453985******7062",
        "expiryDate": "1225",
        "secureToken": {
          "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
          "customerName": "Sarah Hopper",
          "token": "296753123456",
          "status": "notValidated",
          "link": {
            "rel": "self",
            "method": "GET",
            "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
          }
        },
        "securityChecks": {
          "cvvResult": "M",
          "avsResult": "X"
        }
      },
      "supportedOperations": [
        "fullyReverse",
        "setAsPending"
      ],
      "transactionResult": {
        "type": "sale",
        "status": "ready",
        "approvalCode": "OK3",
        "authorizedAmount": 4999,
        "currency": "USD",
        "responseCode": "A",
        "responseMessage": "APPROVAL"
      }
    },
    {
      "paymentId": "E29U8OU8Q4",
      "processingTerminalId": "1234001",
      "operator": "Automatic Payment",
      "order": {
        "orderId": "OrderRef7654",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Monthly Premium Club subscription",
        "amount": 4999,
        "currency": "USD"
      },
      "card": {
        "type": "Visa Debit",
        "cardholderName": "Sarah Hopper",
        "cardNumber": "453985******7062",
        "expiryDate": "1225",
        "secureToken": {
          "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
          "customerName": "Sarah Hopper",
          "token": "296753123456",
          "status": "notValidated",
          "link": {
            "rel": "self",
            "method": "GET",
            "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
          }
        },
        "securityChecks": {
          "cvvResult": "M",
          "avsResult": "X"
        }
      },
      "supportedOperations": [
        "fullyReverse",
        "setAsPending"
      ],
      "transactionResult": {
        "type": "sale",
        "status": "ready",
        "approvalCode": "475318",
        "authorizedAmount": 1000,
        "currency": "EUR",
        "responseCode": "A",
        "responseMessage": "APPROVAL"
      },
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/payments?processingTerminalId=1234001&limit=2&after=E29U8OU8Q4"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/payments?processingTerminalId=1234001&limit=2&before=M2MJOG6O2Y"
    }
  ]
}

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/M2MJOG6O2Y \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Postman",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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.

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/M2MJOG6O2Y/adjust \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"adjustments":[{"type":"customer","shippingAddress":{"recipientName":"Sarah Hopper","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"}}},{"type":"order","amount":3999}]}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Example payment",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK6",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK6"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/M2MJOG6O2Y/capture \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"processingTerminalId":"abc123","operator":"Jane","amount":4999,"breakdown":{"subtotal":2899,"cashbackAmount":0,"tip":{"type":"percentage","amount":0,"percentage":0},"taxes":[{"name":"Sales Tax","rate":7}],"surcharge":{"bypass":false},"dualPricing":{"offered":false,"alternativeTender":"card"},"dutyAmount":0,"freightAmount":0,"items":[{"commodityCode":"5812-0111","productCode":"PZA-001-LG","description":"Large Pepperoni Pizza","unitOfMeasure":"QAN","unitPrice":2709,"quantity":1,"discountRate":5,"taxes":[{"name":"Sales Tax","rate":7}]}]}}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Postman",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/M2MJOG6O2Y/reverse \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"amount":4999}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "USA",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "IT",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "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"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/M2MJOG6O2Y/refund \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"amount":4999,"description":"Refund for order OrderRef6543"}'
Response
application/json
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Jane",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "refunds": [
    {
      "refundId": "CD3HN88U9F",
      "dateTime": "2024-07-02T15:30:00Z",
      "amount": -4999,
      "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": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK13"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "acb123"
    }
  ]
}

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 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","description":"Refund for order OrderRef6543","amount":4999,"currency":"USD"},"channel":"web","refundMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"type":"PAX_A920_PRO","serialNumber":"1850010868"},"expiryDate":"1225","cardNumber":"4539858876047062"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "transactionResult": {
    "type": "refund",
    "status": "ready",
    "approvalCode": "000000",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK5"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "refundId": "CD3HN88U9F",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef6543",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Refund for order OrderRef6543",
        "amount": 4999,
        "currency": "USD"
      },
      "card": {
        "type": "Visa Credit",
        "cardNumber": "453985******7062",
        "expiryDate": "1225"
      },
      "transactionResult": {
        "type": "refund",
        "status": "ready",
        "approvalCode": "000000",
        "authorizedAmount": -4999,
        "currency": "USD",
        "responseCode": "A",
        "responseMessage": "APPROVAL"
      }
    },
    {
      "refundId": "B6ZOFZNVOP",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef7654",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Refund for order OrderRef7654",
        "amount": 3999,
        "currency": "USD"
      },
      "card": {
        "type": "MasterCard",
        "cardNumber": "500165******0000",
        "expiryDate": "0328"
      },
      "transactionResult": {
        "type": "refund",
        "status": "reversal",
        "approvalCode": "000000",
        "authorizedAmount": -3999,
        "currency": "USD",
        "responseCode": "A",
        "responseMessage": "APPROVAL"
      },
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/refunds?processingTerminalId=1234001&limit=2&after=B6ZOFZNVOP"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/refunds?processingTerminalId=1234001&limit=2&before=CD3HN88U9F"
    }
  ]
}

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/CD3HN88U9F \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "transactionResult": {
    "type": "refund",
    "status": "ready",
    "approvalCode": "000000",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK5"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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.

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/CD3HN88U9F/adjust \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"operator":"Jane","adjustments":[{"type":"customer","contactMethods":[{"type":"mobile","value":"8445558735"}]}]}'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "operator": "Jane",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "contactMethods": [
      {
        "type": "mobile",
        "value": "8445558735"
      }
    ]
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "transactionResult": {
    "type": "refund",
    "status": "ready",
    "approvalCode": "000000",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK13"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/CD3HN88U9F/reverse \
	--header 'Authorization: Bearer <access token>' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324'
Response
application/json
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "transactionResult": {
    "type": "refund",
    "status": "reversal",
    "approvalCode": "000000",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "APPROVAL"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/1234001/secure-tokens \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"operator":"Jane","mitAgreement":"unscheduled","customer":{"firstName":"Sarah","lastName":"Hopper","dateOfBirth":"1990-07-15","referenceNumber":"Customer-12","billingAddress":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"shippingAddress":{"recipientName":"Sarah Hopper","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"}},"contactMethods":[{"type":"email","value":"sarah.hopper@example.com"}],"notificationLanguage":"en"},"ipAddress":{"type":"ipv4","value":"104.18.24.203"},"source":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Sarah Hazel Hopper","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1225","cvv":"234"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "source": {
    "type": "card",
    "cardholderName": "Sarah Hazel Hopper",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "token": "296753123456",
  "status": "notValidated",
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/1234001/secure-tokens \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "processingTerminalId": "1234001",
      "mitAgreement": "unscheduled",
      "customer": {
        "firstName": "Sarah",
        "lastName": "Hopper",
        "dateOfBirth": "1990-07-15",
        "referenceNumber": "Customer-12",
        "billingAddress": {
          "address1": "1 Example Ave.",
          "address2": "Example Address Line 2",
          "address3": "Example Address Line 3",
          "city": "Chicago",
          "state": "Illinois",
          "country": "US",
          "postalCode": "60056"
        },
        "shippingAddress": {
          "recipientName": "Sarah Hopper",
          "address": {
            "address1": "1 Example Ave.",
            "address2": "Example Address Line 2",
            "address3": "Example Address Line 3",
            "city": "Chicago",
            "state": "Illinois",
            "country": "US",
            "postalCode": "60056"
          }
        }
      },
      "source": {
        "type": "card",
        "cardholderName": "Sarah Hopper",
        "cardNumber": "453985******7062",
        "expiryDate": "1225"
      },
      "token": "296753123456",
      "status": "notValidated"
    },
    {
      "secureTokenId": "MREF_fe0d9876-cba5-432f-e10d-9cb87654a3f2e1",
      "processingTerminalId": "1234001",
      "mitAgreement": "unscheduled",
      "customer": {
        "firstName": "Sarah",
        "lastName": "Hopper",
        "dateOfBirth": "1990-07-15",
        "referenceNumber": "Customer-12",
        "billingAddress": {
          "address1": "1 Example Ave.",
          "address2": "Example Address Line 2",
          "address3": "Example Address Line 3",
          "city": "Chicago",
          "state": "Illinois",
          "country": "US",
          "postalCode": "60056"
        },
        "shippingAddress": {
          "recipientName": "Sarah Hopper",
          "address": {
            "address1": "1 Example Ave.",
            "address2": "Example Address Line 2",
            "address3": "Example Address Line 3",
            "city": "Chicago",
            "state": "Illinois",
            "country": "US",
            "postalCode": "60056"
          }
        }
      },
      "source": {
        "type": "card",
        "cardholderName": "Sarah Hazel Hopper",
        "cardNumber": "500165******0000",
        "expiryDate": "0328"
      },
      "token": "307864234567",
      "status": "notValidated",
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens?limit=2&after=MREF_fe0d9876-cba5-432f-e10d-9cb87654a3f2e1"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens?limit=2&before=MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  ]
}

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/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "source": {
    "type": "card",
    "cardholderName": "Sarah Hazel Hopper",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "token": "296753123456",
  "status": "notValidated",
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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.

Update secure token

PATCH /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}
Update the customer's payment details that are represented by the secure token. Structure your request to follow the RFC 6902 standard.

Path parameters

Header parameters

Body parameters

array of Patch Operations
Type

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/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '[{"op":"replace","path":"/customer/lastName","value":"Reed"},{"op":"replace","path":"/shippingAddress/recipientName","value":"Sarah Reed"},{"op":"replace","path":"/source/cardDetails/cardholderName","value":"Sarah Reed"}]'
Response
application/json
{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "source": {
    "type": "card",
    "cardholderName": "Sarah Hazel Hopper",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "token": "296753123456",
  "status": "notValidated",
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
	--header 'Authorization: Bearer <access token>'

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 account details

POST /processing-terminals/{processingTerminalId}/secure-tokens/{secureTokenId}/update-account
If you have a single-use token, use this method to update payment details that are represented by a secure token. If you don’t have a single-use token, and you want to update payment details represented by a secure token, go to updateSecureToken. Note: For more information about tokenization, go to tokenization.

Path parameters

Header parameters

Body parameters

Response Schema

Status Code 200

Successful request. We updated the payment details represented by the secure token.
Response body
Request
curl --request post \
	--url https://api.payroc.com/v1/processing-terminals/abc123/secure-tokens/abc123/update-account \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"type":"singleUseToken","token":"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"}'
Response
application/json
{
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
  "processingTerminalId": "1234001",
  "mitAgreement": "unscheduled",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "dateOfBirth": "1990-07-15",
    "referenceNumber": "Customer-12",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    },
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "source": {
    "type": "card",
    "cardholderName": "Sarah Hazel Hopper",
    "cardNumber": "453985******7062",
    "expiryDate": "1225"
  },
  "token": "296753123456",
  "status": "notValidated",
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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
Resource already exists
Resource already exists
Payload too large
The payload submitted is too large
Unsupported media type
The payload is in an unsupported format.
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/1234001/single-use-tokens \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"channel":"web","operator":"Jane","source":{"type":"card","cardDetails":{"entryMethod":"keyed","cardholderName":"Sarah Hazel Hopper","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","expiryDate":"1225","cvv":"234"}}}}'
Response
application/json
{
  "processingTerminalId": "1234001",
  "token": "fa2e9e51bc5265a33a5ca41449524d53d1def596ffd8c0904f222183a71a65cdb58835120a65196a48a6375abc4deafe2b7e948689ab9d6aba919e860f32e247",
  "expiresAt": "2024-08-05T19:50:05.723+02:00",
  "source": {
    "type": "card",
    "cardholderName": "Sarah Hazel Hopper",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "cardType": "Visa Credit",
    "country": "US",
    "currency": "USD",
    "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/1234001/subscriptions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"subscriptionId":"SubRef7654","paymentPlanId":"PlanRef8765","paymentMethod":{"type":"secureToken","token":"296753123456"},"name":"Premium Club","description":"Premium Club subscription","setupOrder":{"amount":4999,"description":"Initial setup fee for Premium Club subscription","breakdown":{"subtotal":4347,"taxes":[{"name":"Sales Tax","rate":5}]},"orderId":"OrderRef6543"},"recurringOrder":{"amount":4999,"description":"Monthly Premium Club subscription","breakdown":{"subtotal":4347,"taxes":[{"name":"Sales Tax","rate":5}]}},"startDate":"2024-07-02","endDate":"2025-07-01","length":12,"pauseCollectionFor":0,"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "subscriptionId": "SubRef7654",
  "processingTerminalId": "1234001",
  "paymentPlan": {
    "paymentPlanId": "PlanRef8765",
    "name": "Monthly Premium Club subscription",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
    }
  },
  "secureToken": {
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "customerName": "Sarah Hazel Hopper",
    "token": "296753123456",
    "status": "notValidated",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  },
  "name": "Premium Club",
  "description": "Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "currentState": {
    "status": "active",
    "nextDueDate": "2024-08-02",
    "paidInvoices": 0,
    "outstandingInvoices": 3
  },
  "startDate": "2024-07-02",
  "endDate": "2025-07-01",
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "pauseCollectionFor": 0,
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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

Header 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/1234001/subscriptions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324'
Response
application/json
{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "subscriptionId": "SubRef7654",
      "processingTerminalId": "1234001",
      "paymentPlan": {
        "paymentPlanId": "PlanRef8765",
        "name": "Monthly Premium Club subscription",
        "link": {
          "rel": "self",
          "method": "GET",
          "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
        }
      },
      "secureToken": {
        "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
        "customerName": "Sarah Hazel Hopper",
        "token": "296753123456",
        "status": "notValidated",
        "link": {
          "rel": "self",
          "method": "GET",
          "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
        }
      },
      "name": "Premium Club",
      "description": "Monthly Premium Club subscription",
      "currency": "USD",
      "setupOrder": {
        "orderId": "OrderRef6543",
        "amount": 4999,
        "description": "Initial setup fee for Premium Club subscription"
      },
      "recurringOrder": {
        "amount": 4999
      },
      "currentState": {
        "status": "active",
        "nextDueDate": "2024-08-02",
        "paidInvoices": 1,
        "outstandingInvoices": 11
      },
      "startDate": "2024-07-02",
      "endDate": "2025-08-01",
      "length": 0,
      "type": "automatic",
      "frequency": "monthly",
      "pauseCollectionFor": 0
    },
    {
      "subscriptionId": "SubRef8543",
      "processingTerminalId": "1234001",
      "paymentPlan": {
        "paymentPlanId": "PlanRef7654",
        "name": "Pie it Forward charitable trust donation",
        "link": {
          "rel": "self",
          "method": "GET",
          "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef7654"
        }
      },
      "secureToken": {
        "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
        "customerName": "Sarah Hazel Hopper",
        "token": "296753123456",
        "status": "notValidated",
        "link": {
          "rel": "self",
          "method": "GET",
          "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
        }
      },
      "name": "Pie It Forward",
      "description": "Pie It Forward charitable trust donation",
      "currency": "USD",
      "setupOrder": {
        "orderId": "OrderRef7654",
        "amount": 3999
      },
      "recurringOrder": {
        "amount": 3999
      },
      "currentState": {
        "status": "active",
        "nextDueDate": "2024-04-11",
        "paidInvoices": 1,
        "outstandingInvoices": 11
      },
      "startDate": "2024-07-02",
      "endDate": "2024-07-02",
      "length": 0,
      "type": "automatic",
      "frequency": "yearly",
      "pauseCollectionFor": 0,
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/subscriptions?limit=2&after=SubRef8543"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/subscriptions?limit=2&before=SubRef7654"
    }
  ]
}

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/1234001/subscriptions/SubRef7654 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "subscriptionId": "SubRef7654",
  "processingTerminalId": "1234001",
  "paymentPlan": {
    "paymentPlanId": "PlanRef8765",
    "name": "Monthly Premium Club subscription",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
    }
  },
  "secureToken": {
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "customerName": "Sarah Hazel Hopper",
    "token": "296753123456",
    "status": "notValidated",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  },
  "name": "Premium Club",
  "description": "Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "currentState": {
    "status": "active",
    "nextDueDate": "2024-08-02",
    "paidInvoices": 0,
    "outstandingInvoices": 3
  },
  "startDate": "2024-07-02",
  "endDate": "2025-07-01",
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "pauseCollectionFor": 0,
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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.

Update subscription

PATCH /processing-terminals/{processingTerminalId}/subscriptions/{subscriptionId}
Make changes to a subscription. Structure your request to follow the RFC 6902 standard.

Path parameters

Header parameters

Body parameters

array of Patch Operations
Type

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/1234001/subscriptions/SubRef7654 \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '[{"op":"replace","path":"/setupOrder/amount","value":2999},{"op":"replace","path":"/recurringOrder/amount","value":2999},{"op":"replace","path":"/frequency","value":"yearly"}]'
Response
application/json
{
  "subscriptionId": "SubRef7654",
  "processingTerminalId": "1234001",
  "paymentPlan": {
    "paymentPlanId": "PlanRef8765",
    "name": "Monthly Premium Club subscription",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
    }
  },
  "secureToken": {
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "customerName": "Sarah Hazel Hopper",
    "token": "296753123456",
    "status": "notValidated",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  },
  "name": "Premium Club",
  "description": "Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "currentState": {
    "status": "active",
    "nextDueDate": "2024-08-02",
    "paidInvoices": 0,
    "outstandingInvoices": 3
  },
  "startDate": "2024-07-02",
  "endDate": "2025-07-01",
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "pauseCollectionFor": 0,
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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/1234001/subscriptions/SubRef7654/deactivate \
	--header 'Authorization: Bearer <access token>'
Response
application/problem+json
{
  "subscriptionId": "SubRef7654",
  "processingTerminalId": "1234001",
  "paymentPlan": {
    "paymentPlanId": "PlanRef8765",
    "name": "Monthly Premium Club subscription",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
    }
  },
  "secureToken": {
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "customerName": "Sarah Hazel Hopper",
    "token": "296753123456",
    "status": "notValidated",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  },
  "name": "Premium Club",
  "description": "Monthly Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Monthly Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "currentState": {
    "status": "cancelled",
    "nextDueDate": "2024-08-02",
    "paidInvoices": 0,
    "outstandingInvoices": 3
  },
  "startDate": "2024-07-02",
  "endDate": "2025-07-01",
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "pauseCollectionFor": 0,
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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
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/1234001/subscriptions/SubRef7654/reactivate \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "subscriptionId": "SubRef7654",
  "processingTerminalId": "1234001",
  "paymentPlan": {
    "paymentPlanId": "PlanRef8765",
    "name": "Monthly Premium Club subscription",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765"
    }
  },
  "secureToken": {
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "customerName": "Sarah Hazel Hopper",
    "token": "296753123456",
    "status": "notValidated",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  },
  "name": "Premium Club",
  "description": "Premium Club subscription",
  "currency": "USD",
  "setupOrder": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "description": "Initial setup fee for Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "recurringOrder": {
    "amount": 4999,
    "description": "Premium Club subscription",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "surcharge": {
        "amount": 217,
        "percentage": 5
      }
    }
  },
  "currentState": {
    "status": "active",
    "nextDueDate": "2024-08-02",
    "paidInvoices": 0,
    "outstandingInvoices": 3
  },
  "startDate": "2024-07-02",
  "endDate": "2025-07-01",
  "length": 12,
  "type": "automatic",
  "frequency": "monthly",
  "pauseCollectionFor": 0,
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "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
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/1234001/subscriptions/SubRef7654/pay \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"operator":"Jane","order":{"amount":4999,"description":"Monthly Premium Club subscription","breakdown":{"subtotal":4999,"taxes":[{"name":"Sales Tax","rate":5}]},"orderId":"OrderRef6543"},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
Response
application/json
{
  "subscriptionId": "SubRef7654",
  "processingTerminalId": "1234001",
  "payment": {
    "paymentId": "M2MJOG6O2Y",
    "dateTime": "2024-07-02T15:30:00Z",
    "amount": 4999,
    "currency": "USD",
    "status": "ready",
    "responseCode": "A",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y"
    }
  },
  "secureToken": {
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "customerName": "Sarah Hazel Hopper",
    "token": "296753123456",
    "status": "notValidated",
    "link": {
      "rel": "self",
      "method": "GET",
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    }
  },
  "currentState": {
    "status": "active",
    "nextDueDate": "2024-08-02",
    "paidInvoices": 1,
    "outstandingInvoices": 2
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

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.

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/1850010868/payment-instructions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"operator":"Jane","processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","currency":"USD","amount":4999},"customizationOptions":{"entryMethod":"deviceRead"},"autoCapture":true}'
Response
application/json
{
  "paymentInstructionId": "a37439165d134678a9100ebba3b29597",
  "status": "inProgress",
  "link": {
    "rel": "self",
    "method": "GET",
    "href": "https://api.payroc.com/v1/payment-instructions/a37439165d134678a9100ebba3b29597"
  }
}

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/e743a9165d134678a9100ebba3b29597 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "paymentInstructionId": "a37439165d134678a9100ebba3b29597",
  "status": "completed",
  "link": {
    "rel": "payment",
    "method": "GET",
    "href": "https://api.payroc.com/v1/payments/M2MJOG6O2Y"
  }
}

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/1850010868/refund-instructions \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"operator":"Jane","processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","currency":"USD","amount":4999,"description":"Refund for order OrderRef6543"},"customizationOptions":{"entryMethod":"manualEntry"}}'
Response
application/json
{
  "refundInstructionId": "a37439165d134678a9100ebba3b29597",
  "status": "inProgress",
  "link": {
    "rel": "self",
    "method": "GET",
    "href": "https://api.payroc.com/v1/refund-instructions/a37439165d134678a9100ebba3b29597"
  }
}

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/a37439165d134678a9100ebba3b29597 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "refundInstructionId": "a37439165d134678a9100ebba3b29597",
  "status": "completed",
  "link": {
    "rel": "refund",
    "method": "GET",
    "href": "https://api.payroc.com/v1/refunds/CD3HN88U9F"
  }
}

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.

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=2027-07-02' \
	--header 'Authorization: Bearer <access token>'
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=2024-07-02"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/batches?after=66&limit=2&&date=2024-07-02"
    }
  ],
  "data": [
    {
      "batchId": 65,
      "date": "2024-07-02",
      "createdDate": "2024-07-02",
      "lastModifiedDate": "2024-07-02",
      "saleAmount": 100,
      "heldAmount": 0,
      "returnAmount": 0,
      "transactionCount": 10,
      "currency": "USD",
      "merchant": {
        "merchantId": "4525644354",
        "doingBusinessAs": "Pizza Doe",
        "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": "2024-07-02",
      "createdDate": "2024-07-02",
      "lastModifiedDate": "2024-07-02",
      "saleAmount": 76,
      "heldAmount": 0,
      "returnAmount": 12,
      "transactionCount": 10,
      "currency": "USD",
      "merchant": {
        "merchantId": "9876543219",
        "doingBusinessAs": "Joe Bloggs Shoes",
        "link": {
          "rel": "merchant",
          "method": "get",
          "href": "https://api.payroc.com/v1/merchants/9876543219"
        }
      },
      "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/12345 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "batchId": 123,
  "date": "2024-07-02",
  "createdDate": "2024-07-02",
  "lastModifiedDate": "2024-07-02",
  "saleAmount": 89,
  "heldAmount": 89,
  "returnAmount": 89,
  "transactionCount": 89,
  "currency": "abc123",
  "merchant": {
    "merchantId": "4525644354",
    "doingBusinessAs": "Doe Hot Dogs",
    "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=2024-07-01&batchId=12345' \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "limit": 2,
  "count": 1,
  "hasMore": false,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/transctions?before=442233&limit=2&date=2024-07-02"
    }
  ],
  "data": [
    {
      "transactionId": 442233,
      "type": "capture",
      "date": "2024-07-02",
      "amount": 4999,
      "entryMethod": "ecommerce",
      "createdDate": "2024-07-02",
      "lastModifiedDate": "2024-07-02",
      "status": "paid",
      "cashbackAmount": 0,
      "interchange": {
        "basisPoint": 0,
        "transactionFee": 0
      },
      "currency": "USD",
      "merchant": {
        "merchantId": "4525644354",
        "doingBusinessAs": "Pizza Doe",
        "link": {
          "rel": "merchant",
          "method": "get",
          "href": "https://api.payroc.com/v1/merchants/4525644354"
        }
      },
      "settled": {
        "settledBy": "3rd party",
        "achDate": "2024-07-02"
      },
      "batch": {
        "batchId": 12,
        "date": "2024-07-02",
        "cycle": "am",
        "link": {
          "rel": "batch",
          "method": "get",
          "href": "https://api.payroc.com/v1/batches/12"
        }
      },
      "card": {
        "cardNumber": "453985******7062",
        "type": "visa",
        "cvvPresenceIndicator": true,
        "avsRequest": true,
        "avsResponse": ""
      },
      "authorization": {
        "authorizationId": 303101,
        "code": "A1B2C3",
        "amount": 4999,
        "avsResponseCode": "",
        "link": {
          "rel": "authorization",
          "method": "get",
          "href": "https://api.payroc.com/v1/authorizations/303101"
        }
      }
    }
  ]
}

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/442233 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "transactionId": 442233,
  "type": "capture",
  "date": "2024-07-02",
  "amount": 4999,
  "entryMethod": "contactlessChip",
  "createdDate": "2024-07-02",
  "lastModifiedDate": "2024-07-02",
  "status": "paid",
  "cashbackAmount": 0,
  "interchange": {
    "basisPoint": 150,
    "transactionFee": 50
  },
  "currency": "USD",
  "merchant": {
    "merchantId": "4525644354",
    "doingBusinessAs": "Doe Hot Dogs",
    "link": {
      "rel": "merchant",
      "method": "get",
      "href": "https://api.payroc.com/v1/merchants/4525644354"
    }
  },
  "settled": {
    "settledBy": "Payroc",
    "achDate": "2024-07-02"
  },
  "batch": {
    "batchId": 1234,
    "date": "2024-07-02",
    "cycle": "am",
    "link": {
      "rel": "previous",
      "method": "get",
      "href": "<uri>"
    }
  },
  "card": {
    "cardNumber": "123456**********4124",
    "type": "visa",
    "cvvPresenceIndicator": false,
    "avsRequest": false,
    "avsResponse": "abc123"
  },
  "authorization": {
    "authorizationId": 303101,
    "code": "A1B2C3",
    "amount": 4999,
    "avsResponseCode": "Y",
    "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=2024-07-01&batchId=12345' \
	--header 'Authorization: Bearer <access token>'
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=2024-07-02"
    }
  ],
  "data": [
    {
      "authorizationId": 65,
      "createdDate": "2024-07-02",
      "lastModifiedDate": "2024-07-02",
      "authorizationResponse": "successful",
      "preauthorizationRequestAmount": 10000,
      "currency": "USD",
      "merchant": {
        "merchantId": "4525644354",
        "doingBusinessAs": "Pizza Doe",
        "link": {
          "rel": "merchant",
          "method": "get",
          "href": "https://api.payroc.com/v1/merchants/4525644354"
        }
      },
      "batch": {
        "batchId": 12,
        "date": "2024-07-02",
        "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/12345 \
	--header 'Authorization: Bearer <access token>'
Response
application/json
{
  "authorizationId": 12345,
  "createdDate": "2024-01-30",
  "lastModifiedDate": "2024-01-30",
  "authorizationResponse": "activityCountLimitExceeded",
  "preauthorizationRequestAmount": 10000,
  "currency": "abc123",
  "batch": {
    "batchId": 1234,
    "date": "2024-07-02",
    "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": "Doe Hot Dogs",
    "link": {
      "rel": "merchant",
      "method": "get",
      "href": "https://api.payroc.com/v1/merchants/4525644354"
    }
  },
  "transaction": {
    "transactionId": 12345,
    "type": "capture",
    "date": "2024-07-02",
    "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=2024-07-02' \
	--header 'Authorization: Bearer <access token>'
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=2024-07-02"
    }
  ],
  "data": [
    {
      "disputeId": 65,
      "disputeType": "firstDispute",
      "currentStatus": {
        "disputeStatusId": 123,
        "status": "new",
        "statusDate": "2024-07-02",
        "link": {
          "rel": "statuses",
          "method": "get",
          "href": "https://api.payroc.com/v1/disputes/65/statuses"
        }
      },
      "createdDate": "2024-07-02",
      "lastModifiedDate": "2024-07-02",
      "receivedDate": "",
      "description": "",
      "referenceNumber": "35435435",
      "disputeAmount": 1000,
      "feeAmount": 100,
      "firstDispute": true,
      "authorizationCode": "574254",
      "currency": "USD",
      "merchant": {
        "merchantId": "4525644354",
        "doingBusinessAs": "Pizza Doe",
        "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/12345/statuses \
	--header 'Authorization: Bearer <access token>'
Response
application/json
[
  {
    "disputeStatusId": 12345,
    "status": "prearbitrationInProcess",
    "statusDate": "2024-02-01"
  }
]

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.