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:
Shell1curl --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:
JSON1{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}
- Create a PaymentConsent API with the Customer ID from Step 1, and save Consent ID for subsequent transactions.
Example request
Shell1curl --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
JSON1{2 "id": "cst_sgstfvwszgf1fm9uk9w",3 "request_id": "5cf9360d-bb07-477e-b39d-0bcf7e6316fd",4 "customer_id": "cus_sgstpkhp5ga4vn7rqyo",5 "next_triggered_by": "merchant",6 "status": "REQUIRES_PAYMENT_METHOD",7 "created_at": "2022-11-02T11:25:18+0000",8 "updated_at": "2022-11-02T11:25:18+0000",9 "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NjczODgzMTgsImV4cCI6MTY2NzM5MTkxOCwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiMTc1MjY1YWMtMGVmZi00ODg4LTlhNDgtMzI4NTE3YmJmNGFhIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0ZnZ3c3pnZjFmbTl1azl3In0.ahMv_dfEx6wdY5R7iLR-ExzRPcVRO7yAFGDN0N3QvKY"10}
- 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. Airwallex offers two verification methods for Bacs Direct Debit: TrueLayer and micro-deposit verification.
TrueLayer verification
TrueLayer is an open banking solution that helps you verify bank accounts instantly and securely.
TrueLayer requires bank_name when confirming the PaymentIntent. You can call Get available bank names API with payment_method_type to get the supported banks.
Example request
Shell1url --request GET2--url 'https://api-demo.airwallex.com/api/v1/pa/config/banks?payment_method_type=bacs_direct_debit&country_code=UK'3--header 'Authorization: Bearer <your_bearer_token>'
Example response
1{2 "has_more": true,3 "items": [4 {5 "bank_name": "revolut",6 "display_name": "Revolut",7 "resources": {8 "logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/revolut.svg"9 }10 }11 ]12}
Set the verification method to truelayer using the payment_method.bacs_direct_debit.verification_method field in Verify a Payment Consent API. You can also provide owner_name and owner_email in the request so that the shopper will see these fields pre-filled on the confirmation page.
Example request
Shell1url --request POST2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_consents/cst_sgstr8wqfga4vna9wc1/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": "bacs_direct_debit",9 "bacs_direct_debit": {10 "bank_name": "revolut",11 "verification_method": "truelayer"12 }13 },14 "descriptor": "Airwallex",15 "return_url": "www.airwallex.com"16}'
Example response
JSON1{2 "id": "cst_sgstjjpnbgf6lw3e3x8",3 "request_id": "41525ca6-df01-411e-9a3c-1f63fe542e3d",4 "customer_id": "cus_sgstpkhp5ga4vn7rqyo",5 "payment_method": {6 "type": "bacs_direct_debit"7 },8 "next_triggered_by": "merchant",9 "metadata": {10 "amount": "100.0",11 "currency": "GBP",12 "schedule": "1st of month"13 },14 "status": "REQUIRES_CUSTOMER_ACTION",15 "created_at": "2022-11-07T04:03:13+0000",16 "updated_at": "2022-11-07T04:03:18+0000",17 "next_action": {18 "type": "redirect",19 "method": "GET",20 "url": "https://checkout-staging.airwallex.com/#/page/sg/truelayer/pay/txn_sgst9xh7gggzwh2ajrx_gxzhij?auth_url=https%3A%2F%2Fauth.truelayer-sandbox.com%3Fclient_id%3Dsandbox-airwallex-3066c0%26redirect_uri%3Dhttps%3A%2F%2Fcheckout-staging.airwallex.com%2Ftruelayer%2Fcallback%26providers%3Dmock%26state%3D6136811274633599%26response_type%3Dcode%26scope%3Dinfo%2520accounts%2520balance%2520offline_access%2520verification"21 }22}
Micro-deposit verification
Airwallex will send the micro-deposit verification email to the shopper to complete the verification process.
Example request
Shell1url --request POST \2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_consents/cst_sgstr8wqfga4vna9wc1/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": "bacs_direct_debit",9 "bacs_direct_debit": {10 "account_number": "000013232323233",11 "sort_code": "084106768",12 "owner_name": "John Doe",13 "owner_email": "[email protected]",14 "address": {15 "line1": "777 Casino Drive",16 "town": "LONDON",17 "postcode": "A11 B12"18 },19 "verification_method": "micro_deposit"20 }21 },22 "descriptor": "Airwallex",23 "return_url": "www.airwallex.com"24}'
Example response
JSON1{2 "id": "cst_sgstjjpnbgf6lw3e3x8",3 "request_id": "41525ca6-df01-411e-9a3c-1f63fe542e3d",4 "customer_id": "cus_sgstpkhp5ga4vn7rqyo",5 "payment_method": {6 "type": "bacs_direct_debit",7 "id": "mtd_sgstbzd9ngf6lw52enq",8 "bacs_direct_debit": {9 "account_number": "000013232323233",10 "sort_code": "084106768",11 "owner_name": "John doe",12 "bank_name": "revolut",13 "owner_email": "[email protected]"14 "address": {15 "line1": "777 Casino Drive",16 "town": "LONDON",17 "postcode": "A11 B12"18 }19 }20 },21 "next_triggered_by": "merchant",22 "metadata": {23 "amount": "100.0",24 "currency": "GBP",25 "schedule": "1st of month"26 },27 "status": "REQUIRES_CUSTOMER_ACTION",28 "created_at": "2022-11-07T04:03:13+0000",29 "updated_at": "2022-11-07T04:03:18+0000",30 "next_action": {31 "type": "notify_micro_deposits",32 "url": "https://checkout-staging.airwallex.com/#/page/direct-debit-verify-account/sg/vfy_sgstmfkqggf6lw60cse_w3e3x8",33 "micro_deposit_count": 2,34 "email": "[email protected]"35 },36 "mandate": {37 "accepted_at": "2022-11-07T04:03:15+0000",38 "version": "1.0"39 }40}
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.
TrueLayer verification
TrueLayer requires bank_name when confirming the PaymentIntent. You can call Get available bank names API with payment_method_type to get the supported banks.
Example request
Shell1--url 'https://api-demo.airwallex.com/api/v1/pa/config/banks?payment_method_type=bacs_direct_debit&country_code=UK'2--header 'Authorization: Bearer <your_bearer_token>'
Example response
JSON1{2 {3 "has_more": false,4 "items": [5 {6 "bank_name": "mock",7 "display_name": "Mock",8 "resources": {9 "logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/mock.svg"10 }11 }12 ]13}
Set the verification method to truelayer using the payment_method_options.bacs_direct_debit.verification_method field. You can also provide owner_name and owner_email in the request so that the shopper will see these fields pre-filled on the confirmation page.
Example request
Shell1url --request POST \2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm' \3--header 'Content-Type: application/json' \4--header 'Authorization: Bearer <your_bearer_token>' \5--data '6{7 "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",8 "payment_method": {9 "type": "bacs_direct_debit",10 "id": "mtd_sgstbzd9ngf6lw52enq",11 "bacs_direct_debit": {12 "bank_name": "revolut",13 "verification_method": "truelayer"14 }15 },16 "payment_consent_id": "cst_sgstfvwszgf1fm9uk9w"17}18}'
Example response
JSON1{2 "id": "int_sgstpf54lgf6t7z71eh",3 "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",4 "amount": 4.4,5 "currency": "GBP",6 "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",7 "customer_id": "cus_sgsts772qgf6t6fjpxb",8 "payment_consent_id": "cst_sgstpf54lgf6t6h2i0r",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": "GBP",16 "payment_method": {17 "type": "bacs_direct_debit",18 "bacs_direct_debit": {19 "owner_name": "John Doe",20 "owner_email": "[email protected]"21 "owner_address": "testing",22 "bank_name": "revolut"23 }24 },25 "payment_intent_id": "int_sgstpf54lgf6t7z71eh",26 "payment_consent_id": "cst_sgstpf54lgf6t6h2i0r",27 "status": "AUTHENTICATION_REDIRECTED",28 "captured_amount": 0,29 "refunded_amount": 0,30 "created_at": "2022-11-07T08:29:12+0000",31 "updated_at": "2022-11-07T08:29:16+0000",32 "settle_via": "airwallex",33 "authentication_data": {34 "ds_data": {},35 "fraud_data": {36 "score": "0"37 },38 "avs_result": "U",39 "cvc_result": "U"40 }41 },42 "created_at": "2022-11-07T08:29:09+0000",43 "updated_at": "2022-11-07T08:29:16+0000",44 "next_action": {45 "type": "redirect",46 "method": "GET",47 "url": "https://checkout-staging.airwallex.com/#/page/sg/truelayer/pay/txn_sgst9xh7gggzwh2ajrx_gxzhij?auth_url=https%3A%2F%2Fauth.truelayer-sandbox.com%3Fclient_id%3Dsandbox-airwallex-3066c0%26redirect_uri%3Dhttps%3A%2F%2Fcheckout-staging.airwallex.com%2Ftruelayer%2Fcallback%26providers%3Dmock%26state%3D6136811274633599%26response_type%3Dcode%26scope%3Dinfo%2520accounts%2520balance%2520offline_access%2520verification"48 },49 "base_amount": 4.450}
Micro-deposit verification
Example request
Shell1url --request POST \2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm' \3--header 'Content-Type: application/json' \4--header 'Authorization: Bearer <your_bearer_token>' \5--data '6{7 "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",8 "payment_method": {9 "type": "bacs_direct_debit",10 "id": "mtd_sgstbzd9ngf6lw52enq",11 "bacs_direct_debit": {12 "account_number": "000013232323233",13 "sort_code": "084106768",14 "owner_name": "John doe",15 "owner_email": "[email protected]"16 "address": {17 "line1": "777 Casino Drive",18 "town": "LONDON",19 "postcode": "A11 B12"20 },21 "verification_method": "micro_deposit"22 }23 },24 "payment_consent_id": "cst_sgstfvwszgf1fm9uk9w"25}26'
Example response
JSON1{2 "id": "int_sgstbn2sxgai33j69xs",3 "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",4 "amount": 4.4,5 "currency": "GBP",6 "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",7 "payment_consent_id": "cus_sgstpkhp5ga4vn7rqyo",8 "descriptor": "For internal testing",9 "status": "REQUIRES_CUSTOMER_ACTION",10 "captured_amount": 0,11 "latest_payment_attempt": {12 "id": "att_sgstjjpnbgf6o7wlijd_3j69xs",13 "amount": 4.4,14 "currency": "GBP",15 "payment_method": {16 "id": "mtd_sgstjjpnbgf6o7wftae",17 "customer_id": "cus_sgstjjpnbgf6lw15hwy",18 "type": "bacs_direct_debit",19 "bacs_direct_debit": {20 "account_number": "000013232323233",21 "sort_code": "084106768",22 "owner_name": "John doe",23 "bank_name": "revolut",24 "owner_email": "[email protected]"25 "address": {26 "line1": "777 Casino Drive",27 "town": "LONDON",28 "postcode": "A11 B12"29 }30 },31 "status": "CREATED",32 "created_at": "2022-11-07T05:27:40+0000",33 "updated_at": "2022-11-07T05:27:40+0000"34 },35 "payment_intent_id": "int_sgstbn2sxgai33j69xs",36 "payment_consent_id": "cus_sgstpkhp5ga4vn7rqyo",37 "status": "AUTHENTICATION_REDIRECTED",38 "captured_amount": 0,39 "refunded_amount": 0,40 "created_at": "2022-11-07T05:27:41+0000",41 "updated_at": "2022-11-07T05:27:49+0000",42 "settle_via": "airwallex",43 "authentication_data": {44 "ds_data": {},45 "fraud_data": {46 "action": "VERIFY",47 "score": "0"48 },49 "avs_result": "U",50 "cvc_result": "U"51 }52 },53 "created_at": "2022-11-07T05:27:22+0000",54 "updated_at": "2022-11-07T05:27:49+0000",55 "next_action": {56 "type": "notify_micro_deposits",57 "url": "https://checkout-staging.airwallex.com/#/page/direct-debit-verify-account/sg/vfy_sgstmfkqggf6o81nrm8_7lbs9n",58 "micro_deposit_count": "2",59 "email": "[email protected]"60 },61 "base_amount": 1062}
Successful verification will change the status of PaymentConsent to VERIFIED. If the PaymentConsent is not verified, the status will remain as PENDING_VERIFICATION, and next_action will appear in the response.
Initiate a subsequent transaction using stored bank account details
- Create a PaymentIntent API with the corresponding Customer ID.
Example request:
Shell1url --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 '{6 "request_id": "e71db33e-e191-48b1-82ae-ed19fdcc3fd9",7 "amount": 4.4,8 "currency": "GBP",9 "customer_id": "cus_sgstpkhp5ga4vn7rqyo",10 "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",11 "return_url": "https://www.airwallex.com",12 "descriptor": "For internal testing",13 "additional_data": "131231232"14}'
Example response:
JSON1{2 "id": "int_sgstbzd9ngf6oc3f6ce",3 "request_id": "e71db33e-e191-48b1-82ae-ed19fdcc3fd9",4 "amount": 4.4,5 "currency": "GBP",6 "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",7 "customer_id": "cus_sgstjjpnbgf6lw15hwy",8 "descriptor": "For internal testing",9 "status": "REQUIRES_PAYMENT_METHOD",10 "captured_amount": 0,11 "created_at": "2022-11-07T05:31:54+0000",12 "updated_at": "2022-11-07T05:31:54+0000",13 "available_payment_method_types": [14 "bacs_direct_debit"15 ],16 "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2Njc3OTkxMTQsImV4cCI6MTY2NzgwMjcxNCwidHlwZSI6ImNsaWVudC1zZWNyZXQiLCJwYWRjIjoiU0ciLCJhY2NvdW50X2lkIjoiMTc1MjY1YWMtMGVmZi00ODg4LTlhNDgtMzI4NTE3YmJmNGFhIiwiaW50ZW50X2lkIjoiaW50X3Nnc3RiemQ5bmdmNm9jM2Y2Y2UiLCJjdXN0b21lcl9pZCI6ImN1c19zZ3N0ampwbmJnZjZsdzE1aHd5IiwiYnVzaW5lc3NfbmFtZSI6IkdveWV0dGUgTExDIn0.bE164aOthTfFQYqcBro5fGbwvhw5w0RS3Y1MruCyHg0",17 "base_amount": 4.418}
- Confirm a PaymentIntent API with
payment_consent_reference.idto request payment with reference to the stored PaymentConsent.
Example request:
Shell1url --request POST \2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/int_sgstbn2sxgai33j69xs/confirm' \3--header 'Content-Type: application/json' \4--header 'Authorization: Bearer <your_bearer_token>' \5--data '{6 "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",7 "payment_consent_id": "cst_sgstr8wqfga4vna9wc1"8}'
Example response:
JSON1{2 "id": "int_sgstbn2sxgai33j69xs",3 "request_id": "c38579ad-4c08-4aad-9dbb-8965bd7c11ac",4 "amount": 4.4,5 "currency": "GBP",6 "customer_id": "cus_sgstpkhp5ga4vn7rqyo",7 "merchant_order_id": "ea95b90f-2ba5-43f8-a6ab-9fa2ce476426",8 "descriptor": "For internal testing",9 "status": "PENDING",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 PaymentConsents API with the corresponding
Customer IDto render the list of shopper’s payment methods they previously saved.
Example request:
Shell1url --request GET \2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_consents' \3--header 'Content-Type: application/json' \4--header 'Authorization: Bearer <your_bearer_token>' \
Example response:
JSON1{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": "bacs_direct_debit",10 "id": "mtd_sgstr8wqfga4vnabxmy",11 "bacs_direct_debit": {12 "account_number": "00000343435",13 "sort_code": "084106768",14 "owner_name": "John doe",15 "bank_name": "revolut",16 "owner_email": "[email protected]",17 "address": {18 "line1": "777 Casino Drive",19 "town": "LONDON",20 "postcode": "A11 B12"21 }22 }23 },24 "next_triggered_by": "merchant",25 "merchant_trigger_reason": "unscheduled",26 "status": "VERIFIED",27 "created_at": "2022-05-26T08:12:30+0000",28 "updated_at": "2022-05-26T08:12:30+0000",29 "client_secret": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NTM1NTI3NTEsImV4cCI6MTY1MzU1NjM1MSwiYWNjb3VudF9pZCI6ImRiMGJkMDgzLTlkZDUtNDk3ZC05ZGFkLWI3NGNkOGNiMWE4ZiIsImRhdGFfY2VudGVyX3JlZ2lvbiI6IlNHIiwiY29uc2VudF9pZCI6ImNzdF9zZ3N0cjh3cWZnYTR2bmE5d2MxIiwicGFkYyI6IlNHIn0.gqCk3eANNbn5DX7UpsA6uG8JoXksn3Yy7JSJaVTcqZg",30 "mandate": {31 "accepted_at": "2023-01-04T06:50:57+0000",32 "version": "1.0",33 "type": "bacs_direct_debit",34 "bacs_direct_debit": {35 "service_user_number": "Airwallex",36 "ddi_reference": "WBGGYOK87GZT"37 }38 }39 }40 ]41}
Was this page helpful?