ACH

The Automated Clearing House (ACH) network is an electronic funds transfer system that allows US customers to move money between bank accounts in a fast, secure and paperless way.

Start accepting ACH payments to collect funds directly from individuals or businesses in the US.

To start accepting ACH, please contact your customer success manager.

Process an ACH payment

ACH payments follow a three-step process:

  1. Collect customer's consent
  2. Create a new ACH payment source
  3. Request an ACH payment

Step 1: Collect customer's consent

Before processing an ACH payment, you need to get consent from the owner of the bank account to make ACH debits to their account. This is necessary to comply with the National Automated Clearing House Association's (NACHA) rules.

This consent should set out the terms of the authorization, clearly state that you are obtaining consent to debit your customer's bank account for a specific transaction or set of recurring transactions, and explain the method by which your customer can revoke their authorization.

I authorize [your company name] ("Company") to debit my account.

This authorization will continue in full force and effect until the Company has received written notice from me of its termination in such time and manner as to give the Company a reasonable opportunity to act on it.

We recommend that you gather the information below and store it for two years. (This list is not exhaustive.)

Information
Description

Transaction details

The date and time of transaction, debit account details, item purchased, IP address, and frequency if it's a recurring payment.

Client/account information

Name on the account/shipping information, and any other details needed to confirm the customer's identity.

Additional transaction details

Previous transaction history, particularly for recurring payments.

Receipt of transaction

Prompt your customer to print and keep a copy of their authorization, and email them a receipt of the processed transaction.

Step 2: Create a new ACH payment source

Once you've got the customer's consent, you can create a new ACH payment source that can be used to process one or more payments.

Payment sources are linked to a specific customer and cannot be shared between customers.

The request

Use the details below to set up a new ACH payment source.

Endpoints

Live

https://api.checkout.com/sources

Sandbox

https://api.sandbox.checkout.com/sources

Header parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

Field name
Description

type
String
required

The payment source type. Set this to ach.

billing_address
Object
required

The payment source owner's billing address.

billing_address.address_line1
String
optional

The first line of the address.

billing_address.address_line2
String
optional

The second line of the address.

billing_address.city
String
optional

The address city.

billing_address.state
String
optional

The address state.

billing_address.zip
String
optional

The address zip/postal code.

billing_address.country
String
optional

The address country (two-letter ISO code).

source_data
Object
required

Additional data required to create ACH payment source.

source_data.account_holder_name
String
required

The account holder's full name.

source_data.account_type
String
required

The type of Direct Debit account.
Should be Checking, Savings, Corporate, or CorpSavings.

source_data.account_number
String
required

The account number of the Direct Debit account.

source_data.routing_number
String
required

The routing number of the Direct Debit account.

source_data.billing_descriptor
String
required

The billing descriptor.

source_data.company_name
String
optional

The name of the company.
Required if account_type is Corporate or CorpSavings.

Request example

{
  "type": "ach",
  "billing_address": {
    "address_line1": "Wayne Plaza 1",
    "address_line2": null,
    "city": "Gotham City",
    "state": null,
    "zip": "12345",
    "country":"US"
  },
  "source_data": {
    "account_holder_name": "Bruce Wayne",
    "account_type": "Checking",
    "account_number": "0123456789",
    "routing_number": "211370545",
    "billing_descriptor": "ACH Demo",
    "company_name": null
  }
}

The response

If you receive a 201 Created response, your request was successful.

Response example

{
  "id": "src_c2gwvk66jpjenn665xuu77vawy",
  "type": "ACH",
  "response_code": "10000",
  "response_data": {},
  "customer": {
  "id": "cus_tvndgx3ig4cetadofprfh2sxla"
  }
}

Step 3: Request an ACH payment

The request

Use the details below to set up your payment request.

ACH does not support separate authorization and capture. The payment is authorized and captured at the same time.

Endpoints

Live

https://api.checkout.com/payments

Sandbox

https://api.sandbox.checkout.com/payments

Header parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

The table below describes the minimum recommended fields. You can find the full list, as well as complete request and response examples, in our API reference.

Field name
Description

amount
Integer
required

The payment amount.

currency
String
required

The currency of the payment (three-letter ISO 4217 code). Set this to USD.

source
Object
required

The source of the payment.

source.type
String
required

The payment source type. Set this to id.

source.id
String
required

The payment source ID.

Request example

{
  "source": {
    "type": "id",
    "id": "src_c2gwvk66jpjenn665xuu77vawy"
  },
  "amount": 154,
  "currency": "USD"
}

The response

If you receive a 202 Accepted response with a status field set to Pending, your request was successful.

Response example

{
  "id": "pay_zyhhgywqsowuvcbilkcfqyf5by",
  "status": "Pending",
  "customer": {
    "id": "cus_tvndgx3ig4cetadofprfh2sxla"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_zyhhgywqsowuvcbilkcfqyf5by"
    }
  }
}

ACH payment flow

It typically takes two to five business days to receive confirmation of whether or not an ACH payment was successful:

  1. When you make your ACH payment request, we set the payment status to Pending.
  2. After we receive confirmation that your request has been accepted, we update the payment status from Pending to Deferred.
  3. On the next business day, the payment is processed.
  4. The payment’s status then changes to Succeeded or Declined. We’ll send you a success or failure notification when this happens. Note that it can take up to four business days for the payment status to change, depending on your customer’s bank.
    • If the payment was successful, we’ll transfer the funds to your account on the next business day.
    • If the payment failed, the customer will not be charged.

Get details about an ACH payment

You can use the payment_id found in the payment response, or the cko-session-id from the success/failure URL (e.g., https://www.checkout.com/order/succeeded?cko-session-id=sid_vii64oquze5u3h2x6hh4rurc4y) to retrieve details about the payment.

The request

Use the details below to set up your request.

Endpoint

Live

GEThttps://api.checkout.com/payments/{payment_id}

Sandbox

GEThttps://api.sandbox.checkout.com/payments/{payment_id}

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Path
Description

payment_id
Required

The payment ID, found in the payment response, or the session ID from the success/failure URL.

The response

Response example

{
  "id": "pay_zyhhgywqsowuvcbilkcfqyf5by",
  "requested_on": "2019-08-19T07:37:56Z",
  "source": {
    "type": "ach",
    "id": "src_c2gwvk66jpjenn665xuu77vawy"
  },
  "amount": 154,
  "currency": "USD",
  "payment_type": "Regular",
  "status": "Pending",
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_tvndgx3ig4cetadofprfh2sxla"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_zyhhgywqsowuvcbilkcfqyf5by"
    }
  }
}

Refund an ACH payment

An ACH payment can be refunded using our refund API. Once refunded, the payment status updates to refunded, and you will receive a payment_refunded webhook notification.

Risk of double crediting
If you issue a refund for an ACH payment, you must immediately notify your customer of this to prevent them simultaneously canceling the payment with their bank and being credited twice for the same transaction. If your customer does get credited twice, you will need to contact them directly to resolve the situation.

ACH chargebacks

Customers can reverse an ACH payment and have it refunded up to 60 days after settlement by submitting a claim to their bank either revoking their authorization or stating that they never gave it for the transaction in question.

If your customer initiates a chargeback, we will let you know through a payment_chargeback webhook notification.

Unlike card payment disputes, you cannot defend against ACH chargebacks; the payment will always be reversed. You will need to contact your customer directly to resolve the situation.

ACH webhooks

When using ACH, you may receive any of the following webhooks. Note that other webhook types, such as payment_canceled will not be raised for ACH.

Webhook
Description

payment_pending

Sent when a payment request is successfully initiated.

payment_capture_pending

Sent when the acquirer is in the process of accepting the payment.

payment_captured

Sent when the payment has been successfully approved.

payment_declined

Sent when the payment is declined.

payment_refund_pending

Sent when a refund is successfully initiated.

payment_refunded

Sent when a refund is successfully processed.

payment_refund_declined

Sent when a refund is declined.

payment_chargeback

Sent when the customer requests a chargeback.
Unlike card payment disputes, you cannot defend against ACH chargebacks.

Testing ACH payments

To start testing, you'll need to:

  • create a test account, and
  • contact your customer success manager or integrations engineer to activate ACH payments in the sandbox environment.

Use the values contained in the tables below to test various scenarios:

Outright declines

Invalid account number

Payment was declined because of an invalid account number.

Field
Value

source_data.account_holder_name

Mike J Hammer

source_data.account_type

checking

source_data.account_number

10@BC99999

source_data.routing_number

053100300

source_data.company_name

n/a

Approved payments

No chargeback nor Notification Of Change (NOC)

Payment was successfully approved (captured). No chargebacks or notifications of change were received later on.

Field
Value

source_data.account_holder_name

Tom Black

source_data.account_type

checking

source_data.account_number

4099999992

source_data.routing_number

011075150

source_data.company_name

n/a

Recon payment failure

Payment was successfully initiated, but later on was declined by account holder's bank e.g., due to insufficient funds.

Field
Value

source_data.account_holder_name

Tom Black

source_data.account_type

corporate

source_data.account_number

4099999992

source_data.routing_number

011075150

source_data.company_name

Green Co

Chargeback but no Notification Of Change (NOC)

After a successful payment capture, the customer has initiated a chargeback with their bank. No notifications of change were sent.

Field
Value

source_data.account_holder_name

Robert Jones

source_data.account_type

corporate

source_data.account_number

3099999999

source_data.routing_number

011075150

source_data.company_name

Widget Inc

No chargeback with Notification Of Change (NOC), next payment failure

Payment was successfully initiated and captured. Later on, a notification of change was received. The next payment failed.

Field
Value

source_data.account_holder_name

Ashley Barret

source_data.account_type

corporate

source_data.account_number

6099999993

source_data.routing_number

211370545

source_data.company_name

Checkout.com

Refunds

Payment successfully refunded or payment refund failed.

Initiating a refund with one of amounts below will reconcile the payment either successfully or unsuccessfully depending on the amount provided. Any other amount will produce a successful reconciliation.

Successful refund
Unsuccessful refund

1000

2000

3000

4000

5000

6000

7000

8000

Can we help?

Thanks for using Checkout.com. If you need help or have a question, message our support team at support@checkout.com.

ACH


Suggested Edits are limited on API Reference Pages

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