Re-present an ACH payment

Prerequisites: Authentication

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

Each time you re-present a payment, you use a new paymentId from the returns object of the retrieved payment, not the paymentId you used to retrieve it. You can re-present a payment up to two times.

Mermaid source

sequenceDiagram
    participant M as Merchant
    participant GW as Gateway
    participant N as NACHA

    Note over M,N: An ACH payment has failed

    rect rgba(0, 81, 194, 0.4)
        Note over M,GW: Find out why the payment failed
        GW-->>M: Email: the ACH payment failed
        M->>GW: GET /bank-transfer-payments/:paymentId
        GW-->>M: returns[].paymentId and the failure reason
        Note over M: Contact the customer to<br />fix the issue, if needed
    end

    rect rgba(0, 224, 184, 0.3)
        Note over M,N: Re-present the payment
        M->>GW: POST /bank-transfer-payments/:paymentId/represent<br />using the new paymentId from returns
        GW->>N: Submit the re-presentment
        Note over M,N: If the payment fails again, repeat both steps with each new<br />paymentId from the returns object. You can re-present twice.
    end

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

Your integration journey

View the payment details.
Re-present the payment.
(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.

JSON

...
"returns": [  
    {  
       "paymentId": "GIJXAU3WUJ",  
       "date": "2025-06-23",  
       "returnCode": "R01",  
       "returnReason": "Insufficient Funds",  
       "represented": false,
       "closed": false,
       "link": {
          "rel": "self",  
          "method": "GET",  
          "href": "https://api.payroc.com/v1/bank-transfer-payments/GIJXAU3WUJ"
       }  
    }  
 ],
...

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.

Environment	URL
Test	https://api.uat.payroc.com/v1/bank-transfer-payments/{paymentId}
Production	https://api.payroc.com/v1/bank-transfer-payments/{paymentId}

Request parameters

Schema (`request.path`)

Path parameters for GET /bank-transfer-payments/{paymentId}

Example request

Request

GET https://api.payroc.com/v1/bank-transfer-payments/{paymentId}

Store Token Bank Transfer Payment

curl

curl https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y \
     -H "Authorization: Bearer <token>"

Store Token Bank Transfer Payment

Python

import requests

url = "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())

Store Token Bank Transfer Payment

JavaScript

const url = 'https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Store Token Bank Transfer Payment

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Store Token Bank Transfer Payment

ruby

require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Store Token Bank Transfer Payment

Java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y")
  .header("Authorization", "Bearer <token>")
  .asString();

Store Token Bank Transfer Payment

PHP

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();

Store Token Bank Transfer Payment

using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);

Store Token Bank Transfer Payment

swift

import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: \{ (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

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.

Schema (`response.body`)

Response body schema for GET /bank-transfer-payments/{paymentId}

Example response

Response (200)

JSON

{
  "paymentId": "E29U8OU8Q4",
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef7654",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5,
          "amount": 217
        }
      ],
      "tip": {
        "type": "percentage",
        "amount": 435,
        "percentage": 10
      }
    },
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "bankAccount": {
    "type": "ach",
    "accountNumber": "****1591",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "053200983",
    "secCode": "web"
  },
  "transactionResult": {
    "type": "payment",
    "status": "declined",
    "responseCode": "D",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseMessage": "Payment Declined",
    "processorResponseCode": "R11"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "returns": [
    {
      "paymentId": "M2MJOG6O2Y",
      "date": "2024-07-02",
      "returnCode": "R11",
      "returnReason": "Customer advises not authorized",
      "represented": false,
      "closed": false,
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y"
      }
    }
  ]
}

Step 2. Re-present the payment

To retry the payment, send a POST request to our Bank Transfer Payments endpoint.

Environment	URL
Test	https://api.uat.payroc.com/v1/bank-transfer-payments/{paymentId}/represent
Production	https://api.payroc.com/v1/bank-transfer-payments/{paymentId}/represent

Request parameters

Schema (`request.path`)

Path parameters for POST /bank-transfer-payments/{paymentId}/represent

Schema (`request.body`)

Request body schema for POST /bank-transfer-payments/{paymentId}/represent