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.

Overview

ACH payments follow a three-step process:

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

Collect customer 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.

 Customer consent example

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.)

InformationDescription

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.

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 POST request

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

Endpoints

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

Header parameters

HeaderValue

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 nameDescription

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.

This should be one of following:

  • Checking
  • Savings
  • Corporate
  • 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 POST 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"
  }
}

Request a payment 

The POST request

Use the details below to set up your payment request.

Endpoints

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

Header parameters

HeaderValue

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 nameDescription

amount

INTEGER

REQUIRED

The payment amount.

currency

STRING

REQUIRED

The currency in which the payment is being made (three-letter ISO 4217 code). Set this to USD.

source

OBJECT

REQUIRED

Details about the payment source.

source.type

STRING

REQUIRED

The type of payment source. 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 POST response

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

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

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 a 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 GET request

Endpoints

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

Header and path parameters

HeaderValue

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
PathValue

payment_id

REQUIRED

The payment ID found in the response of the initial payment.

The GET 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 a 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.

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.

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.

WebhookDescription
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

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.

FieldValue
source_data.account_holder_nameMike J Hammer
source_data.account_typechecking
source_data.account_number

10@BC99999

source_data.routing_number

053100300

source_data.company_namen/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.

FieldValue
source_data.account_holder_nameTom Black
source_data.account_typechecking
source_data.account_number4099999992
source_data.routing_number011075150
source_data.company_namen/a

Recon payment failure

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

FieldValue
source_data.account_holder_nameTom Black
source_data.account_typecorporate
source_data.account_number4099999992
source_data.routing_number011075150
source_data.company_nameGreen 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.

FieldValue
source_data.account_holder_nameRobert Jones
source_data.account_typecorporate
source_data.account_number3099999999
source_data.routing_number011075150
source_data.company_nameWidget 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.

FieldValue
source_data.account_holder_nameAshley Barret
source_data.account_typecorporate
source_data.account_number6099999993
source_data.routing_number211370545
source_data.company_nameCheckout.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 refundsUnsuccessful refund
10002000
30004000
50006000
70008000

Can we help?

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