Desktop/Mobile Website Browser
This guide describes how to offer ACH Direct Debit as a payment method on your checkout page using Native API integration.
Step 1. Create a PaymentIntent
Create a PaymentIntent object with a request_id, amount, currency and a merchant_order_id from your backend server.
Example request:
Example response:
Step 2. Collect payment method details and mandate acknowledgement
You should display the exact authorization terms below for your customer on the checkout form. Only upon your customer’s authorization will you be able to initiate debits from your customer’s bank account.
By providing your bank account details and confirming this payment, you authorize Airwallex US, LLC to electronically debit your account via ACH for the total payment amount specified on this page, and, if necessary, electronically credit your account to correct erroneous debits. You certify that you are either the holder of, or an authorized signatory on, the bank account.
If you integrate through Hosted Payment Page (HPP) or Drop-in, Airwallex will display the authorisation terms for you.
When a shopper submits ACH Direct Debit on checkout form, you should use payment_intent.confirm to collect the mandate and complete the payment. For ACH Direct Debit, we support two verification methods: Plaid and micro-deposit. We will send below events to update you on the current status:
| EVENT | DESCRIPTION | NEXT STEPS |
|---|---|---|
| payment_consent.pending_verification | The payment is undergoing verification. | N/A. This status should remain short for Plaid verification but may take 1-2 days for micro-deposit verification. |
| payment_consent.verified | The customer's bank account has been successfully verified through Plaid or micro-deposits. | If you have disabled the authorization emails sent from Airwallex, you should notify your customers with the mandate confirmation. |
Option 1: Plaid verification
You can select the verification method by setting payment_method_options.ach_direct_debit.verification_method. You can provide owner_name, owner_email and whether it is business_account so that shopper will see these fields pre-filled on the confirmation page.
Example request
Example response
Example response
Option 2: Micro-deposit verification
You can also verify ACH Direct Debit with micro-deposits by providing the following payload.
Example request
When fraud scanning requires you to VERIFY the account, you will find the next actions in the response of Confirma a PaymentIntent API.
Example response
Airwallex will send a notification email to your shopper automatically to guide them on micro-deposits verification. If you want to customize the experience, please contact our Sales Support to turn off the Airwallex notification email and use the url returned in the response to build your own verification flow.
You can use instructions as below to guide your shoppers on checkout. Learn more about micro-deposit verification.
This account cannot be charged at the moment, please verify the account.
You will receive two micro-deposits to your account in 1-2 business days. You can click the verify button or verify through the email we have sent you.
Step 4. Wait for payment notifications from Airwallex
ACH Direct Debit provides delayed notifications, which means that the transaction cannot be authorized instantly (see ACH Direct Debit timing).
An ACH Direct Debit payment_intent remains pending after submission to the ACH network. The following events are sent when there is an update to payment_intent.
| EVENT | DESCRIPTION | NEXT STEPS |
|---|---|---|
payment_intent.pending payment_attempt.pending_authorization | The shopper’s payment was submitted to Airwallex successfully. | Wait for the initiated payment to succeed or fail. |
payment_intent.succeeded payment_attempt.capture_requested | The customer’s payment has succeeded. | Provision goods and services. |
payment_intent.requires_payment_method payment_attempt.authorization_failed | The customer’s payment was declined. | Contact the shopper and request another payment method. |
payment_disputes.accepted | Any bank rejections or indemnity claims within the rejection window are treated as disputes by Airwallex. The amount of the dispute is deducted from your pending settlement amount. Please note that payment_intent remains succeeded. | You cannot defend against ACH Direct Debit disputes. You must contact your customer to resolve the situation. |
Succeeded payment intents can be disputed due to various reasons. You should familiarise yourself with the dispute risks of direct debits and contact your customers to resolve the situation. Learn more about disputes.
If the transaction fails after the request is sent to the bank, you can get the failed reason using payment_attempt.authorization_failed webhook.
You may also query the status of a payment anytime using Retrieve a PaymentIntent API
Test ACH Direct Debit
Use the following details to test ACH Direct Debit in the demo environment.
1. Account verification
1.1 Account verification using Plaid
| Account holder name | Test scenario |
|---|---|
| Alberta Bobbeth Charleson | For successful Plaid verification |
| Any other name | For failed Plaid verification |
1.2 Account verification using micro-deposits
| Account number | Test scenario |
|---|---|
| 8454797888 | Verification required |
| 8454797666 | No verification required |
| Verification amounts | Test scenario |
|---|---|
| 0.04, 0.04 | For failed verification |
| Any other amount | For successful verification |
2. Payment
Once the account has been verified successfully, you can initiate a payment intent.
| Payment amounts | Test scenario |
|---|---|
| 400 | For failed payment intent |
| Any other amount | For successful payment intent |
3. Refund
After the payment succeeds, you can issue a refund.
| Refund amounts | Test scenario |
|---|---|
| 4 | For failed refund |
| Any other amount less than payment amount | For successful partial/full refund |