You can add ACH Direct Debit to your existing integration. The following instructions show only what you must add to your integration specifically for ACH Direct Debit.
If an instruction on this page corresponds with a step in the main integration guide, it includes a link to that corresponding step of the main integration guide.
Requirements
| Requirement | Description | |
|---|---|---|
| Integration type | Make sure that you have an existing API-only integration. This page includes only instructions to add ACH Direct Debit to your existing integration. |
|
| Webhooks | Subscribe to DIRECT_DEBIT_NOTICE_OF_CHANGE_NOTIFICATION webhooks to receive a notification when a shopper has outdated banking details. | |
| Setup steps | Before you begin, add ACH Direct Debit in your Customer Area. |
Get ACH Direct Debit as an available payment method
When you make the /paymentMethods call to get available payment methods, specify the following so that ACH Direct Debit is included in the response.
| Parameter | Values |
|---|---|
| countryCode | US, PR |
| amount.currency | USD |
Build your payment form
We provide the logo for ACH Direct Debit that you can download.
When a customer chooses to pay with ACH Direct Debit, collect the following payment details in your payment form and use these to get a mandate from the customer:
| Payment details | Example |
|---|---|
| Bank account number | The US bank account number from which the payment will be debited. Format: numeric. Minimum length: 4 Maximum length: 17 Example: 01234567890123 |
| Bank routing number | The 9-digit ACH routing number of the account. Alert your customers that some banks have different routing numbers for different transfers. Customers should not provide their wire transfer routing number. Do not remove any leading zeros. Adyen performs validation to ensure the routing number is genuine. Example: 123456789 |
| Bank account type | checking or savings |
| Account holder name | "John Smith" |
| Account holder address | A valid US address (optional field). |
| Type of account holder | personal or business |
Bank account type
Customers can use both checking accounts and savings accounts to make ACH payments. If you do not provide the bankAccountType in your payment request, this defaults to checking account. In cases where the account type defaulted to checking account while the customer provided the account number of a savings account, this mismatch will lead to a chargeback.
To avoid chargebacks, we recommend collecting the bank account type from the customer, and providing it in your payment request.
SEC code
Nacha requires a Standard Entry Class (SEC) code for ACH payments. If you do not provide the correct SEC code, you risk chargebacks and potential fines.
Collect the account holder type (personal or business) from the customer and provide the appropriate SEC code in your payment request. There are a few ways you can specify an SEC code:
- Send the SEC code in your ACH Direct Debit payment request using the
additionalData.ach.secCodefield. - Send the field
paymentmethod.accountHolderTypein your payment request.- If the value is business, we use CCD.
- If it is personal, we use WEB.
- Ask our Support Team to configure a default SEC code for all your ACH Direct Debit payments.
If you do not provide an SEC code, we try to select the correct code based on the account holder's name. If we cannot make a confident guess, we default to WEB.
Add additional parameters to your /payments request
When you make a payment, add the following parameters:
| Parameter | Required | Description | |
|---|---|---|---|
| paymentMethod.type |  |
ach | |
| paymentMethod.bankAccountNumber or paymentMethod.encryptedBankAccountNumber |
|
The customer's bank account number. | |
| paymentMethod.bankAccountType | The type of bank account. Allowed values: checking, savings. | ||
| paymentMethod.bankLocationId or paymentMethod.encryptedBankLocationId |
|
The ACH routing number of the account. | |
| paymentMethod.ownerName | |
The name on the bank account. | |
additionalData.ach.secCode |
The SEC code to use for the payment. Possible values: CDD (for B2B transactions), PPD (for personal transactions with written authorization), or WEB (for personal transactions with digital authorization). | ||
| paymentMethod.accountHolderType | The type of account holder (personal or business). If you are not using additionalData.ach.secCode, use this field to determine the SEC code. |
Test and go live
You can test ACH Direct Debit payments as well as chargebacks.
Test the payment flow
Before making live ACH Direct Debit payments, use the following account details to test your integration.
ownerName |
bankAccountNumber |
bankLocationId (routing number) |
|---|---|---|
| Any name | Any correctly formatted account number. Example: 1234567890 |
Any correctly formatted routing number. Examples: 011000138 or 121000358 |
Test the chargeback flow
You can test the chargeback flow by making test payments with an ownerName value that consists of chargeback: followed by an ACH return reason code. For example, chargeback:R01. The other account details to use are the same as when testing payments.
For instructions, see Test a chargeback scenario.