# Close an ACH payment

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.

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](/api/represent-bank-transfer-payment) method instead.

<a id="how-it-works"></a>
## 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.

<a id="your-integration-journey"></a>
## Your integration journey

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

<a id="things-to-consider"></a>
## 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"
       }
    }
 ],
...
```

<a id="errors"></a>
## Errors

If your request is unsuccessful, we return an error. For more information about errors, see [Errors](/api/errors).

<a id="step-1-view-the-payment-details"></a>
## 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](https://api.uat.payroc.com/v1/bank-transfer-payments/:paymentId) |
| Production | `api.` | [https://api.payroc.com/v1/bank-transfer-payments/:paymentId](https://api.payroc.com/v1/bank-transfer-payments/:paymentId) |

<a id="request-parameters"></a>
### Request parameters

<a id="schema-requestpath"></a>
### Schema (`request.path`)

[Path parameters for `GET /bank-transfer-payments/{paymentId}`](/api/get-bank-transfer-payment)

<a id="example-request"></a>
### Example request

<a id="request"></a>
### Request

GET [https://api.payroc.com/v1/bank-transfer-payments/\{paymentId\}](https://api.payroc.com/v1/bank-transfer-payments/%7BpaymentId%7D)

**`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`**

```go
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`**

```csharp
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()
```

<a id="response-fields"></a>
### 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.

<a id="schema-responsebody"></a>
### Schema (`response.body`)

[Response body schema for `GET /bank-transfer-payments/{paymentId}`](/api/get-bank-transfer-payment)

<a id="example-response"></a>
### Example response

<a id="response-200"></a>
### 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"
      }
    }
  ]
}
```

<a id="step-2-close-the-return"></a>
## 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](https://api.uat.payroc.com/v1/bank-transfer-payments/:paymentId/close) |
| Production | `api.` | [https://api.payroc.com/v1/bank-transfer-payments/:paymentId/close](https://api.payroc.com/v1/bank-transfer-payments/:paymentId/close) |

<a id="request-parameters-1"></a>
### Request parameters

<a id="schema-requestpath-1"></a>
### Schema (`request.path`)

[Path parameters for `POST /bank-transfer-payments/{paymentId}/close`](/api/close-bank-transfer-payment)

<a id="example-request-1"></a>
### Example request

<a id="request-1"></a>
### Request

POST [https://api.payroc.com/v1/bank-transfer-payments/\{paymentId\}/close](https://api.payroc.com/v1/bank-transfer-payments/%7BpaymentId%7D/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`**

```go
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`**

```csharp
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()
```

<a id="response-fields-1"></a>
### Response fields

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

<a id="schema-responsebody-1"></a>
### Schema (`response.body`)

[Response body schema for `POST /bank-transfer-payments/{paymentId}/close`](/api/close-bank-transfer-payment)

<a id="example-response-1"></a>
### Example response

<a id="response-200-1"></a>
### 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"
    }
  ]
}
```