Bond Studio

The Bond Developer Hub

Welcome to the Bond Studio Developer Hub.

Get up and running fast with documentation, guides, and support.

Let's get started!

Get Started    API Reference

ACH transfers

ACHACH - Automated Clearing House. The network that coordinates electronic payments and automated money transfers. is a method of transferring money electronically between banks without the need for paper checks, cards, or wire transfers. Common examples of ACH transfers include payroll systems which issue ACH credit transactions to pay employees by direct deposits, or utility providers which issue ACH debit transactions to request direct payments from the consumer's bank account.

Every transfer or attempted transfer is defined by its ACH return code.

ACH transfer requests are sent from the bank acting as the ODFIODFI - Originating Depository Financial Institution. The banking institution that acts on your behalf to initiate an ACH transfer. and are received by the bank acting as the RDFIRDFI - Receiving Depository Financial Institution. The banking institution that acts on behalf of the recipient of the transfer in the context of an ACH transaction.. Successful transfer requests move funds between an Originator account at the ODFI and a Receiver account at the RDFI. The ODFI sends a batch of ACH files representing ACH requests to the ACH Operator. The ACH Operator then processes the requests and sends them to the appropriate RDFI. The RDFI credits or debits the Receiver account.
The diagram below shows this flow.

The ODFI always initiates the ACH transactions, so the request must specify the direction of the transfer:

  • An ACH Credit "push" transaction credits the Receiver account, pushing funds from the Originator.
  • An ACH Debit "pull" transaction debits the Receiver account, pulling funds to the Originator.

A standard ACH transfer takes approximately 3 business days to complete but may finish sooner, but in some cases may take much longer. Bond supports same-day ACH, taking approximately one business day to complete. Bond handles the creation and transmission of the ACH file formatted with appropriate parameters to the ACH operator

ACH class code

Every ACH transaction is classified with a single, 3-letter, ACH SECSEC - Standard Entry Class. The valid payment methods as prescribed by NACHA. Each SEC Code defines the type of transaction (debit or credit), type of account (corporate or consumer), and any information specific to the format (such as single/recurring, terminal location, or check number). code. The SEC code is a mandatory parameter that identifies the transaction type in an ACH transfer request. It identifies the ACH file format and specifies the authorization method for the Receiver account. SEC codes distinguish between consumer and commercial usage categories.

NACHANACHA - The National Automated Clearing House Association. Manages the development, administration, and governance of the ACH Network., the regulatory body governing the ACH network, maintains and provides the complete list of SEC codes.

Bond supports the following SEC codes:

  • ARC—Accounts Receivable Conversion
  • CBR—Cross Border Entry (corporate)
  • CCD—Cash Concentration or Disbursement
  • CIE—Customer Initiated Entry
  • COR—Notification of Change (NOC) or Refused NOC
  • CTX—Corporate Trade Exchange
  • IAT—International ACH Transactions
  • MTE—Machine Transfer Entry
  • PBR—Cross Border Entry (consumer)
  • POP—Point-of-Purchase Entry
  • POS—Point-of-Sale Entry
  • PPD—Prearranged Payment and Deposit
  • RCK—Represented Check
  • TEL—Telephone-Initiated Entry
  • WEB—Internet-Initiated Entry

Executing an ACH transfer

For details on executing a transfer, see Account transfers.

Balance check

Prior to creating an ACH transfer, we check the customer's account balance to ensure there are sufficient funds. For an ACH credit, we confirm that the card account balance is sufficient before attempting to pull funds from the card. For an ACH debit, we check the customer's external bank account balance. This, however, can only be checked if the account was connected via Plaid Link and if the account's institute supports it; otherwise, the transfer will still be created.

Fund authorization

Following an ACH credit request, when funds are pushed from the card account and credited to the customer's external account, a pre-authorization hold is placed on the card account, equal to the amount of the ACH transfer. The table below summarizes the hold time.

ACH Network

Hold Expiry (days)

Standard ACH

3

Same-day ACH

1

ACH submission cut-off times

ACH transfers must be submitted before certain cut-off times to ensure that the transfers are included in the appropriate NACHA batch files. The table below summarizes the cut-off times depending on the network.

ACH Network

Cut-off Time

Standard ACH Origination

4:00 pm ET

Same-day ACH Origination

2:45 pm ET

ACH transfer state

The ACH transfer status may be:

  • pending
  • completed
  • cancelled
  • failed
  • returned

For more information, see Transaction states.

A created transfer will be pending and becomes completed after it posts. If a transfer is failed, a failure_reason is shown. After a transfer has posted, it might still be returned. This reversal can only ever happen after a transaction has already completed.

If a transfer is returned, in addition to the failure_reason there will also be an ach_return_code. These ACH return codes are standard and described in ACH return codes.

Reversing a transaction after it has reached the ODFI can only be done under specific circumstances. A reversal must occur within 5 business days of the transaction and is only considered for the following reasons:

  • The transaction was for the wrong amount.
  • The provided account number was incorrect.
  • The transaction is a duplicate.

Only pending transfers can be cancelled and only during a limited time-window after creation. These are discussed in the section below.

Cancelling an ACH transfer

To cancel an ACH transfer, use the PATCH /transfers/{transfer_id} operation and pass the body parameter as shown in the table below.

Parameter

Type

Description

status
required

String

The status is used to cancel a transfer. Set to cancel.
Note: Card-to-card transfers are instantaneous and cannot be cancelled.

An example of a request to cancel an ACH transfer is shown below.

curl --request PATCH \
     --url https://sandbox.bond.tech/api/v0/transfers/002e0f0e-e39d-1234-876c-afcad30d9c37 \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '{"status":"cancel"}'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/transfers/002e0f0e-e39d-1234-876c-afcad30d9c37")

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

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"status\":\"cancel\"}"

response = http.request(request)
puts response.read_body
const options = {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({status: 'cancel'})
};

fetch('https://sandbox.bond.tech/api/v0/transfers/002e0f0e-e39d-1234-876c-afcad30d9c37', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/transfers/002e0f0e-e39d-1234-876c-afcad30d9c37"

payload = {"status": "cancel"}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("PATCH", url, json=payload, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0/transfers/002e0f0e-e39d-1234-876c-afcad30d9c37");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"status\":\"cancel\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"status\":\"cancel\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/transfers/002e0f0e-e39d-1234-876c-afcad30d9c37")
  .patch(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

Response response = client.newCall(request).execute();

If the transfer can be cancelled, a successful 200 response is returned as shown below, and the transfer status value changes to cancelled.

{   
    "date_updated": "2020-10-09T17:18:58.856878",
    "date_created": "2020-10-09T17:14:09.686688",
    "transfer_id": "4ead6cdc-77eb-45fa-9959-3f166385a60a",
    "origination_account_id": "6f0e7dcb-6073-42df-bf02-ce71bd5fac3b",
    "account_id": "225641a5-f6e4-4ae1-b5e0-326e6b98842e",
    "type": "ach",
    "ach_direction": "debit",
    "ach_class_code": "WEB",
    "ach_network": "ach",
    "ach_description": "PAYROLL",
    "status": "cancelled",
    "ach_return_code": null,
    "failure_reason": null,
    "amount_in_cents": "1000",
    "iso_currency_code": "USD"
}

For a complete specification and interactive examples, see Cancelling an ACH transfer in the Bond API Reference.

Updated 10 days ago



ACH transfers


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.