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

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

Example request:

Shell

xxxxxxxxxx
 
curl --request POST \
--url 'https://api-demo.airwallex.com/api/v1/pa/customers/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_bearer_token>' \
--data '{ 
  "request_id": "743c92db-289f-4e0c-a578-e902a56dbd46", 
  "merchant_customer_id": "661b4105-55ae-4acc-b672-92bbc8bd1e30", 
  "email": "john.doe@airwallex.com", 
  "phone_number": "15566668888", 
  "first_name":"John", 
  "last_name":"Doe", 
}' 

Example response:

JSON

xxxxxxxxxx
 
{
    "id": "cus_sgstpkhp5ga4vn7rqyo",
    "request_id": "743c92db-289f-4e0c-a578-e902a56dbd46",
    "merchant_customer_id": "661b4105-55ae-4acc-b672-92bbc8bd1e30",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@airwallex.com",
    "phone_number": "15566668888",
    "created_at": "2022-05-26T08:12:26+0000",
    "updated_at": "2022-05-26T08:12:26+0000"
}

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

Example request

Shell

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

Example response

JSON

xxxxxxxxxx
 
{
    "id": "cst_sgstfvwszgf1fm9uk9w",
    "request_id": "5cf9360d-bb07-477e-b39d-0bcf7e6316fd",
    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
    "next_triggered_by": "merchant",
    "status": "REQUIRES_PAYMENT_METHOD",
    "created_at": "2022-11-02T11:25:18+0000",
    "updated_at": "2022-11-02T11:25:18+0000",
    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NjczODgzMTgsImV4cCI6MTY2NzM5MTkxOCwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiMTc1MjY1YWMtMGVmZi00ODg4LTlhNDgtMzI4NTE3YmJmNGFhIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0ZnZ3c3pnZjFmbTl1azl3In0.ahMv_dfEx6wdY5R7iLR-ExzRPcVRO7yAFGDN0N3QvKY"
}

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

xxxxxxxxxx
 
url --request POST \
--url 'https://api-demo.airwallex.com/api/v1/pa/payment_consents/cst_sgstr8wqfga4vna9wc1/verify' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_bearer_token>' \
--data '{ 
    "request_id": "c8812204-0b15-4ae0-8758-26c4b601b055",
    "payment_method": {
        "type": "ach_direct_debit",
        "ach_direct_debit": {
            "business_account": true,
            "owner_name": "John doe",
            "owner_email": "wei.liu@airwallex.com"
        }
    },
    "verification_options": {
        "ach_direct_debit": {
            "method": "plaid"
        }
    },
    "descriptor": "Airwallex",
    "return_url": "www.baidu.com" 
}'

Example response

JSON

xxxxxxxxxx
 
{
   "id": "cst_sgstjjpnbgf6lw3e3x8",
    "request_id": "41525ca6-df01-411e-9a3c-1f63fe542e3d",
    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
    "payment_method": {
        "type": "ach_direct_debit"
    },
    "next_triggered_by": "customer",
    "requires_cvc": true,
    "metadata": {
        "amount": "100.0",
        "currency": "CNY",
        "schedule": "1st of month"
    },
    "status": "PENDING_VERIFICATION",
    "created_at": "2022-11-07T04:03:13+0000",
    "updated_at": "2022-11-07T04:03:18+0000",
    "next_action": {
        "type": "redirect",
        "method": "GET",
        "url": "https://checkout-staging.airwallex.com/#/page/sg/plaid/verify/txn_sgstmfkqggf6t6k1th6_6h2i0r?link_token=link-sandbox-a11208b1-af9b-4246-94a6-4c1e59ccee85"
    }
}

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 PaymentIntent API and Confirm a PaymentIntent API with payment_consent_id from Step 2. This will return SUCCEEDED status for the first payment if the verification is successfull.

Plaid verification

Example request:

Shell

xxxxxxxxxx
 
POST /api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm
{
  "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
  "payment_method": {
    "type": "ach_direct_debit",
    "id": "mtd_sgstbzd9ngf6lw52enq",
    "ach_direct_debit": {
      "business_account": true,
      "owner_name": "John doe",
      "owner_email": "john.doe@gmail.com"
    }
  },
  "payment_consent_reference": {
    "id": "cst_sgstfvwszgf1fm9uk9w"
  },
  "payment_method_options": {
    "ach_direct_debit": {
      "verification_method": "plaid"
    }
  }
}

Example response:

JSON

xxxxxxxxxx
}
{
    "id": "int_sgstpf54lgf6t7z71eh",
    "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
    "amount": 4.4,
    "currency": "USD",
    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
    "customer_id": "cus_sgsts772qgf6t6fjpxb",
    "payment_consent_id": "cst_sgstpf54lgf6t6h2i0r",
    "descriptor": "For internal testing",
    "status": "REQUIRES_CUSTOMER_ACTION",
    "captured_amount": 0,
    "latest_payment_attempt": {
        "id": "att_sgstpf54lgf6t817nlq_7z71eh",
        "amount": 4.4,
        "currency": "USD",
        "payment_method": {
            "type": "ach_direct_debit",
            "ach_direct_debit": {
                "business_account": false,
                "owner_name": "Wei Liu",
                "owner_email": "wei.liu@airwallex.com"
            }
        },
        "payment_intent_id": "int_sgstpf54lgf6t7z71eh",
        "payment_consent_id": "cst_sgstpf54lgf6t6h2i0r",
        "status": "AUTHENTICATION_REDIRECTED",
        "captured_amount": 0,
        "refunded_amount": 0,
        "created_at": "2022-11-07T08:29:12+0000",
        "updated_at": "2022-11-07T08:29:16+0000",

Initiate a subsequent transaction using stored bank account details

Create a PaymentIntent API with the corresponding Customer ID.

Example request:

Shell

xxxxxxxxxx
 
POST /api/v1/pa/payment_intents/create

Shell

xxxxxxxxxx
 
{
    "request_id": "20780f04-5eff-4227-af8e-4c4d2f4d68b7",
    "amount": 4.4,
    "email": "testing@airwallex.com",
    "phone": "+86-19100008888",
    "currency": "USD",
    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
    "return_url": "https://www.baidu.com",
    "descriptor": "For internal testing",
    "additional_data": "131231232"
}

Example response:

JSON

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

Confirm a PaymentIntent API with payment_consent_reference.id to request payment with reference to the stored PaymentConsent.

Example request:

Shell

xxxxxxxxxx
 
POST /api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm
​
{
  "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
  "payment_consent_reference": {
    "id": "cst_sgstr8wqfga4vna9wc1"
  }
}

Example response:

JSON

xxxxxxxxxx
 
{
    "id": "int_sgstbn2sxgai33j69xs",
    "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",
    "amount": 4.4,
    "currency": "USD",
    "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
    "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",
    "descriptor": "For internal testing",
    "status": "PENDING",
    "captured_amount": 0,
    "created_at": "2022-06-08T02:24:20+0000",
    "updated_at": "2022-06-08T02:24:20+0000",
    "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTQ2NTUwNjAsImV4cCI6MTY1NDY1ODY2MCwiYWNjb3VudF9pZCI6ImRiMGJkMDgzLTlkZDUtNDk3ZC05ZGFkLWI3NGNkOGNiMWE4ZiIsImludGVudF9pZCI6ImludF9zZ3N0bXpkNTJnYWl5MWd0czg1IiwicGFkYyI6IlNHIiwiYnVzaW5lc3NfbmFtZSI6IkdvcmN6YW55LCBNYWNlamtvdmljIGFuZCBKYWt1Ym93c2tpIn0.X_HQSYf8tbwjtZI2HzS9MjEbO1dTiQopyi-Pw6iny1I",
}

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

Example request:

Shell

xxxxxxxxxx
 
GET /api/v1/pa/payment_consents

Example response:

JSON

xxxxxxxxxx
}
{
    "has_more": false,
    "items": [
        {
            "id": "cst_sgstr8wqfga4vna9wc1",
            "request_id": "e06ba29c-aabc-4a17-accf-c08fe06f418d",
            "customer_id": "cus_sgstpkhp5ga4vn7rqyo",
            "payment_method": {
                "type": "ach_direct_debit",
                "id": "mtd_sgstr8wqfga4vnabxmy",
                "ach_direct_debit": {
                    "account_number": "00000343435",
                    "aba_routing_number": "084106768",
                    "business_account": true,
                    "owner_name": "John doe",
                    "owner_email": "john.doe@airwallex.com"
                }
            },
            "next_triggered_by": "merchant",
            "merchant_trigger_reason": "unscheduled",
            "status": "PENDING_VERIFICATION",
            "created_at": "2022-05-26T08:12:30+0000",
            "updated_at": "2022-05-26T08:12:30+0000",
            "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTM1NTI3NTEsImV4cCI6MTY1MzU1NjM1MSwiYWNjb3VudF9pZCI6ImRiMGJkMDgzLTlkZDUtNDk3ZC05ZGFkLWI3NGNkOGNiMWE4ZiIsImRhdGFfY2VudGVyX3JlZ2lvbiI6IlNHIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0cjh3cWZnYTR2bmE5d2MxIiwicGFkYyI6IlNHIn0.gqCk3eANNbn5DX7UpsA6uG8JoXksn3Yy7JSJaVTcqZg",
            "mandate": {
                "accepted_at": "2022-05-26T08:12:30+0000",
                "version": "1.0"
            }
        }
    ]