Save bank details for future payments

This guide describes how to save shopper's bank details and use it for subsequent payments.

Save bank details for the first time

Step 1. Call Create a Customer API if it is a new customer and save the returned Customer ID.

Example request:

Shell

1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/pa/customers/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{ 
6  "request_id": "743c92db-289f-4e0c-a578-e902a56dbd46", 
7  "merchant_customer_id": "661b4105-55ae-4acc-b672-92bbc8bd1e30", 
8  "email": "[email protected]", 
9  "phone_number": "15566668888", 
10  "first_name":"John", 
11  "last_name":"Doe", 
12}'

Example response:

JSON

1{
2    "id": "cus_sgstpkhp5ga4vn7rqyo",
3    "request_id": "743c92db-289f-4e0c-a578-e902a56dbd46",
4    "merchant_customer_id": "661b4105-55ae-4acc-b672-92bbc8bd1e30",
5    "first_name": "John",
6    "last_name": "Doe",
7    "email": "[email protected]",
8    "phone_number": "15566668888",
9    "created_at": "2022-05-26T08:12:26+0000",
10    "updated_at": "2022-05-26T08:12:26+0000"
11}

Step 2. Create a Payment Consent API with the Customer ID from Step 1, and save Consent ID for subsequent transactions.

Example request

Shell

1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_consents/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{ 
6    "request_id": "e06ba29c-aabc-4a17-accf-c08fe06f418d", 
7    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
8    "next_triggered_by": "merchant", 
9    "merchant_trigger_reason": "unscheduled" 
10}'

Example response

JSON

1{
2    "id": "cst_sgstfvwszgf1fm9uk9w",
3    "request_id": "e06ba29c-aabc-4a17-accf-c08fe06f418d",
4    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
5    "next_triggered_by": "merchant",
6    "merchant_trigger_reason": "unscheduled",
7    "status": "REQUIRES_PAYMENT_METHOD",
8    "created_at": "2022-11-02T11:25:18+0000",
9    "updated_at": "2022-11-02T11:25:18+0000",
10    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NjczODgzMTgsImV4cCI6MTY2NzM5MTkxOCwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiMTc1MjY1YWMtMGVmZi00ODg4LTlhNDgtMzI4NTE3YmJmNGFhIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0ZnZ3c3pnZjFmbTl1azl3In0.ahMv_dfEx6wdY5R7iLR-ExzRPcVRO7yAFGDN0N3QvKY"
11}

Step 3. Verify a PaymentConsent through a transaction authorization or verification. You have two options to get the PaymentConsent verified.

Option 1: Save bank account details without a payment

The shopper only attaches the bank account details for future payments.

Plaid verification

Plaid is an open banking solution that helps you verify bank accounts instantly and securely.

Example request

Shell

1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_consents/cst_sgstfvwszgf1fm9uk9w/verify' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{ 
6    "request_id": "c8812204-0b15-4ae0-8758-26c4b601b055",
7    "payment_method": {
8        "type": "ach_direct_debit",
9        "ach_direct_debit": {
10            "business_account": true,
11            "owner_name": "Alberta Bobbeth Charleson",
12            "owner_email": "[email protected]"
13        }
14    },
15    "verification_options": {
16        "ach_direct_debit": {
17            "method": "plaid"
18        }
19    },
20    "descriptor": "Airwallex",
21    "return_url": "www.baidu.com" 
22}'

Example response

JSON

1{
2    "id": "cst_sgstfvwszgf1fm9uk9w",
3    "request_id": "c8812204-0b15-4ae0-8758-26c4b601b055",
4    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
5    "payment_method": {
6        "type": "ach_direct_debit"
7    },
8    "next_triggered_by": "merchant",
9    "merchant_trigger_reason": "unscheduled",
10    "requires_cvc": true,
11    "metadata": {
12        "amount": "100.0",
13        "currency": "CNY",
14        "schedule": "1st of month"
15    },
16    "status": "REQUIRES_CUSTOMER_ACTION",
17    "created_at": "2022-11-07T04:03:13+0000",
18    "updated_at": "2022-11-07T04:03:18+0000",
19    "next_action": {
20        "type": "redirect",
21        "method": "GET",
22        "url": "https://checkout-staging.airwallex.com/#/page/sg/plaid/verify/txn_sgstmfkqggf6t6k1th6_6h2i0r?link_token=link-sandbox-a11208b1-af9b-4246-94a6-4c1e59ccee85"
23    }
24}

Option 2: Save bank account details during payment

The shopper pays for the first order and attaches the bank account details for future payments. You can Create a Payment Intent API and Confirm a Payment Intent API with payment_consent_id from Step 2. This will return SUCCEEDED status for the first payment if the verification is successful.

Plaid verification

Example request:

POST /api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm

JSON

1{
2  "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
3  "payment_method": {
4    "type": "ach_direct_debit",
5    "id": "mtd_sgstbzd9ngf6lw52enq",
6    "ach_direct_debit": {
7        "business_account": true,
8        "owner_name": "Alberta Bobbeth Charleson",
9        "owner_email": "[email protected]",
10        "verification_method": "plaid"
11    }
12  },
13  "payment_consent_id": "cst_sgstfvwszgf1fm9uk9w",
14  "payment_method_options": {
15    "ach_direct_debit": {
16        "verification_method": "plaid"
17    }
18  }
19}

Example response:

JSON

1{
2    "id": "int_sgstbn2sxgai33j69xs",
3    "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
4    "amount": 4.4,
5    "currency": "USD",
6    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
7    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
8    "payment_consent_id": "cst_sgstfvwszgf1fm9uk9w",
9    "descriptor": "For internal testing",
10    "status": "REQUIRES_CUSTOMER_ACTION",
11    "captured_amount": 0,
12    "latest_payment_attempt": {
13        "id": "att_sgstpf54lgf6t817nlq_7z71eh",
14        "amount": 4.4,
15        "currency": "USD",
16        "payment_method": {
17            "type": "ach_direct_debit",
18            "ach_direct_debit": {
19                "business_account": true,
20                "owner_name": "Alberta Bobbeth Charleson",
21                "owner_email": "[email protected]"
22            }
23        },
24        "payment_intent_id": "int_sgstbn2sxgai33j69xs",
25        "payment_consent_id": "cst_sgstfvwszgf1fm9uk9w",
26        "status": "AUTHENTICATION_REDIRECTED",
27        "captured_amount": 0,
28        "refunded_amount": 0,
29        "created_at": "2022-11-07T08:29:12+0000",
30        "updated_at": "2022-11-07T08:29:16+0000",
31        "settle_via": "airwallex",
32        "authentication_data": {
33            "ds_data": {},
34            "fraud_data": {
35                "score": "0"
36            },
37            "avs_result": "U",
38            "cvc_result": "U"
39        }
40    },
41    "created_at": "2022-11-07T08:29:09+0000",
42    "updated_at": "2022-11-07T08:29:16+0000",
43    "next_action": {
44        "type": "redirect",
45        "method": "GET",
46        "url": "https://checkout-staging.airwallex.com/#/page/sg/plaid/pay/txn_sgstmfkqggf6t82emp1_7z71eh?link_token=link-sandbox-68861238-5db8-44eb-8615-20c99cb22271"
47    },
48    "payment_method_options": {
49      "ach_direct_debit": {
50        "verification_method": "plaid"
51      }
52    },
53    "base_amount": 4.4
54}

Initiate a subsequent transaction using stored bank account details

Create a Payment Intent API with the corresponding Customer ID.

Example request:

POST /api/v1/pa/payment_intents/create

JSON

1{
2    "request_id": "20780f04-5eff-4227-af8e-4c4d2f4d68b7",
3    "amount": 4.4,
4    "email": "[email protected]",
5    "phone": "+86-19100008888",
6    "currency": "USD",
7    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
8    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
9    "return_url": "https://www.baidu.com",
10    "descriptor": "For internal testing",
11    "additional_data": "131231232"
12}

Example response:

JSON

1{
2    "id": "int_sgstbn2sxgai33j69xs",
3    "request_id": "20780f04-5eff-4227-af8e-4c4d2f4d68b7",
4    "amount": 4.4,
5    "currency": "USD",
6    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
7    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
8    "descriptor": "For internal testing",
9    "status": "REQUIRES_PAYMENT_METHOD",
10    "captured_amount": 0,
11    "created_at": "2022-06-07T07:41:44+0000",
12    "updated_at": "2022-06-07T07:41:45+0000",
13    "available_payment_method_types": [
14        "ach_direct_debit"
15    ],
16    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTQ1ODc3MDUsImV4cCI6MTY1NDU5MTMwNSwiYWNjb3VudF9pZCI6ImRiMGJkMDgzLTlkZDUtNDk3ZC05ZGFkLWI3NGNkOGNiMWE4ZiIsImludGVudF9pZCI6ImludF9zZ3N0Ym4yc3hnYWkzM2o2OXhzIiwicGFkYyI6IlNHIiwiYnVzaW5lc3NfbmFtZSI6IkdvcmN6YW55LCBNYWNlamtvdmljIGFuZCBKYWt1Ym93c2tpIn0.zjunyrRE4Wq1YTUUQBqWt4ACmL_rJCnhIR81OM1Fl8k",
17}

Confirm a Payment Intent API with payment_consent.id to request payment with reference to the stored PaymentConsent.

Example request:

POST /api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm

JSON

1{
2    "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
3    "payment_consent_id": "cst_sgstfvwszgf1fm9uk9w"
4}

Example response:

JSON

1{
2    "id": "int_sgstbn2sxgai33j69xs",
3    "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
4    "amount": 4.4,
5    "currency": "USD",
6    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
7    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
8    "descriptor": "For internal testing",
9    "status": "SUCCEEDED",
10    "captured_amount": 0,
11    "created_at": "2022-06-08T02:24:20+0000",
12    "updated_at": "2022-06-08T02:24:20+0000",
13    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTQ2NTUwNjAsImV4cCI6MTY1NDY1ODY2MCwiYWNjb3VudF9pZCI6ImRiMGJkMDgzLTlkZDUtNDk3ZC05ZGFkLWI3NGNkOGNiMWE4ZiIsImludGVudF9pZCI6ImludF9zZ3N0bXpkNTJnYWl5MWd0czg1IiwicGFkYyI6IlNHIiwiYnVzaW5lc3NfbmFtZSI6IkdvcmN6YW55LCBNYWNlamtvdmljIGFuZCBKYWt1Ym93c2tpIn0.X_HQSYf8tbwjtZI2HzS9MjEbO1dTiQopyi-Pw6iny1I",
14}

You can also get a list of Payment Consents API with the corresponding Customer ID to render the list of shopper's payment methods they previously saved.

Example request:

GET /api/v1/pa/payment_consents

Example response:

JSON

1{
2    "has_more": false,
3    "items": [
4        {
5            "id": "cst_sgstr8wqfga4vna9wc1",
6            "request_id": "e06ba29c-aabc-4a17-accf-c08fe06f418d",
7            "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
8            "payment_method": {
9                "type": "ach_direct_debit",
10                "id": "mtd_sgstr8wqfga4vnabxmy",
11                "ach_direct_debit": {
12                    "account_number": "00000343435",
13                    "aba_routing_number": "084106768",
14                    "business_account": true,
15                    "owner_name": "Alberta Bobbeth Charleson",
16                    "owner_email": "[email protected]"
17                }
18            },
19            "next_triggered_by": "merchant",
20            "merchant_trigger_reason": "unscheduled",
21            "status": "PENDING_VERIFICATION",
22            "created_at": "2022-05-26T08:12:30+0000",
23            "updated_at": "2022-05-26T08:12:30+0000",
24            "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTM1NTI3NTEsImV4cCI6MTY1MzU1NjM1MSwiYWNjb3VudF9pZCI6ImRiMGJkMDgzLTlkZDUtNDk3ZC05ZGFkLWI3NGNkOGNiMWE4ZiIsImRhdGFfY2VudGVyX3JlZ2lvbiI6IlNHIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0cjh3cWZnYTR2bmE5d2MxIiwicGFkYyI6IlNHIn0.gqCk3eANNbn5DX7UpsA6uG8JoXksn3Yy7JSJaVTcqZg",
25            "mandate": {
26                "accepted_at": "2022-05-26T08:12:30+0000",
27                "version": "1.0"
28            }
29        }
30    ]
31}

Was this page helpful?