Native API (For API versions before 2024-06-14)
Please note that this guide is applicable only for API versions before 2024-06-14. Please refer to this page for later API versions.
Airwallex supports 3D Secure authentication on your Native API integration. This step-by-step guide describes how to implement 3DS frictionless and challenge flows in your integration using Airwallex’s 3DS provider, and verify if authentication and payment are successful.
How it works
Create the PaymentIntent with the required 3DS settings to start the authentication process.
Confirm the PaymentIntent by providing the payment method and return URL.
Check the PaymentIntent status and build your implementation depending on the
statusparameter returned in the response.The value returned in the
next_action.stageparameter determines the next steps:a) If you receive
next_action.stage=WAITING_DEVICE_DATA_COLLECTION, collect device data from the shopper. Render a hidden iframe on the browser, send a device data request to the issuer and submit the result to Airwallex. If you get a response withlatest_payment_attempt.status=AUTHORIZED, this indicates that 3DS2 authentication was frictionless, and the payment authorization was successfully completed.b) If you receive
next_action.stage=WAITING_USER_INFO_INPUT, present a challenge to the shopper. Depending on the issuer’s requirements, you may receive this response after you confirm the PaymentIntent or after you submit the result of device data collection to Airwallex. To handle a challenge flow, render an iframe, send a challenge request to the issuer and submit the challenge result to Airwallex. If you get a response withlatest_payment_attempt.status=AUTHORIZED, this indicates that 3DS2 authentication was successful, and the payment authorization was successfully completed.
Before you begin
Before you add 3DS to your integration, consider the following:
- If your bank (acquirer) and the shopper’s bank (issuer) are both located in the European Economic Area (EEA), 3DS will be automatically triggered to comply with Revised Payment Services Directive (PSD2) Strong Customer Authentication (SCA) regulations unless exemptions apply.
- You can configure risk score ranges in the Airwallex web app to decide whether or not to send a transaction for 3DS. This will ensure that 3DS will trigger only when required depending on the issuer’s requirements.
- Contact your Airwallex Account Manager to configure your preferred 3DS settings on your Airwallex account.
- By default, 3DS authentication is enabled on every payment using Airwallex’s 3DS provider.
- You can choose to use your own external 3DS provider for authentication instead of Airwallex’s 3DS provider. Once enabled, simply provide the 3DS values when you confirm the PaymentIntent else 3DS will be skipped. For more information, see FAQ.
- You can choose to skip 3DS authentication on all transactions regardless of the risk score from your risk management rules. This setting will depend on your risk profile and requires approval from Airwallex.
You can override these global settings on individual payments using the payment_method_options.card.three_ds_action parameter. See Step 1: Create a PaymentIntent.
Step 1: Create a PaymentIntent
When the shopper begins the checkout process, create a PaymentIntent using Create a PaymentIntent API.
You can choose to override your global 3DS settings on individual payments by providing a different value in the payment_method_options.card.three_ds_action parameter.
| Value | Description |
|---|---|
FORCE_3DS | Enforces 3DS authentication on this payment using Airwallex’s 3DS provider. |
EXTERNAL_3DS | Indicates that you want to use your own 3DS provider. See FAQ. |
SKIP_3DS | Indicates that you want to skip 3DS regardless of the risk score. |
null | Indicates that you want to use the default global 3DS settings. |
Providing EXTERNAL_3DS or SKIP_3DS is only allowed if Airwallex has configured this 3DS setting on your merchant account. If you provide a value that is not allowed based on your default settings, your payment request will be rejected. If you encounter any issues with these settings, contact your Airwallex Account Manager.
To increase the likelihood of frictionless authentication, create a Customer first by providing additional parameters such as customer name, email, billing, shipping, etc., in Create a Customer API and then provide the returned customer ID in Create a PaymentIntent API.
Example request
Example response
Step 2: Confirm the PaymentIntent
When your shopper is ready to complete their purchase, confirm the PaymentIntent using Confirm a PaymentIntent API to begin the process of collecting their payment. Make sure you provide the payment_method for the PaymentIntent and payment_method.card.three_ds.return_url where the shopper will be redirected once 3DS authentication is complete.
You can also provide a return_url in the request to redirect your shopper to page where they can view the payment status. Providing this parameter overrides the return_url from Create a PaymentIntent API
To increase the likelihood of frictionless authentication, provide additional shopper information using the device_data object.
Example request
Example response
For API versions before 2022-11-11, the next_action object supported the following values.
next_action.type:redirect_formnext_action.method:POSTForm parameters were included in
next_action.data.For more information, see Changelog API.
Step 3: Check the PaymentIntent status
After receiving a successful response to Confirm a PaymentIntent API, inspect the status parameter to decide on the next steps. Listed below are the possible values for the status parameter.
| status | Description | |
|---|---|---|
REQUIRES_PAYMENT_METHOD | The payment_method has not been provided when calling Confirm a PaymentIntent API. Or, the payment_method has failed during confirm, in which case you can provide a different payment method. | |
REQUIRES_CUSTOMER_ACTION | This status indicates that the issuer bank would like to collect additional device information of the cardholder or the issuer would like the customer to go through the challenge workflow to complete 3DS authentication. | |
REQUIRES_CAPTURE | Manual capture of authorization is pending, which is required after calling the Confirm a PaymentIntent API with auto_capture=false | |
CANCELLED | The PaymentIntent has been cancelled. The amount that was authorized but not captured will be returned. | |
SUCCEEDED | The payment was successful, no further action required. |
Frictionless flow
If issuer decides to use frictionless flow, you will get a response where:
status=SUCCEEDEDlatest_payment_attempt.status=AUTHORIZEDnext_actionobject is empty
This indicates that payment authorization was successfully completed.
Send a device data request to the issuer to increase the chances of frictionless authentication. Perform this step only if Confirm a Payment Intent API returns WAITING_DEVICE_DATA_COLLECTION in the next_action.stage parameter.
Step 4a: Collect device data
When next_action.type and next_action.method return redirect_iframe and GET respectively, render a hidden HTML iframe with src attribute set to next_action.url. This will redirect the request to the ACS / issuer to collect device data.
For API versions before 2022-11-11, next_action.type returns redirect_form. You will need to render a hidden iframe, and send an HTTP POST to the next_action.url with next_action.data fields as parameters using content-type as application/x-www-form-urlencoded. Since the request will be redirected to ACS / issuer to collect device data, we recommend you not to implement a retry logic in this step. Some issuers directly reject duplicate requests or your request will be stuck without any response.
Once the device data is collected, the iframe redirects to the URL provided in payment_method.card.three_ds.return_url of Confirm a PaymentIntent API request.
Submit issuer response
Submit the issuer response in Continue to confirm a PaymentIntent API using the following parameters:
type=3ds_continue
Also provide the three_ds.return_url for a possible challenge flow callback in case the issuer decides to trigger a challenge flow.
For API versions before 2022-11-11, the request should include three_ds.acs_response field with the issuer data received in the redirect response, for example "acs_response": "threeDSMethodData=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6Ij...."
Frictionless flow
If issuer decides to use a frictionless flow, you will get a response where:
status=SUCCEEDEDlatest_payment_attempt.status=AUTHORIZEDnext_actionobject is empty
This indicates that payment authorization was successfully completed.
Challenge flow
If issuer decides to use a challenge flow, you will get a response where:
status=REQUIRES_CUSTOMER_ACTIONlatest_payment_attempt.status=AUTHENTICATION_REDIRECTEDnext_action.stage=WAITING_USER_INFO_INPUT
Step 4b: Present a challenge
When the cardholder finishes the authentication process, the redirect sends them back to the return_url you specified in Create PaymentIntent API or Confirm a PaymentIntent API. The redirect also adds payment_intent_id, succeeded, error_code, and error_message in URL query parameters that your application can use to identify the PaymentIntent associated with the purchase.
You can identify if a transaction is processed via frictionless / challenge mode based on the “Frictionless” field in the Retrieve Paymentintent API API response. Refer response sample provided in step#2.
Render an iframe
Render an iframe in the browser to display the authentication page provided by the issuing bank. Choose a style that provides a seamless checkout experience to your shopper, who will complete the authentication challenge on this UI.
When next_action.type and next_action.method return redirect_iframe and GET respectively, render a hidden HTML iframe with src attribute set to next_action.url. This will redirect to the issuer’s authentication UI to present the challenge to the shopper.
For API versions before 2022-11-11, next_action.type returns redirect_form. You will need to render a hidden iframe, and send an HTTP POST to the next_action.url with next_action.data fields as parameters using content-type as application/x-www-form-urlencoded. Since the request will be redirected to ACS / issuer to present a challenge to the shopper, we recommend you not to implement a retry logic in this step. Some issuers directly reject duplicate requests or your request will be stuck without any response.
Once the shopper completes the challenge, the iframe redirects to the URL provided in payment_method.card.three_ds.return_url of Confirm a PaymentIntent API request.
Submit the issuer response
Submit the issuer response in Continue to confirm a PaymentIntent API request using the following parameters:
type=3ds_continue
If the shopper authenticated successfully on the challenge flow, you will get a response where:
status=SUCCEEDEDlatest_payment_attempt.status=AUTHORIZEDnext_actionobject is empty
This indicates that payment authorization was successfully completed.
If latest_payment_attempt.status = FAILED check the response code for next steps.
For API versions before 2022-11-11, the request should include three_ds.acs_response field with the issuer data received in the redirect response, for example "acs_response": "cres=eyJtZXNzYWdlVHlwZSI6IkNSZXMiLCJ0aHJ...."
Test your integration
Use the test card numbers from the Netcetera Simulator section to trigger different 3DS scenarios.
FAQ
I’m already integrated to an external 3DS provider. How do I complete a Airwallex payment using this provider?
If you are using your own external 3DS provider for authentication then you must contact your Airwallex Account Manager to configure your account for external 3DS. Once enabled, provide 3DS values for the fields in the payment_method_options.card.external_three_ds object when you confirm the PaymentIntent using the Confirm a PaymentIntent API. If you do not provide these values, then 3DS will be skipped.
What happens if 3DS is not available for a card or the issuer does not support 3DS?
This depends on the 3DS version being used, 3DS1 or 3DS2.
For 3DS2, the card schemes (Mastercard, Visa) can stand-in for the issuer and authenticate the transactions to provide frictionless checkout. You will still get the liability shift.
For 3DS1, the card schemes redirect you to the attempts server where you can provide the Cardholder Authentication Verification Value (CAVV)/Accountholder Authentication Value (AAV) for the transaction indicating that you have attempted the authentication but the issuer is unavailable for 3DS. You will still get the liability shift.
What card schemes are supported for 3DS?
Airwallex supports 3DS for all card schemes that you can use to accept payments, namely Mastercard (Mastercard Identity Check), Visa (Visa Secure), American Express (SafeKey), and UnionPay. For card schemes outside of the supported list, for example, Japan Credit Bureau (JCB), the payment will be rejected.