Integration steps

Create a bank transfer payment.

Before you begin

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

Include your API key in the x-api-key parameter in the header of a POST request.
Send your request to https://identity.payroc.com/authorize.

You need to generate a new Bearer token before the previous Bearer token expires.

Example request

curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

Headers

To create the header of each POST request, you must include the following parameters:

Content-Type: Include application/json as the value for this parameter.
Authorization: Include your Bearer token in this parameter.
Idempotency-Key: Include a UUID v4 to make the request idempotent.

curl
-H "Content-Type: application/json"
-H "Authorization: <Bearer token>"
-H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, see Errors.

Create a bank transfer payment

To create a bank transfer payment, send a POST request to our Bank Transfer Payments endpoint. Test endpoint: https://api.uat.payroc.com/v1/bank-transfer-payments
Production endpoint: https://api.payroc.com/v1/bank-transfer-payments

Request parameters

To create the body of your request, use the following parameters:

Header parameters

Body parameters

Example request

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":"[email protected]"}]},"credentialOnFile":{"tokenize":true},"paymentMethod":{"type":"ach","accountType":"checking","nameOnAccount":"Sarah Hazel Hopper","accountNumber":"32183159","routingNumber":"063100277","secCode":"web"},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'

Response fields

If your request is successful, we create the payment and return the following response:

Response Schema

Status Code 201

Successful request. We processed the sale.

Response headers

Response body

Example response

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": "[email protected]"
      }
    ],
    "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"
    }
  ]
}

Test cases

Before you run test cases, read the Payments page in Test Your Integration.

Run a sale with bank account details

Send a POST request to the following endpoint: POST https://api.uat.payroc.com/v1/bank-transfer-payments Example response

{
    "channel": "POS",
    "processingTerminalId": "3204001",
    "operator": "Davi-CHP",
    "order": {
        "orderId": "CC-12",
        "description": "BT ACH - Sale with CC",
        "currency": "USD",
        "amount": 9700
    },
    "paymentMethod": {
        "type": "ach",
        "accountType": "checking",
        "secCode": "web",
        "nameOnAccount": "Davi",
        "accountNumber": "49100130",
        "routingNumber": "292735277"
    }
}