United States (US_ACH_DEBIT)

Before you begin

Settlement time

ach direct debit settlement time - mtl

ach direct debit settlement time - evolve

As indicated above, ACH direct debit in the United States takes 2-4 business days to settle, depending on submission before/after the cut-off time. Therefore, we recommend leaving some buffer time ahead of the cut-off to avoid delays.

Customers who wish to accelerate the settlement time may apply for our Faster Direct Debit offering, which offers a shortened settlement time of 0-2 business days throughout the day. To enable this capability, please contact your Account Manager and confirm our terms, conditions, and fees.

Mandate requirements

To add funds to their customers via ACH direct debit, your customers must first link their United States external bank accounts, as outlined in Linked Accounts.

Before any ACH direct debit is processed, the owner of the external bank account must authorize Airwallex to directly debit the account on your behalf, in compliance with the NACHA Rules. A copy of the authorization will be sent by Airwallex via email to the bank account owner, and is stored and made available to be shared with the customer at all times.

The following is a guide to building your native product experience for your customers to link their external bank account and sign the mandate/agreement.

1. Linking an external bank account

The title should clearly inform your customers that they are linking an external bank account to set up direct debit.

You must ask the external bank account owner (or display their previously entered):

Bank account name
Bank account number
ACH routing number (only required if MICRO_DEPOSIT is set as the preferred_verification_type)
Bank account owner email address

2. Confirmation of account details and direct debit authorization

The customers must be given a prompt to confirm that their bank account details are correct before submitting the Linked Bank Account.

The following text must be displayed on the same confirmation screen:

You authorize Airwallex US, LLC ("Airwallex"), on behalf of AIRWALLEX PLATFORM CUSTOMER, and, if applicable, AIRWALLEX PLATFORM CUSTOMER’s affiliated entities ("Merchant"), to debit the bank account specified above for any amount owed for charges arising from your use of Merchant’s services and/or purchase of products from Merchant, pursuant to Merchant’s terms, and, if necessary, to electronically credit your bank account to correct erroneous debits, until this authorization is revoked.
If you use Merchant’s services or purchase additional products periodically, pursuant to Merchant’s terms, you authorize Airwallex to debit your bank account periodically. Payments that fall outside of any regular debits authorized above will only be debited after your authorization is obtained.
You may amend or cancel this authorization at any time by providing 30 (thirty) days' notice to Airwallex prior to the scheduled debit. You may provide such notice to Airwallex by contacting [email protected].

3. Confirmation of direct debit set up

If the linked account was created using PLAID as the preferred_verification_type, you must provide a confirmation page to your customers at the end of the process to inform them that direct debit has been successfully set up for the Linked Bank Account.

API instructions

1. Create Linked Account with direct debit mandate

Referring to Linked Account requirements for direct debit, only BUSINESS Linked Account type is supported for ACH direct debit in the United States.

Micro-deposit and Open Banking are both available for this scheme. Please follow the instructions in Create a Linked Account and submit the required mandate information under the mandate object.

Example request for Linked Account created using micro-deposit verification

Shell

If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.

Example response

JSON

Example request for Linked Account created using Open Banking verification

Shell

If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.

Example response

JSON

If you already have a Linked Account created, you may call a Direct Debit Mandate API to create the mandate.

Example request

Shell

If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.

Example response

JSON

2. Create direct debit deposit

Before creating a direct debit deposit, please ensure that you have a sufficient funding limit by checking your available funding limit.

If the Linked Account was created using Open Banking verification, you may use Check available balance API to ensure that the Linked Account has sufficient balance before initiating a direct debit deposit.

Next, follow the instructions outlined in Create a direct debit deposit. Please note that the direct debit deposit reference for ACH direct debit should not exceed 10 characters.

Example request

Shell

If you are registered as a platform account, you can call this endpoint on behalf of your customers by specifying the open ID in the x-on-behalf-of header.

Example response

JSON

Clearing system error codes

To help you handle exceptions systematically, this page provides a comprehensive list of all possible clearing system errors and detailed descriptions when the Linked Accounts or a direct debit deposit from Linked Accounts are in failure statuses.

We recommend using the Airwallex error code or the iso_code for systematic exception handling. The code from provider_failure_details can be used for troubleshooting against the clearing system rules, but it is not advised for systematic handling because the clearing system may update it from time to time.

Linked Account error codes

code	iso code	provider failure details code	description
`inconsistent_with_end_customer`	`AC01`	`R03`	The payer’s bank account number is invalid. Please confirm the account number with the payer.
`blocked_account`	`AC06`	`R16`	The bank account has been blocked for ACH transactions. Contact the payer to remove the block, or create a new mandate to charge a different bank account.
`transaction_forbidden`	`AG01`	`R29`	The payer’s bank is not authorised to receive ACH transactions. Contact the payer or payer’s bank for further information.
`invalid_clearing_system_member_identifier`	`RC08`	`R13`	The ACH routing number of the payer’s bank is invalid. Contact the payer or payer’s bank for further information.
`refused_by_creditor`	`NARR`	`R23`	Reason has not been specified. Contact the payer or payer’s bank for further information.

Direct debit deposit error codes

code	iso code	provider failure details code	description
`insufficient_funds`	`AM04`	`R01`	The balance in the Linked Account is insufficient. Please ensure funds are added to the Linked Account and retry.
`closed_account_number`	`AC04`	`R02`	The payer’s bank account is closed. Contact the payer to reopen the account, or create a new mandate to charge a different bank account.
`inconsistent_with_end_customer`	`BE01`	`R03`	Unable to identify the account information (e.g. routing number, account number, account name) of the payer. Please confirm the account information with the payer.
`incorrect_account_number`	`AC01`	`R04`	The payer’s bank account number is invalid (e.g. format of the account number specified is not correct). Please confirm the account number with the payer.
`transaction_not_supported`	`AG03`	`R05`	The debit was sent to a consumer account, but the payer hasn’t authorised the debit. Contact the payer for further information.
`unsuccessful_direct_debit`	`AG07`	`R07`	The payer who authorised the debit has revoked the authorisation. Contact the payer for further information.
`order_cancelled`	`DS02`	`R08`	The payer has placed a stop payment order on this debit. Contact the payer for further information.
`blocked_amount`	`AM07`	`R09`	The available balance in the Linked Account is insufficient. Please ensure funds are added to the Linked Account and retry. Although the ledger balance of the external bank account is sufficient to cover the transaction amount (including fees), the available balance is below the dollar value of the debit. This may be due to pending transactions.
`transaction_forbidden`	`AG01`	`R10`	The payer’s bank has been notified by the payer that the debit is unauthorised, improper ineligible, or part of an incomplete transaction. Contact the payer or payer’s bank for further information.
`account_transferred`	`NARR`	`R12`	The payer’s bank account was sold or transferred to another bank. Contact the payer or payer’s bank for further information.
`invalid_clearing_system_member_identifier`	`RC08`	`R13`	The ACH routing number of the payer’s bank is invalid. Contact the payer or payer’s bank for further information.
`end_customer_deceased`	`MD07`	`R14, R15`	You cannot create a direct debit against the payer’s bank account because the payer is deceased, or unable to continue in that capacity (e.g. a legally incapacitated adult). Contact the payer’s bank for further instructions.
`blocked_account`	`AC06`	`R16`	The bank account has been blocked for ACH direct debits. Contact the payer to remove the block, or create a new mandate to charge a different bank account.
`invalid_file_format`	`FF01`	`R17`	The payer’s bank is unable to process certain fields in the transaction file. Contact the payer’s bank for further information.
`transaction_forbidden`	`AG01`	`R20`	The debit was sent to a non-transaction account, i.e., an account against which transactions are limited or prohibited. Contact the payer to remove the limit, or create a new mandate to charge a different bank account.
`missing_debtor_account_or_identification`	`RR01`	`R22`	The payer’s bank has been notified by the payer that the identification number specified by the recipient is invalid. Contact the payer or payer’s bank for further instructions.
`duplication`	`AM05`	`R24`	The date, dollar amount, trace number, and other data matches another transaction. Contact your account manager for further information.
`invalid_cheque_number`	`FF09`	`R28`	The check digit provided for the routing number is invalid. Contact your account manager for further information.
`transaction_forbidden`	`AG01`	`R29`	The payer’s bank has been notified by payer that the debit is unauthorised, improper ineligible, or part of an incomplete transaction. Contact the payer or payer’s bank for further information.
`permissible_return_entry`	`NARR`	`R31`	The payer may return a direct debit that the recipient agrees to accept. Contact the payer to create a new mandate to charge a different bank account.
`settlement_failed`	`ED05`	`R32`	Settlement of the transaction has failed. Contact the payer’s bank for the failure reason.
`limited_participation_dfi`	`NARR`	`R34`	The federal or state supervisor of the payer’s bank has limited their participation. Contact the payer or payer’s bank for further information.
`collection_not_due`	`MD05`	`R35`	The debit request is not permitted for loan accounts or CIE Entries. Contact the payer to provide a new bank account.
`misrouted_return`	`NARR`	`R61`	The bank preparing the return request placed an incorrect recipient identification number. Contact the payer’s bank for further information.
`erroneous_debit`	`NARR`	`R62`	The payer bank’s use of the reversal process has resulted in, or failed to correct, an unintended credit to the recipient. Contact the payer’s bank to resolve the issue.

Was this page helpful?