Log inGet started
Airwallex logo
Home
Online Payments
Treasury
Transactional FX
Payouts
Issuing
Scale
Open Banking
Developer Tools
API Reference
Home
Online Payments
Overview
Starting with paymentsTransaction and settlement modelPricing model
Features
3D Secure authentication
Native API
Save payment details for future paymentsMulti-currency pricingFraud managementRiskNetwork TokenizationDisputes

Native API

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

3DSNativeAPI

  1. Create the PaymentIntent with the required 3DS settings to start the authentication process.

  2. Confirm the PaymentIntent by providing the payment method and return URL.

  3. Check the PaymentIntent status and build your implementation depending on the status parameter returned in the response.

  4. The value returned in the next.action.stage parameter 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 with latest_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 with latest_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.risk_control.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.risk_control.three_ds_action parameter.

ValueDescription
FORCE_3DSEnforces 3DS authentication on this payment using Airwallex’s 3DS provider.
EXTERNAL_3DSIndicates that you want to use your own 3DS provider. See FAQ.
SKIP_3DSIndicates that you want to skip 3DS regardless of the risk score.
nullIndicates 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

Shell

Example response

JSON

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 also the return URL, which is where the shopper will be redirected once authentication is complete. You can provide the return URL using the following parameters:

  • return_url: If you have already provided the return_url in Create a PaymentIntent API you can leave it empty.
  • payment_method_options.card.three_ds.return_url: You can provide a return URL in this parameter; however, the URL from the return_url parameter takes precedence over this parameter and will be used for subsequent actions.

To increase the likelihood of frictionless authentication, provide additional shopper information using the device_data object.

Example request

Shell

Example response

JSON

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.

statusDescription
REQUIRES_PAYMENT_METHODThe 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_ACTIONCustomer action such as 3DS authentication is pending. Inspect the following parameters in the next_action object for details: (1) If next_action.type= redirect_form then 3DS is required. (2) If next_action.stage= WAITING_DEVICE_DATA_COLLECTION then you will need to collect more data from the customer’s device for a frictionless flow. See Step 4a: Collect Device Data (3) If next_action.stage= WAITING_USER_INFO_INPUT then the data provided is not sufficient to the issuer and a challenge flow is required. See Step 4b: Render a 3DS iframe
REQUIRES_CAPTUREManual capture of authorisation is pending, which is required after calling the Confirm a PaymentIntent API with auto_capture=false
CANCELLEDThe PaymentIntent has been cancelled. The amount that was authorized but not captured will be returned.
SUCCEEDEDThe payment was successful, no further action required.

Frictionless flow

If issuer decides to use frictionless flow, you will get a response where:

  • status = SUCCEEDED
  • latest_payment_attempt.status = AUTHORIZED
  • next_action object is empty

This indicates that payment authorization was successfully completed.

Step 4a: Collect device data

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.

Render a hidden HTML iframe in the browser, and send an HTTP POST to the next_action.url with next_action.data.JWT and next_action.data.threeDSMethodData fields using content-type as application/x-www-form-urlencoded.

HTML

This will do a POST call to the return_url provided in Create a PaymentIntent API or Confirm a PaymentIntent API. The response contains issuer data that you need to provide to Airwallex in Continue to confirm a PaymentIntent API.

HTML

Submit issuer response

Submit the issuer response in Continue to confirm a PaymentIntent API using the following parameters:

  • three_ds.acs_response = <response from issuer>

  • type=3ds_continue

Also provide the return_url for a possible challenge flow callback in case the issuer decides to trigger a challenge flow.

Shell

Frictionless flow

If issuer decides to use a frictionless flow, you will get a response where:

  • status = SUCCEEDED
  • latest_payment_attempt.status = AUTHORIZED
  • next_action object is empty

This indicates that payment authorization was successfully completed.

JSON

Challenge flow

If issuer decides to use a challenge flow, you will get a response where:

  • status = REQUIRES_CUSTOMER_ACTION
  • latest_payment_attempt.status = AUTHENTICATION_REDIRECTED
  • next_action.stage = WAITING_USER_INFO_INPUT

See Step 4b: Present a challenge.

Step 4b: Present a challenge

If the response of Confirm a PaymentIntent API or Continue to confirm a PaymentIntent API returns the following then it indicates that the data provided is not sufficient or the issuer has decided to step up the authentication based on their risk requirements and a challenge flow is required.

  • status = REQUIRES_CUSTOMER_ACTION
  • latest_payment_attempt.status = AUTHENTICATION_REDIRECTED
  • next_action.stage = WAITING_USER_INFO_INPUT
JSON

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.

On submitting the form in the iframe, the iframe redirects to the issuer’s authentication UI to present the challenge to the shopper.

HTML

Once the shopper completes the challenge, the issuer will redirect the iframe to three_ds.return_url provided in Confirm a PaymentIntent API or Continue to confirm a PaymentIntent API by doing a POST call. The response contains issuer data that you need to provide to Airwallex in Continue to confirm a PaymentIntent API request.

HTML

Submit the issuer response

Submit the issuer response in Continue to confirm a PaymentIntent API request using the following parameters:

  • three_ds.acs_response = <response from issuer>
  • type=3ds_continue
Shell

If the shopper authenticated successfully on the challenge flow, you will get a response where:

  • status = SUCCEEDED
  • latest_payment_attempt.status = AUTHORIZED
  • next_action object is empty

This indicates that payment authorization was successfully completed.

If latest_payment_attempt.status = FAILED check the response code for next steps.

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.

Shell

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.

On this page