Desktop/Mobile Website Browser

This guide describes how to offer EFT Pre-Authorized 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{
7    "request_id": "fb6210f7-a37b-437f-a4e0-5ceece2de12b",
8    "amount": 10,
9    "email": "[email protected]",
10    "phone": "+86-19100008888",
11    "currency": "CAD",
12    "merchant_order_id": "c591561e-9a9a-4374-b300-732ef48ca6f2",
13    "return_url": "https://www.airwallex.com",
14    "descriptor": "For internal testing",
15    "metadata": {
16        "test": "test"
17    }
18}
19' 

Example response:

JSON
1{
2    "id": "int_sgstcsjwdgsxmjtwlhl",
3    "request_id": "fb6210f7-a37b-437f-a4e0-5ceece2de12b",
4    "amount": 10,
5    "currency": "CAD",
6    "merchant_order_id": "c591561e-9a9a-4374-b300-732ef48ca6f2",
7    "descriptor": "vip8888",
8    "metadata": {
9        "test": "test"
10    },
11    "status": "REQUIRES_PAYMENT_METHOD",
12    "captured_amount": 0,
13    "created_at": "2024-01-30T03:31:29+0000",
14    "updated_at": "2024-01-30T03:31:29+0000",
15    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MDY1ODU0OTAsImV4cCI6MTcwNjU4OTA5MCwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiNjgwYjAyOWUtYzA5MC00MTI2LTkzYWMtZmZiYTUwYTZjNmQ3IiwiaW50ZW50X2lkIjoiaW50X3Nnc3Rjc2p3ZGdzeG1qdHdsaGwiLCJidXNpbmVzc19uYW1lIjoiSGlydGhlLCBUcm9tcCBhbmQgS292YWNlayJ9.B4S3D2uVPUeXW71rHJk7jd7nyRRoTsxHKmevWKJj60I",
16    "base_amount": 10,
17    "base_currency": "CAD"
18  }

If you want to skip verification for all transactions, please contact your Airwallex account manager for instructions.

Step 2. Get available payment methods

To be able to display EFT PAD as an option on your checkout page, you need to get available payment methods from Airwallex API.

When the PaymentIntent is created, send a GET request with parameters country_code, transaction_currency, transaction_mode to API endpoint /api/v1/pa/config/payment_method_types to query for a list of available payment method based on the information provided. The response will also contain the required fields and necessary resources of each payment method for you to display them on your page.

Example request:

Shell
1/api/v1/pa/config/payment_method_types?transaction_currency=CAD&transaction_mode=oneoff&country_code=CA

Example response: Render payment methods in items to show all available payment methods to the shopper at checkout page.

JSON
1{
2    "has_more": false,
3    "items": [
4        {
5            "name": "eft_direct_debit",
6            "transaction_mode": "oneoff",
7            "flows": [],
8            "transaction_currencies": [
9                "CAD"
10            ],
11            "country_codes": [
12                "*"
13            ],
14            "active": true
15        }
16    ]
17    ...
18}

Step 3. 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.

When a shopper submits EFT PAD on checkout form, you should use payment_intent/confirm to collect the mandate and complete the payment. For EFT PAD, we support two verification methods: Plaid and micro-deposit.

Option 1: Plaid verification

You can select the verification method by setting payment_method_options.eft_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_sgst6b57zgsxmq29aai/confirm' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer <your_bearer_token>' \
4--data '
5{
6  "request_id": "21bef56a-da91-4a8b-a105-1b8ffe797ae7",
7  "payment_method": {
8    "type": "eft_direct_debit",
9    "eft_direct_debit": {
10      "owner_name": "John Doe",
11      "owner_email": "[email protected]",
12      "verification_method": "plaid"
13    }
14  }
15}

Example response:

JSON
1{
2    "id": "int_sgst6b57zgsxmq29aai",
3    "request_id": "150fb199-f437-48e1-864d-7c180f314f30",
4    "amount": 10,
5    "currency": "CAD",
6    "merchant_order_id": "3d9a4b5c-1999-417f-93a7-e0865a6fedbb",
7    "descriptor": "For internal testing",
8    "status": "REQUIRES_CUSTOMER_ACTION",
9    "captured_amount": 0,
10    "latest_payment_attempt": {
11        "id": "att_sgst6b57zgsxmq2os5z_q29aai",
12        "amount": 10,
13        "currency": "CAD",
14        "payment_method": {
15            "type": "eft_direct_debit",
16            "eft_direct_debit": {
17                "business_account": false,
18                "owner_name": "John Doe",
19                "owner_email": "[email protected]"
20            }
21        },
22        "payment_intent_id": "int_sgst6b57zgsxmq29aai",
23        "status": "AUTHENTICATION_REDIRECTED",
24        "captured_amount": 0,
25        "refunded_amount": 0,
26        "created_at": "2024-01-30T03:37:47+0000",
27        "updated_at": "2024-01-30T03:37:50+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": "2024-01-30T03:37:46+0000",
39    "updated_at": "2024-01-30T03:37:50+0000",
40    "next_action": {
41        "type": "redirect",
42        "method": "GET",
43        "url": "https://checkout-staging.airwallex.com/#/page/sg/plaid/pay/txn_sgst9sv9cgsxmq2vizy_q29aai?link_token=link-sandbox-9d46a0a8-9cb7-4fd3-a2bd-f7fa401af05e"
44    },
45    "base_amount": 10,
46    "base_currency": "CAD"
47}

Option 2: Micro-deposit verification

You can also verify EFT PAD 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_sgstcsjwdgsxmveagis/confirm' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '
6{
7  "request_id": "b5239ad2-fa88-41da-9b5f-cc0a28061890",
8  "payment_method": {
9    "type": "eft_direct_debit",
10    "eft_direct_debit": {
11        "account_number": "0033441",
12        "institution_number": "010",
13        "transit_number": "04832",
14        "business_account": false,
15        "owner_name": "John Doe",
16        "owner_email": "[email protected]",
17        "mandate_version" : "1.0"
18    }
19  }
20}

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    "latest_payment_attempt": {
3        "id": "att_sgstcsjwdgsxmvemva9_veagis",
4        "amount": 10,
5        "currency": "CAD",
6        "payment_method": {
7            "id": "mtd_sgstcsjwdgsxmvekwao",
8            "type": "eft_direct_debit",
9            "eft_direct_debit": {
10                "account_number": "0033441",
11                "institution_number": "010",
12                "transit_number": "04832",
13                "business_account": false,
14                "owner_name": "Zhaofeng Wang",
15                "owner_email": "[email protected]",
16                "micro_deposit": {
17                    "status": "PENDING"
18                }
19            },
20            "status": "CREATED",
21            "created_at": "2024-01-30T03:43:09+0000",
22            "updated_at": "2024-01-30T03:43:09+0000"
23        },
24        "merchant_order_id": "4888ec17-db40-4986-8a92-445ddcb07c00",
25        "payment_intent_id": "int_sgstcsjwdgsxmveagis",
26        "payment_consent_id": "cst_sgstcsjwdgsxmveo4t6",
27        "status": "AUTHENTICATION_REDIRECTED",
28        "captured_amount": 0,
29        "refunded_amount": 0,
30        "created_at": "2024-01-30T03:43:09+0000",
31        "updated_at": "2024-01-30T03:43:13+0000",
32        "settle_via": "airwallex",
33        "authentication_data": {
34            "ds_data": {},
35            "fraud_data": {
36                "action": "VERIFY",
37                "score": "0"
38            },
39            "avs_result": "U",
40            "cvc_result": "U"
41        },
42        "payment_method_options": {
43            "card": {}
44        }
45    },
46    "id": "int_sgstcsjwdgsxmveagis",
47    "request_id": "993fb7d0-8927-47bf-85c4-8baf0097d4de",
48    "amount": 10,
49    "currency": "CAD",
50    "merchant_order_id": "4888ec17-db40-4986-8a92-445ddcb07c00",
51    "payment_consent_id": "cst_sgstcsjwdgsxmveo4t6",
52    "descriptor": "vip8888",
53    "metadata": {
54        "test": "test"
55    },
56    "status": "REQUIRES_CUSTOMER_ACTION",
57    "captured_amount": 0,
58    "created_at": "2024-01-30T03:43:09+0000",
59    "updated_at": "2024-01-30T03:43:13+0000",
60    "next_action": {
61        "type": "notify_micro_deposits",
62        "url": "https://checkout-staging.airwallex.com/#/page/direct-debit-verify-account/sg/vfy_sgst9sv9cgsxmvgcnln_veagis",
63        "micro_deposit_count": "2",
64        "email": "[email protected]"
65    },
66    "base_amount": 10,
67    "base_currency": "CAD"
68}

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.

Step 4. 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：

By providing your bank account details and confirming this payment, you authorize Airwallex US, LLC to electronically debit your account via EFT PAD 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.

Step 5. Wait for notifications from Airwallex

EFT PAD provides delayed notifications, which means that the transaction cannot be authorized instantly. An EFT PAD PaymentIntent remains in a pending state after submission to the EFT network. Once the payment succeeds, the associated PaymentIntent status updates from pending to succeeded.

The following events are sent when the PaymentIntent status is updated.

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": "901"
5    }

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

Shell
1GET /payment_intents/{id}

Test EFT PAD

Use the following details to test EFT PAD in the sandbox environment.

1. Account verification

1.1 Account verification using Plaid

1.2 Account verification using micro-deposits

2. Payment

3. Refund

EFT PAD return codes reference

There are currently 20 distinct EFT PAD return codes. This list will be continually updated.

The most common of which are:

The other return codes, which are less common, include: