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:

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data-raw '{
6    "request_id": "1af636ea-3606-4b84-acec-db098c8459cc", 
7    "amount": 10, 
8    "email": "[email protected]", 
9    "phone": "+86-19100008888", 
10    "currency": "USD", 
11    "merchant_order_id": "3d5b8003-0343-49bb-b799-3bc427e19eee", 
12    "return_url": "https://www.airwallex.com", 
13    "descriptor": "For internal testing", 
14    "additional_data": "131231232" 
15}' 

Example response:

JSON
1{
2    "id": "int_hkst7jgh4g8lkxpq7ck",
3    "request_id": "1af636ea-3606-4b84-acec-db098c8459cc",
4    "amount": 10,
5    "currency": "USD",
6    "merchant_order_id": "3d5b8003-0343-49bb-b799-3bc427e19eee",
7    "descriptor": "For internal testing",
8    "status": "REQUIRES_PAYMENT_METHOD",
9    "captured_amount": 0,
10    "created_at": "2022-04-06T04:30:07+0000",
11    "updated_at": "2022-04-06T04:30:07+0000",
12    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NDkyMTk0MDcsImV4cCI6MTY0OTIyMzAwNywiYWNjb3VudF9pZCI6ImY1M2UyYzg4LWYwMTEtNDA1NC05ZWZjLTgzYzYwN2VjNzM1MCIsImRhdGFfY2VudGVyX3JlZ2lvbiI6IkhLIiwiaW50ZW50X2lkIjoiaW50X2hrc3Q3amdoNGc4bGt4cHE3Y2siLCJwYWRjIjoiSEsiLCJidXNpbmVzc19uYW1lIjoiSmFza29sc2tpIGFuZCBTb25zIn0.uARmsMiAkBBjzP5qQl1w8rN4LtrhNGI2v7BZnNc4wr4"
13}

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.

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:

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

JSON
1api/v1/pa/payment_intents/int_hkstd5mlqg8lrt9hv28/confirm' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <your_bearer_token>' \
4--data '{  
5   "request_id": "21bef56a-da91-4a8b-a105-1b8ffe797ae7",
6  "payment_method": {
7    "type": "ach_direct_debit",
8    "ach_direct_debit": {
9      "owner_name": "Alberta Bobbeth Charleson",
10      "owner_email": "[email protected]",
11      "verification_method": "plaid" 
12    }
13}} 

Example response

JSON
1{
2    "id": "int_sgstf4jnlgez7mhvwbb",
3    "request_id": "d47ce971-2e3e-4e79-93db-72a09ebd1534",
4    "amount": 30,
5    "currency": "USD",
6    "merchant_order_id": "5bc5a070-572a-4f51-b0e1-c3aaeabba635",
7    "descriptor": "For internal testing",
8    "status": "REQUIRES_CUSTOMER_ACTION",
9    "captured_amount": 0,
10    "latest_payment_attempt": {
11        "id": "att_sgstf4jnlgez7mjro4s_mhvwbb",
12        "amount": 30,
13        "currency": "USD",
14        "payment_method": {
15            "type": "ach_direct_debit",
16            "ach_direct_debit": {
17                "business_account": false,
18                "owner_name": "Alberta Bobbeth Charleson",
19                "owner_email": "[email protected]"
20            }
21        },
22        "payment_intent_id": "int_sgstf4jnlgez7mhvwbb",
23        "status": "AUTHENTICATION_REDIRECTED",
24        "captured_amount": 0,
25        "refunded_amount": 0,
26        "created_at": "2022-10-31T11:03:12+0000",
27        "updated_at": "2022-10-31T11:03:15+0000",
28        "settle_via": "airwallex",
29        "authentication_data": {
30            "ds_data": {},
31            "fraud_data": {
32                "score": "0"
33            },
34            "avs_result": "U",
35            "cvc_result": "U"
36        }
37    },
38    "created_at": "2022-10-31T11:03:08+0000",
39    "updated_at": "2022-10-31T11:03:15+0000",
40    "next_action": {
41        "type": "redirect",
42        "method": "GET",
43        "url": "https://checkout-staging.airwallex.com/#/page/sg/plaid/pay/txn_sgstdp2tngez7ml2082_mhvwbb?link_token=link-sandbox-f4d04f70-d9d9-414f-9d96-688d5a2464cd"
44    },
45    "base_amount": 30
46}

Option 2: Micro-deposit verification

You can also verify ACH Direct Debit with micro-deposits by providing the following payload.

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_hkstd5mlqg8lrt9hv28/confirm' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6  "request_id": "b5239ad2-fa88-41da-9b5f-cc0a28061890",
7  "payment_method": {
8    "type": "ach_direct_debit",
9    "ach_direct_debit": {
10      "account_number": "000003434346",
11      "aba_routing_number": "084106768",
12      "business_account": true,
13      "owner_name": "John doe",
14      "owner_email": "[email protected]"
15      }
16    }
17}'

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

JSON
1{
2    "created_at": "2022-03-25T08:56:55+0000",
3    "updated_at": "2022-03-25T08:57:02+0000",
4    "next_action": {
5        "type": "notify_micro_deposits",
6        "url": "https://checkout.airwallex.com/#/page/direct-debit-verify-account/hk/vfy_hkpd5nwckg88jzrlen8_zo9u84",
7        "micro_deposit_count": "2",
8        "email": "[email protected]"
9    }
10}

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 3: Send authorization email

Airwallex will send an authorization confirmation email on your behalf to shoppers. If you choose to turn off Airwallex notification email and send your own, you should use payment_intent.pending to trigger confirmation of each authorization to your shoppers. Please include below information either on downloadable copy on your website or through email.

The following is a sample mandate confirmation email that you can send：

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.

If the transaction fails after the request is sent to the bank, you can get the failed reason using payment_attempt.authorization_failed webhook.

JSON
1"error": {
2        "code": "processor_declined",
3        "message": "The payment provider declined this transaction. Please refer to the original response code.",
4        "provider_original_response_code": "R03"
5    }

You may also query the status of a payment anytime using Retrieve a PaymentIntent API

Shell
1GET /payment_intents/{id}

Test ACH Direct Debit

Use the following details to test ACH Direct Debit in the sandbox environment.

1. Account verification

1.1 Account verification using Plaid

1.2 Account verification using micro-deposits

2. Payment

Once the account has been verified successfully, you can initiate a payment intent.

3. Refund

After the payment succeeds, you can issue a refund.