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}