Take paymentsPayments

Re-present an ACH payment

View as MarkdownOpen in Claude

If an ACH payment has failed, we send an email to the merchant to let them know that the payment has failed. You can integrate with our API return the reason that the payment failed and then re-present the payment.

Note: When the merchant views the reason why the payment failed, they might have to contact their customer to fix the issue before they can re-present the payment.

How it works

  1. We email the merchant to let them know that an ACH payment has failed.
  2. Merchant uses their POS to view the details of the payment and the reason the payment has failed.
  3. Merchant contacts their customer to fix the issue.
  4. Merchant uses their POS to re-present the payment.

Your integration journey

  1. View the payment details.
  2. Re-present the payment.
  3. (Optional) Re-present the payment again.

Note: You can re-present a payment up to two times.

Things to consider

When you re-present a payment, don’t use the same paymentId that you use to retrieve the payment.

In the response of the Retrieve Payment method, our gateway sends a returns object with a new paymentId, which you need to send in the Re-present Payment request.

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

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 reason why the payment failed, 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
1using Payroc;
2using System.Threading.Tasks;
3using Payroc.BankTransferPayments.Payments;
4
5namespace Usage;
6
7public class Example
8{
9    public async Task Do() {
10        var client = new BasePayrocClient(
11            clientOptions: new ClientOptions {
12                Environment = PayrocEnvironment.Production
13            }
14        );
15
16        await client.BankTransferPayments.Payments.RetrieveAsync(
17            new RetrievePaymentsRequest {
18                PaymentId = "M2MJOG6O2Y"
19            }
20        );
21    }
22
23}
Try it

Response fields

Important: Save the paymentId from the returns object for the re-presentment.

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 failed.

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
List of re-presented payments 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    "accountType": "checking"
33  },
34  "transactionResult": {
35    "type": "payment",
36    "status": "declined",
37    "currency": "USD",
38    "responseCode": "D",
39    "authorizedAmount": 4999,
40    "responseMessage": "Payment Declined",
41    "processorResponseCode": "R11"
42  },
43  "customer": {
44    "notificationLanguage": "en",
45    "contactMethods": [
46      {
47        "type": "email",
48        "value": "[email protected]"
49      }
50    ]
51  },
52  "returns": [
53    {
54      "paymentId": "M2MJOG6O2Y",
55      "date": "2024-07-02",
56      "returnCode": "R11",
57      "returnReason": "Customer advises not authorized",
58      "represented": 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. Re-present the payment

To retry the payment, 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.

Request

paymentMethodobjectOptional
Polymorphic object that contains the customer's updated payment details. The value of the type parameter determines which variant you should use: - `ach` - Automated Clearing House (ACH) details - `secureToken` - Secure token details

Example request

POST
/v1/bank-transfer-payments/:paymentId/represent
1using Payroc;
2using System.Threading.Tasks;
3using Payroc.BankTransferPayments.Payments;
4
5namespace Usage;
6
7public class Example
8{
9    public async Task Do() {
10        var client = new BasePayrocClient(
11            clientOptions: new ClientOptions {
12                Environment = PayrocEnvironment.Production
13            }
14        );
15
16        await client.BankTransferPayments.Payments.RepresentAsync(
17            new Representment {
18                PaymentId = "M2MJOG6O2Y",
19                IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
20                PaymentMethod = new RepresentmentPaymentMethod(
21                    new AchPayload {
22                        AccountNumber = "11101010",
23                        NameOnAccount = "Sarah Hopper",
24                        RoutingNumber = "053200983",
25                        AccountType = AchPayloadAccountType.Checking,
26                        SecCode = AchPayloadSecCode.Tel
27                    }
28                )
29            }
30        );
31    }
32
33}
Try it

Response fields

If your request is successful, our gateway sends the re-presentment to NACHA to retry the payment.

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
List of re-presented payments 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    "accountType": "checking"
44  },
45  "transactionResult": {
46    "type": "payment",
47    "status": "ready",
48    "currency": "USD",
49    "responseCode": "A",
50    "authorizedAmount": 4999,
51    "responseMessage": "NoError",
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}

Step 3. (Optional) Re-present the payment again

If the re-presentment fails, you can send a second and final re-presentment request. To do this:

  1. Save the paymentId from the response in Step 2. This is the paymentId of the failed re-presentment.
  2. Use our Retrieve Payment method with the paymentId of the failed re-presentment. In the response, our gateway sends a returns object with a new paymentId.
  3. Use our Re-present Payment method with this new paymentId to re-present the payment for a final time.