Native API (For API versions on or after 2024-06-14)
Please note that this guide is applicable only for API versions on or after 2024-06-14. Please refer to this page for earlier 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.Render the 3DS iframe to manage the 3DS authentication process
Handle the return URL, this step may change based on whether the return URL being a website URL or a server URL, please see detailed explanation in steps below.
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
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. |
Step 4: Render the 3DS iframe
When next_action.type and next_action.method return redirect_iframe and GET respectively, render an iframe in the browser to display the authentication page provided by the issuing bank or device data collection in the progress frame.
Choose a style that provides a seamless checkout experience to your shopper, who will complete the authentication challenge on this UI.
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.
As per EMVco guidelines for transactions on 3DS version 2.1.0 or after, issuers are required to show the 3DS content in the window with full screen and specific sizes in 600x400, 500x600, 390x400, 250x400 dimensions. It is recommended for you to render the iframe in one of the above mentioned sizes to optimise 3DS authentication process.
Once the 3DS authentication is completed, the iframe redirects to the URL provided in payment_method.card.three_ds.return_url of Confirm a PaymentIntent API request.
Step 5:Handle the return URL
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.
When RETURN_URL is a website URL
If you have provided your website's URL as the Return_URL in the Confirm Payment Intent API, you can post the 3DS finished event to the container window. Upon receiving the event in the container window, the window should make a query to the PaymentIntent and display the result accordingly.
All the latest browsers support postMessage e.g. IE 10+, Edge, Firefox 57+, safari 4+, iOS Safari, Opera mini, Chrome for Android, UC Browser, etc. So there will be no compatibility issues.
See this link for more details.
When RETURN_URL is a server URL
If you have provided a server URL as the Return_URL in the Confirm Payment Intent API API, you can get the PaymentIntent response from the req.body and display the result accordingly to the container window.
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.