Take paymentsPayments

Close an ACH payment

View as Markdown

If NACHA returned an ACH payment and the merchant accepted an alternative payment method, you can use our API to close the return without re-presenting the payment to NACHA.

Note: Use this method to permanently close a return. If you want to retry the payment, use our Re-present Payment method instead.

How it works

  1. We email the merchant to let them know that NACHA returned an ACH payment.
  2. Merchant uses an alternative payment method to collect payment from their customer.
  3. Merchant uses their POS to close the return.

Your integration journey

  1. View the payment details.
  2. Close the return.

Things to consider

When you close a return, don’t use the paymentId that you use to retrieve the payment.

In the response of the Retrieve Payment method, our gateway includes a returns array with a new paymentId, which you need to send in the Close Return request.

1...
2"returns": [
3    {
4       "paymentId": "GIJXAU3WUJ",
5       "date": "2025-06-23",
6       "returnCode": "R01",
7       "returnReason": "Insufficient Funds",
8       "represented": false,
9       "closed": false,
10       "link": {
11          "rel": "self",
12          "method": "GET",
13          "href": "https://api.payroc.com/v1/bank-transfer-payments/GIJXAU3WUJ"
14       }
15    }
16 ],
17...

Errors

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

Step 1. View the payment details

To view the details of the return, send a GET request to our Bank Transfer Payments endpoint.

Request parameters

Path parameters

paymentIdstringRequired=10 characters
Unique identifier that our gateway assigned to the payment.

Example request

GET
/v1/bank-transfer-payments/:paymentId
1curl https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y \
2     -H "Authorization: Bearer <token>"
Try it

Response fields

Important: Save the paymentId from the returns object for closing the payment.

If your request is successful, our gateway sends a returns object that contains a returnCode field and a returnReason field that indicates the reason the payment was returned.

Response

paymentIdstringRequired=10 characters
Unique identifier that we assigned to the payment.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the transaction.
bankAccountobjectRequired
Polymorphic object that contains bank account information. The value of the type field determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details
transactionResultobjectRequiredRead-only
Object that contains information about the transaction.
customerobjectOptional
Object that contains information about the customer.
refundslist of objectsOptional
List of refunds issued against the payment.
returnslist of objectsOptional
List of returns issued against the payment.
representmentobjectOptional
Object that contains details about the re-presented payment linked to the return.
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
1{
2  "paymentId": "E29U8OU8Q4",
3  "processingTerminalId": "1234001",
4  "order": {
5    "amount": 4999,
6    "currency": "USD",
7    "orderId": "OrderRef7654",
8    "breakdown": {
9      "subtotal": 4347,
10      "taxes": [
11        {
12          "name": "Sales Tax",
13          "rate": 5,
14          "amount": 217
15        }
16      ],
17      "tip": {
18        "type": "percentage",
19        "amount": 435,
20        "percentage": 10
21      }
22    },
23    "dateTime": "2024-07-02T15:30:00Z",
24    "description": "Large Pepperoni Pizza"
25  },
26  "bankAccount": {
27    "type": "ach",
28    "accountNumber": "****1591",
29    "nameOnAccount": "Sarah Hazel Hopper",
30    "routingNumber": "053200983",
31    "secCode": "web"
32  },
33  "transactionResult": {
34    "type": "payment",
35    "status": "declined",
36    "responseCode": "D",
37    "authorizedAmount": 4999,
38    "currency": "USD",
39    "responseMessage": "Payment Declined",
40    "processorResponseCode": "R11"
41  },
42  "customer": {
43    "notificationLanguage": "en",
44    "contactMethods": [
45      {
46        "type": "email",
47        "value": "[email protected]"
48      }
49    ]
50  },
51  "returns": [
52    {
53      "paymentId": "M2MJOG6O2Y",
54      "date": "2024-07-02",
55      "returnCode": "R11",
56      "returnReason": "Customer advises not authorized",
57      "represented": false,
58      "closed": false,
59      "link": {
60        "rel": "self",
61        "method": "GET",
62        "href": "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y"
63      }
64    }
65  ]
66}

Step 2. Close the return

To close the return, send a POST request to our Bank Transfer Payments endpoint.

Request parameters

Path parameters

paymentIdstringRequired=10 characters
Unique identifier that our gateway assigned to the payment.

Example request

POST
/v1/bank-transfer-payments/:paymentId/close
1curl -X POST https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y/close \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>"
Try it

Response fields

If your request is successful, our gateway closes the return.

Response

paymentIdstringRequired=10 characters
Unique identifier that we assigned to the payment.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the transaction.
bankAccountobjectRequired
Polymorphic object that contains bank account information. The value of the type field determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `pad` - Pre-authorized debit (PAD) details
transactionResultobjectRequiredRead-only
Object that contains information about the transaction.
customerobjectOptional
Object that contains information about the customer.
refundslist of objectsOptional
List of refunds issued against the payment.
returnslist of objectsOptional
List of returns issued against the payment.
representmentobjectOptional
Object that contains details about the re-presented payment linked to the return.
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
1{
2  "paymentId": "M2MJOG6O2Y",
3  "processingTerminalId": "1234001",
4  "order": {
5    "amount": 4999,
6    "currency": "USD",
7    "orderId": "OrderRef6543",
8    "breakdown": {
9      "subtotal": 4347,
10      "taxes": [
11        {
12          "name": "Sales Tax",
13          "rate": 5,
14          "amount": 217
15        }
16      ],
17      "tip": {
18        "type": "percentage",
19        "amount": 435,
20        "percentage": 10
21      }
22    },
23    "dateTime": "2024-07-02T15:30:00Z",
24    "description": "Large Pepperoni Pizza"
25  },
26  "bankAccount": {
27    "type": "ach",
28    "accountNumber": "****3159",
29    "nameOnAccount": "Sarah Hazel Hopper",
30    "routingNumber": "053200983",
31    "secCode": "web",
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  },
44  "transactionResult": {
45    "type": "payment",
46    "status": "ready",
47    "responseCode": "A",
48    "authorizedAmount": 4999,
49    "currency": "USD",
50    "responseMessage": "NoError",
51    "processorResponseCode": "0"
52  },
53  "customer": {
54    "notificationLanguage": "en",
55    "contactMethods": [
56      {
57        "type": "email",
58        "value": "[email protected]"
59      }
60    ]
61  },
62  "customFields": [
63    {
64      "name": "yourCustomField",
65      "value": "abc123"
66    }
67  ]
68}