Authenticate with 3D Secure

Integrate 3D Secure (3DS) authentication into your checkout flow across multiple platforms, including Web, iOS, Android, and React Native. When supported by the cardholder's issuing bank, Onerway automatically runs 3D Secure 2 (3DS2), falling back to 3D Secure 1 when necessary.

Control the 3DS flow

Onerway triggers 3DS automatically if:

• Regulations mandate it (such as SCA in Europe, PSD2 in the UK)
• Industry guidelines require it (such as Japan's Credit Card Security Guidelines)
• An issuer requests it with a soft declineTODO code
• Onerway's risk assessment recommends it

You can also use the API to decide when to prompt users for 3DS authentication. This allows you to customize the authentication process based on your business requirements. However, not all transactions support 3DS—for example, digital wallet payments or offline deductions.

When a payment triggers 3DS, the issuer might require the customer to authenticate, as long as the card supports 3DS. While Onerway initiates the authentication request, the requirement comes from the issuer. Depending on your frontend, you might need to display the 3DS flow.

Typical payment flow with 3DS

In a typical checkout payment flow that triggers 3DS:

1. The user enters their payment information, and the merchant submits the order request through the checkout payment APIPayments API, including card information and order details.
2. Onerway assesses if the transaction supports and requires 3DS based on:

• Regional regulatory requirements
• Merchant-configured risk rules
• 3DS parameter settings in the API request
• Issuer soft decline responses
• Transaction risk level assessment

3. If 3DS is:

• Not required: For example, because of an exemption, Onerway attempts the charge directly. The order transitions to a status of P (Processing). If the issuer returns a soft decline requiring 3DS, the system automatically reattempts with 3DS.
• Not supported: Onerway determines whether to continue based on the reason 3DS was triggered. If allowed, the order transitions to P (Processing). If not allowed, it transitions to F (Failed) with an error message.
• Required: Onerway starts the 3DS authentication flow by contacting the issuer's 3DS Access Control Server (ACS). The order transitions to R (Pending Authentication).

4. When 3DS flow information is received from the issuer, Onerway submits the request for the issuer to authenticate the cardholder:

• Challenge Flow: The cardholder completes an additional authentication step (such as entering an OTP or password).
• Frictionless Flow: The issuer authenticates the cardholder in the background without additional input.

5. Based on the 3DS authentication result:

• Authenticated (Y): Onerway attempts the charge. If successful, the order transitions to S (Payment Successful).
• Failed (N): The order transitions to F (Payment Failed). Guide the user to try a different payment method, or retry 3DS by creating a new payment.

Track 3DS authentication

To track whether 3DS was supported and attempted on a card payment, check the VerificationResult object returned in the payment response or order query API. Onerway populates this field when the customer attempts 3DS authentication:

Manually request 3DS through API

The default method to trigger 3DS is for Onerway to dynamically request 3D Secure based on risk level and other requirements. Triggering 3DS manually is for advanced users integrating Onerway with their own fraud engine.

To trigger 3DS manually, set risk3dsStrategy and related parameters in the mpiInfo object when calling the checkout payment API:

{
  "risk3dsStrategy": "EXTERNAL",
  "mpiInfo": "{\"eci\":\"05\",\"cavv\":\"AJkBBmUXZlVEZHlkdxdmAAAAAAA=\",\"dsTransID\":\"\",\"xid\":\"AJkBBmUXZlVEZHlkdxdmAAAAAAA=\"}"
}

When to provide this parameter depends on when your fraud engine detects risk:

• If your fraud engine only inspects card details, you know whether to request 3DS before calling the API.
• If your fraud engine inspects both card and transaction details, provide the parameter after you have complete transaction information.

3DS flow

After calling the checkout payment API, Onerway returns a payment page link (redirectUrl). Redirect the user to this page to complete payment and authentication.

Onerway collects basic device and transaction information during 3DS2 authentication and sends it to the issuing bank for risk analysis.

Redirect to Onerway checkout

When calling the checkout payment API, pass notifyUrl (async notification URL) and returnUrl (sync redirect URL) in the request parameters.

After successful submission, Onerway returns redirectUrl. Redirect the user to this address to complete payment. If the transaction requires 3DS verification, the user completes authentication within the checkout page. After verification:

1. The user is redirected back to returnUrl
2. Onerway sends an async payment result notification to notifyUrl

The redirect appends orderNo (merchant order number) as a query parameter to returnUrl, which your application can use to identify and query payment results.

Checkout page display

The Onerway checkout page UI is controlled by Onerway. Merchants can partially customize fonts, colors, and layout. The 3DS verification interface is controlled by the issuing bank and cannot be customized.

You can choose how to navigate to the checkout page:

• Window redirect: Redirect the current window (most common)
• New tab: Open in a new browser tab
• iframe: Embed the checkout page (note cross-origin and payment experience considerations)

Initiate payment request

When your customer is ready to complete a purchase, call the Onerway checkout payment API to create a payment session:

{
  "billingInformation": "{\"address\":\"71969 Cormier Mountain\",\"city\":\"Yakima\",\"country\":\"US\",\"email\":\"Watson91@gmail.com\",\"firstName\":\"Lyric\",\"lastName\":\"Morissette\",\"phone\":\"14848980027\",\"postalCode\":\"83406\",\"province\":\"CO\"}",
  "merchantCustId": "CustId-1F6O-9KB6",
  "merchantNo": "800209",
  "merchantTxnId": "e868e769-afe5-41f7-9882-04835122e0b3",
  "merchantTxnTime": "2025-04-18 14:47:42",
  "orderAmount": "3",
  "orderCurrency": "USD",
  "productType": "CARD",
  "subProductType": "DIRECT",
  "txnType": "SALE",
  "txnOrderMsg": "{\"returnUrl\":\"https://example.com/return\",\"notifyUrl\":\"https://example.com/webhook\"}"
}

To append order information to the return URL:

{
  "txnOrderMsg": "{\"returnUrl\":\"https://example.com/return?orderNo=2003042447256858624\"}"
}

Check order status

Check the status field through WebhookPayments API notifications or by querying the transaction status APIPayments API to determine if the payment completed successfully:

Automated 3DS handling

The Onerway checkout automatically handles the 3DS verification flow. Merchants don't need to check status on the client side or manually render iframes.

The automated flow:

1. User fills in card information on the Onerway checkout and submits
2. Onerway system automatically detects whether 3DS verification is needed
3. If required, the checkout displays the 3DS verification interface
4. User completes bank verification (enters OTP, password, etc.)
5. After verification, Onerway processes the payment result
6. User is redirected to the merchant's returnUrl
7. Onerway sends a Webhook notification to the merchant's notifyUrl

Disputes and liability shift

The liability shift rule typically applies to payments successfully authenticated using 3DS. In some cases, liability shift applies with equivalent cryptograms, such as Apple Pay or Google Pay. If a cardholder disputes a 3DS payment as fraudulent, liability typically shifts from you to the issuer.

If a card doesn't support 3DS or an error occurs during authentication, the payment proceeds normally. When this occurs, liability doesn't generally shift to the issuer because successful 3DS authentication hasn't taken place.

In practice, this means you typically won't receive disputes marked as fraudulent if the payment is covered by liability shift, but you might still receive an Early Fraud Warning.

Respond to dispute inquiries

You might receive a dispute inquiry on a successfully authenticated 3DS payment. This type of dispute doesn't precipitate a chargeback because it's only a request for information.

To prevent no-reply chargebacks, submit sufficient information about the charge:

• What was ordered
• How it was delivered
• Who it was delivered to (physical goods, electronic goods, or services)

When liability shift applies

Liability shift can also occur when the card network requires 3DS, but it isn't available for the card or issuer. This can happen if:

• The issuer's 3DS provider is down
• The issuer doesn't support 3DS despite the card network requiring it

During payment, the cardholder isn't prompted to complete 3DS authentication because the card isn't enrolled. Although the cardholder didn't complete authentication, liability can still shift to the issuer.

Onerway returns the requested ECI value in the electronic_commerce_indicator field of the 3DS verification result. This indicator helps determine whether a charge should adhere to liability shift rules. Since 3DS occurs after the initial payment response, you typically get this from Webhooks or query API results.

When liability shift doesn't apply