Close an ACH payment

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

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

Your integration journey

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

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 details of the return, send a GET request to our Bank Transfer Payments endpoint.

Endpoint	Prefix	URL
Test	`api.uat.`	https://api.uat.payroc.com/v1/bank-transfer-payments/:paymentId
Production	`api.`	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 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.

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. Close the return

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

Endpoint	Prefix	URL
Test	`api.uat.`	https://api.uat.payroc.com/v1/bank-transfer-payments/:paymentId/close
Production	`api.`	https://api.payroc.com/v1/bank-transfer-payments/:paymentId/close

Request parameters

Schema (`request.path`)

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

Example request

Request

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

Store Token Bank Transfer Payment

curl

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

Store Token Bank Transfer Payment

Python

import requests

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

headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>"
}

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

print(response.json())

Store Token Bank Transfer Payment

JavaScript

const url = 'https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y/close';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    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/close"

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

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	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/close")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
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.post("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y/close")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .asString();

Store Token Bank Transfer Payment

PHP

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y/close', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Store Token Bank Transfer Payment

using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y/close");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);

Store Token Bank Transfer Payment

swift

import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y/close")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
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

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

Schema (`response.body`)

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

Example response

Response (200)

JSON

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "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": "****3159",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "053200983",
    "secCode": "web",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "ready",
    "responseCode": "A",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

How it works

Your integration journey

Things to consider

Errors

Step 1. View the payment details

Request parameters

Schema (`request.path`)

Example request

Request

Response fields

Schema (`response.body`)

Example response

Response (200)

Step 2. Close the return

Request parameters

Schema (`request.path`)

Example request

Request

Response fields

Schema (`response.body`)

Example response

Response (200)

Browse guides

Menu

Sign out

Talk to an engineer

How it works

Your integration journey

Things to consider

Errors

Step 1. View the payment details

Request parameters

Schema (request.path)

Example request

Request

Response fields

Schema (response.body)

Example response

Response (200)

Step 2. Close the return

Request parameters

Schema (request.path)

Example request

Request

Response fields

Schema (response.body)

Example response

Response (200)

Schema (`request.path`)

Schema (`response.body`)

Schema (`request.path`)

Schema (`response.body`)