IntegratePayments

Run a sale with bank account details

Our gateway supports the following bank transfer services:

  • Automated Clearing House (ACH): A service that U.S. banks use to transfer funds between accounts.
  • Pre-Authorized Debit (PAD): A service that Canadian banks use to transfer funds between accounts.

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:

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

Note: 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.

1{
2  "access_token": "eyJhbGc....adQssw5c",
3  "expires_in": 3600,
4  "scope": "service_a service_b",
5  "token_type": "Bearer"
6}

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.

Request parameters

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

Example request

POST
/v1/bank-transfer-payments
1curl -X POST https://api.payroc.com/v1/bank-transfer-payments \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "processingTerminalId": "1234001",
7  "order": {
8    "orderId": "OrderRef6543",
9    "amount": 4999,
10    "currency": "USD",
11    "description": "Large Pepperoni Pizza",
12    "breakdown": {
13      "subtotal": 4347,
14      "tip": {
15        "type": "percentage",
16        "percentage": 10
17      },
18      "taxes": [
19        {
20          "name": "Sales Tax",
21          "rate": 5
22        }
23      ]
24    }
25  },
26  "paymentMethod": {
27    "type": "ach",
28    "accountType": "checking",
29    "secCode": "web",
30    "nameOnAccount": "Sarah Hazel Hopper",
31    "accountNumber": "321831591",
32    "routingNumber": "063100277"
33  },
34  "customer": {
35    "notificationLanguage": "en",
36    "contactMethods": [
37      {
38        "type": "email",
39        "value": "[email protected]"
40      }
41    ]
42  },
43  "credentialOnFile": {
44    "tokenize": true
45  },
46  "customFields": [
47    {
48      "name": "yourCustomField",
49      "value": "abc123"
50    }
51  ]
52}'

Response fields

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

Example response

Response
1{
2  "paymentId": "M2MJOG6O2Y",
3  "processingTerminalId": "1234001",
4  "order": {
5    "orderId": "OrderRef6543",
6    "amount": 4999,
7    "currency": "USD",
8    "dateTime": "2024-07-02T15:30:00Z",
9    "description": "Large Pepperoni Pizza",
10    "breakdown": {
11      "subtotal": 4347,
12      "tip": {
13        "type": "percentage",
14        "amount": 435,
15        "percentage": 10
16      },
17      "taxes": [
18        {
19          "name": "Sales Tax",
20          "rate": 5,
21          "amount": 217
22        }
23      ]
24    }
25  },
26  "bankAccount": {
27    "type": "ach",
28    "secCode": "web",
29    "nameOnAccount": "Sarah Hazel Hopper",
30    "accountNumber": "****3159",
31    "routingNumber": "063100277",
32    "secureToken": {
33      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
34      "customerName": "Sarah Hazel Hopper",
35      "token": "296753123456",
36      "status": "notValidated",
37      "link": {
38        "rel": "self",
39        "method": "GET",
40        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
41      }
42    },
43    "accountType": "checking"
44  },
45  "transactionResult": {
46    "type": "payment",
47    "status": "ready",
48    "responseMessage": "NoError",
49    "authorizedAmount": 4999,
50    "currency": "USD",
51    "responseCode": "A",
52    "processorResponseCode": "0"
53  },
54  "customer": {
55    "notificationLanguage": "en",
56    "contactMethods": [
57      {
58        "type": "email",
59        "value": "[email protected]"
60      }
61    ]
62  },
63  "customFields": [
64    {
65      "name": "yourCustomField",
66      "value": "abc123"
67    }
68  ]
69}

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

1{
2    "channel": "POS",
3    "processingTerminalId": "3204001",
4    "operator": "Davi-CHP",
5    "order": {
6        "orderId": "CC-12",
7        "description": "BT ACH - Sale with CC",
8        "currency": "USD",
9        "amount": 9700
10    },
11    "paymentMethod": {
12        "type": "ach",
13        "accountType": "checking",
14        "secCode": "web",
15        "nameOnAccount": "Davi",
16        "accountNumber": "49100130",
17        "routingNumber": "292735277"
18    }
19}