ACH Direct Debit
Last updated: July 31, 2024
The Automated Clearing House (ACH) network is an electronic funds transfer system that enables customers in the United States (US) to move money between bank accounts in a fast, secure and paperless way.
Information
To enable ACH payments on your account, contact your Account Manager or [email protected].
Model | Collecting |
---|---|
Payment flow | Direct Debit |
Payment method type | Direct |
One-step payment | |
Authorization | |
Capture | |
Refund | |
Partial refund | |
Multiple refunds | |
Return | |
Recurring payment |
ACH payments follow a three-step process:
To comply with National Automated Clearing House Association (NACHA) rules, you must obtain consent from the bank account owner before you can collect ACH debit payments from their account.
The consent you present to the customer must:
- clearly set out the terms of the authorization
- explicitly state that you are obtaining consent to debit the customer's bank account for a specific transaction, or set of recurring transactions
- explain how the customer can revoke their direct debit authorization
You must also:
- include NACHA-mandated language in the terms and conditions section
- enable your customer to view and print a receipt after the payment has been successfully submitted.
- If you are managing recurring payments, the receipt must have full details of the schedule (payment amount, frequency, start date, end date, and number of payments), along with a confirmation number and date for any transaction processed as part of the schedule
- email a receipt to your customer, with a copy to yourself
- notify your customer in advance of any change to the scheduled payment amount, payment range or payment date
To process ACH payments, you must validate your customer's bank account. For this validation, you must contract directly with one of NACHA's third-party validation service vendors listed on the Account Validation Resource Center.
For ease of integration, we recommend using Plaid Link due to our built-in support for their Balance and Auth APIs.
Plaid Link provides you with instant account validation and eliminates the need to transmit sensitive bank routing and account numbers.
To use Plaid in your account validation process:
- Create a Plaid account.
- Create a sandbox API key on the Keys page and make a note of your Plaid client ID.
- Select Checkout.com on the Plaid Integrations page.
- Call the
/link/token/create
endpoint to create a Link token. - Initialize Link, open a consent window, and obtain a public token.
- Call the
/item/public_token/exchange
endpoint to obtain an access token. - Call the
/processor/token/create
endpoint to obtain a Checkout.com processor token. You submit this token when you request a payment using our Payments API.
If you are using other validation service, you must perform account validation on your own before processing the ACH payment.
Once the NACHA Account Validation step is complete, you can submit a payment request.
When we receive the request:
- We send a
payment_pending
webhook before processing the request. - We run syntax validation and compliance checks on the payment data. Plaid implementations also include a balance check.
- If all checks are successful, we set the payment status to
pending
and send apayment_capture_pending
webhook. - If unsuccessful, we set the payment status to
declined
and send apayment_declined
webhook, in which case the payment process is complete.
- If all checks are successful, we set the payment status to
- ACH payments submitted before midnight Eastern Time will progress to
captured
status on the following business day before 10:20 AM Eastern Time. Payments will not progress tocaptured
on weekends or banking holidays.
When a payment progresses to captured
status, we'll send a payment_captured
webhook. Note that the ACH network does not provide final confirmation of payment completion. The only indicator of a successful payment is the absence of a return. To minimize exposure to a return, some businesses choose to retain assets for seven to ten calendar days following an ACH payment.
Captured payments are settled according to your standard settlement schedule and will appear within your financial reconciliation reports.
If the recipient bank returns a successfully processed payment, we set the payment status to returned
and send a payment_returned
webhook. Typically, an ACH network or bank return is reported within a few business days; however, the account holder can return a payment for up to 60 days.
To comply with regulatory requirements and reduce the likelihood of bank declines or fraud, you must provide the following values within the account_holder object:
- if the
account_holder.type
isindividual
, provide theaccount_holder.first_name
andaccount_holder.last_name
fields - if the
account_holder.type
iscorporate
, provide theaccount_holder.company_name
field
Information
Typically, the bank account holder's name is on file within your database. Otherwise, Plaid implementations can obtain the name through the accounts.owners.names
object in the response from Plaid's /identity/get endpoint.
post
https://api.checkout.com/payments
1{2"source": {3"type": "plaid",4"token": "<PLAID_PROCESSOR_TOKEN>",5"account_holder": {6"type": "individual",7"first_name": "John",8"last_name": "Doe"9}10},11"amount": "6540",12"currency": "USD",13"processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq"14}
If you receive a 202 Accepted
response with a status field set to Pending
, your request was successful.
1{2"id": "pay_itm5maobcrne5fbbafuu2mw3le",3"status": "Pending",4"_links": {5"self": {6"href": "https://api.sandbox.checkout.com/payments/pay_itm5maobcrne5fbbafuu2mw3le"7}8}9}
post
https://api.checkout.com/payments
Recurring payments with Plaid occasionally require the user to re-authenticate with Plaid Link's update mode.
1{2"source": {3"type": "plaid",4"token": "<PLAID_PROCESSOR_TOKEN>",5"account_holder": {6"type": "individual",7"first_name": "John",8"last_name": "Doe"9}10},11"amount": "6540",12"currency": "USD",13"processing_channel_id": "pc_ovo75iz4hdyudnx6tu74mum3fq"14}
If you receive a 202 Accepted
response with a status field set to Pending
, your request was successful.
1{2"id": "pay_itm5maobcrne5fbbafuu2mw3le",3"status": "Pending",4"_links": {5"self": {6"href": "https://api.sandbox.checkout.com/payments/pay_itm5maobcrne5fbbafuu2mw3le"7}8}9}
For the full API specification, see the API reference.
get
https://api.checkout.com/payments/{payment_id}
1{2"id": "pay_itm5maobcrne5fbbafuu2mw3le",3"status": "Pending",4"reference": "reference_example",5"_links": {6"self": {7"href": "https://api.sandbox.checkout.com/payments/pay_itm5maobcrne5fbbafuu2mw3le"8}9}10}
You can use our Refund API to fully or partially refund a payment. Once refunded, the payment status updates to refunded
, and you receive a payment_refunded
webhook notification.
After the payment status changes to captured
, you can submit a request to process a full or partial refund. After receiving it, we send a payment_refund_pending
webhook but do not change the payment status. If the processor token is revoked before the refund occurs, you may need to re-authenticate the user in Plaid Link's update mode. The flow and timing for refunds are the same as for payments.
After a refund request is successfully sent to the ACH network (within one to three business days), we set the payment status to refunded
or partially_refunded
and send a payment_refunded
webhook.
If you issue a refund, you should notify your customer as soon as possible to prevent them from simultaneously canceling the payment with their bank. If your customer does get credited twice, you must contact them directly to resolve the situation.
If the refund is declined by the ACH network or bank (typically within one to three business days), the payment status is set to payment_refund_declined
.
An ACH return indicates that your bank, also known as the Receiving Depository Financial Institution (RDFI), could not collect the funds from your customer's account. A return can happen for various reasons, for example:
- the customer has insufficient funds in their bank account
- the customer’s bank account is closed or frozen
- the customer claims that they do not recognize the purchase and did not authorize it
See ACH returns explained for more information.
You can avoid returns caused by outdated banking information by listening to the bank_account_updated
webhook. As soon as we receive a notification of change (NoC), we will send you a request with the necessary information for you to update your instruments.
When a return happens, you'll receive a payment_returned
webhook notification.
ACH return codes identify the reason an ACH payment could not be collected from a customer's account. These codes provide additional information about the cause of the issue.
ACH return code | Description | API response code |
---|---|---|
R01 | Insufficient funds |
|
R03 | No account or unable to locate account |
|
R04 | Invalid account number | |
R19 | Amount field error |
|
R02 | Account closed |
|
R18 | Improper effective entry date |
|
R07 | Authorization revoked by customer |
|
R08 | Payment stopped or stop payment on item |
|
R09 | Uncollected funds |
|
R10 | Customer advises not authorized |
|
R11 | Customer advises entry not in accordance with the terms of the authorization |
|
R17 | File record edit criteria |
|
R21 | Invalid company identification |
|
R22 | Invalid individual ID number | |
R24 | Duplicate entry |
|
R25 | Addenda error |
|
R26 | Mandatory field error |
|
R27 | Trace number error |
|
R29 | Corporate customer advises not authorized |
|
R31 | Permissible return entry |
|
R32 | RDFI non-settlement |
|
R33 | Return of XCK entry |
|
R35 | Return of improper debit entry |
|
R36 | Return of improper credit entry |
|
R37 | Source document presented for payment |
|
R38 | Stop payment on source document |
|
R05 | Unauthorized debit to consumer account |
|
R06 | Returned per ODFI's request |
|
R12 | Branch sold to another DFI |
|
R13 | Invalid ACH routing number |
|
R14 | Representment payee deceased or unable to continue in that capacity |
|
R15 | Beneficiary of account holder deceased |
|
R16 | Account frozen |
|
R20 | Non-transaction account |
|
R23 | Credit entry refused by receiver |
|
R28 | Routing number or check digit error |
|
R30 | RDFI not participant in check truncation program |
|
R34 | Limited participation DFI |
|
When using ACH, you may receive the following webhooks.
For more details about these webhooks, see Webhook
Webhook | Description |
---|---|
| Sent when a merchant initiates a payment request. |
| Sent when a payment request has been successfully initiated and the payment capture is pending. |
| Sent when a payment request has been rejected. We send this webhook after unsuccessful real-time checks on the payment, including data validation, compliance, and balance availability (Plaid Link only). Typically, around 100 milliseconds after |
| Sent when a payment has been successfully captured. Typically, one to two business days after |
| There was a failure after an initial success scenario. Money will be moved out the merchant's account. Sent if a payment is returned due to an ACH network decline, bank decline or customer dispute. ACH network and bank declines typically occur within a few business days, but customers can dispute for up to 60 days. |
| Occurs when a refund request has successfully initiated. |
| Occurs when a refund is successful. Sent once a refund is sent to the ACH network. Typically, one to three business days after |
| Occurs when a refund is declined. Typically, one to three business days after |
| Sent when the customer's bank account details have changed and must be updated for future payments. This webhook sends two objects:
Use the new bank account details returned in the |
You can send test requests using the values from the following table, depending on which outcome you want to simulate:
API response code | ACH return code | Payment status | Webhook | Values |
---|---|---|---|---|
| N/A |
|
| Corporate and personal accounts:
|
| N/A |
|
| Corporate accounts:
Personal accounts:
|
| R01 |
|
| Corporate accounts:
Personal accounts:
|
| R02 |
|
| Corporate and personal accounts:
|
| R05 |
|
| Corporate and personal accounts:
|
| R07 |
|
| Corporate and personal accounts:
|
| R10 |
|
| Corporate and personal accounts:
|
| R29 |
|
| Corporate and personal accounts:
|