3D Secure (3DS)

3D Secure adds an additional authentication step for card payments, reducing fraud and shifting liability from the merchant to the card issuer. Axra handles 3DS transparently — your integration is the same regardless of the card network or issuing bank.

How 3DS Works

3DS introduces a challenge step where the cardholder’s bank verifies their identity (via SMS code, biometric, or app confirmation) before the payment is authorized.

Integration Flow

Server-to-Server (S2S) 3DS Flow

 Your Server                    Axra API                     Card Network             Issuing Bank
     |                             |                              |                        |
     |  1. POST /payment/charge    |                              |                        |
     |  (card + returnUrl)         |                              |                        |
     |---------------------------->|                              |                        |
     |                             |  2. Forward charge request   |                        |
     |                             |----------------------------->|                        |
     |                             |                              |  3. Check 3DS required |
     |                             |                              |----------------------->|
     |                             |                              |  4. 3DS challenge URL  |
     |                             |                              |<-----------------------|
     |                             |  5. Return requires_action   |                        |
     |                             |<-----------------------------|                        |
     |  6. Response:               |                              |                        |
     |  {status: requires_action,  |                              |                        |
     |   requiresAction: {         |                              |                        |
     |     redirectUrl: "..."      |                              |                        |
     |   }}                        |                              |                        |
     |<----------------------------|                              |                        |
     |                             |                              |                        |
     |  7. Redirect customer       |                              |                        |
     |  to redirectUrl             |                              |                        |
     |.............................>|  (customer's browser)        |                        |
     |                             |                              |                        |
     |                             |         8. Customer completes 3DS challenge           |
     |                             |                              |<--- - - - - - - - - -->|
     |                             |                              |                        |
     |                             |  9. Customer redirected to returnUrl                  |
     |<.............................| (customer's browser)         |                        |
     |                             |                              |                        |
     | 10. POST /payment/confirm-3ds                              |                        |
     |  {transactionId}            |                              |                        |
     |---------------------------->|                              |                        |
     |                             | 11. Confirm payment          |                        |
     |                             |----------------------------->|                        |
     |                             |                              | 12. Verify with issuer |
     |                             |                              |----------------------->|
     |                             |                              | 13. Auth result        |
     |                             |                              |<-----------------------|
     |                             | 14. Charge result            |                        |
     |                             |<-----------------------------|                        |
     | 15. Response:               |                              |                        |
     | {status: succeeded}         |                              |                        |
     |<----------------------------|                              |                        |
     |                             |                              |                        |
     |                    16. Webhook: payment.completed           |                        |
     |<----------------------------|                              |                        |
     |                             |                              |                        |

Checkout Session 3DS Flow

For checkout sessions, 3DS is handled entirely within the Axra-hosted checkout page. The customer never leaves the checkout experience.

 Your Server                    Axra API              Checkout Page          Card Network
     |                             |                      |                       |
     |  1. POST /payment/session   |                      |                       |
     |---------------------------->|                      |                       |
     |  2. {checkoutUrl}           |                      |                       |
     |<----------------------------|                      |                       |
     |                             |                      |                       |
     |  3. Redirect customer       |                      |                       |
     |  to checkoutUrl             |                      |                       |
     |.............................>|  4. Load session     |                       |
     |                             |--------------------->|                       |
     |                             |                      |                       |
     |                             |     5. Customer enters card & submits        |
     |                             |                      |                       |
     |                             |  6. POST /checkout/session/:id/charge        |
     |                             |<---------------------|                       |
     |                             |                      |                       |
     |                             |  7. Process charge   |                       |
     |                             |--------------------------------------------->|
     |                             |  8. requires_action  |                       |
     |                             |<---------------------------------------------|
     |                             |                      |                       |
     |                             |  9. Return 3DS URL   |                       |
     |                             |--------------------->|                       |
     |                             |                      | 10. Show 3DS iframe   |
     |                             |                      |  or redirect          |
     |                             |                      |                       |
     |                             |                      | 11. Customer completes|
     |                             |                      |  3DS challenge        |
     |                             |                      |                       |
     |                             | 12. POST /checkout/session/:id/confirm-3ds   |
     |                             |<---------------------|                       |
     |                             |                      |                       |
     |                             | 13. Confirm payment  |                       |
     |                             |--------------------------------------------->|
     |                             | 14. Succeeded        |                       |
     |                             |<---------------------------------------------|
     |                             |                      |                       |
     |                             | 15. Redirect to      |                       |
     |                             |     successUrl       |                       |
     |                             |--------------------->|                       |
     |                             |                      |                       |
     |            16. Webhook: payment.completed          |                       |
     |<----------------------------|                      |                       |
     |                             |                      |                       |

Implementation Guide

Step 1: Initiate the Charge

Include a returnUrl in your charge request. This is where the customer will be redirected after completing the 3DS challenge.

curl -X POST https://api.useaxra.com/api/v1/business/payment/charge \
  -H "x-api-key: bk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.99,
    "currency": "usd",
    "card": {
      "number": "4000002500003155",
      "expiryMonth": 12,
      "expiryYear": 2028,
      "cvv": "123"
    },
    "returnUrl": "https://yoursite.com/payment/3ds-return?order=1234",
    "customerIp": "203.0.113.42"
  }'

Step 2: Check for 3DS Requirement

Inspect the response. If status is requires_action, the customer must complete a 3DS challenge.

{
  "paymentId": "bpay_01H...",
  "status": "requires_action",
  "transactionId": "txn_3Abc...",
  "requiresAction": {
    "type": "3ds_redirect",
    "redirectUrl": "https://pay.useaxra.com/3ds/authenticate?..."
  }
}

The requiresAction object contains:

Field	Type	Description
`type`	string	`3ds_redirect`, `3ds_challenge`, or `fingerprint`
`redirectUrl`	string	URL to redirect the customer for authentication

Step 3: Redirect the Customer

Redirect the customer’s browser to the redirectUrl:

// React / Next.js
if (response.status === 'requires_action') {
  window.location.href = response.requiresAction.redirectUrl;
}

Step 4: Handle the Return

After the customer completes (or cancels) the 3DS challenge, they are redirected to your returnUrl. Confirm the payment:

curl -X POST https://api.useaxra.com/api/v1/business/payment/confirm-3ds \
  -H "x-api-key: bk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_3Abc..."
  }'

Step 5: Handle the Result

const result = await confirmPayment(transactionId);

if (result.status === 'succeeded') {
  // Payment confirmed! Wait for payment.completed webhook
  // to update order status in your system.
  showSuccessPage();
} else if (result.status === 'failed') {
  // 3DS authentication failed or was declined
  showErrorPage('Payment authentication failed. Please try again.');
}

When is 3DS Required?

3DS may be triggered by:

Card issuer rules: Some issuers require 3DS for all online transactions
SCA regulation (PSD2): Required for European card payments over certain thresholds
Risk scoring: Axra’s risk engine may trigger 3DS for suspicious transactions
Amount thresholds: Some regions require 3DS above certain amounts

Not all transactions will require 3DS. When 3DS is not needed, the charge completes immediately with status: "succeeded".

Error Handling

3DS Failures

Scenario	Response Status	What to Do
Card requires 3DS	`requires_action`	Redirect customer to `redirectUrl`
Customer cancels 3DS	`failed`	Show error, allow retry
3DS authentication fails	`failed`	Show error, suggest different card
3DS timeout	`failed`	Show error, allow retry
Card does not support 3DS	`succeeded`	Payment completes without 3DS (frictionless)

Common Mistakes

Missing returnUrl: Without a return URL, the customer has nowhere to go after 3DS. Always include it for S2S charges.
Not checking requires_action: If you ignore this status, the payment stays pending forever.
Confirming without 3DS completion: Calling confirm-3ds before the customer completes the challenge will fail.
Hardcoding transactionId: Always use the transactionId from the charge response — it is unique per transaction.

Testing 3DS

Test Cards

Card Number	Behavior
`4000002500003155`	3DS required, authentication succeeds
`4000008260003178`	3DS required, authentication fails
`4242424242424242`	No 3DS required (frictionless)
`4000000000003220`	3DS2 required (newer protocol)

Testing Flow

Use a sandbox/test API key
Charge with a 3DS test card
Follow the redirectUrl — in test mode the challenge auto-completes
Confirm the payment
Verify the payment.completed webhook fires

Liability Shift

When 3DS authentication succeeds:

Fraud liability shifts from the merchant to the card issuer
If a fraudulent chargeback occurs, the merchant is protected
Dispute fees may be waived for 3DS-authenticated transactions

This is a significant benefit: 3DS-authenticated payments have a much lower dispute rate. Where possible, we recommend enabling 3DS for all transactions.

Payments

Treasury

Webhooks

SDKs

3D Secure (3DS)

How 3DS Works

Integration Flow

Server-to-Server (S2S) 3DS Flow

Checkout Session 3DS Flow

Implementation Guide

Step 1: Initiate the Charge

Step 2: Check for 3DS Requirement

Step 3: Redirect the Customer

Step 4: Handle the Return

Step 5: Handle the Result

When is 3DS Required?

Error Handling

3DS Failures

Common Mistakes

Testing 3DS

Test Cards

Testing Flow

Liability Shift

​How 3DS Works

​Integration Flow

​Server-to-Server (S2S) 3DS Flow

​Checkout Session 3DS Flow

​Implementation Guide

​Step 1: Initiate the Charge

​Step 2: Check for 3DS Requirement

​Step 3: Redirect the Customer

​Step 4: Handle the Return

​Step 5: Handle the Result

​When is 3DS Required?

​Error Handling

​3DS Failures

​Common Mistakes

​Testing 3DS

​Test Cards

​Testing Flow

​Liability Shift

How 3DS Works

Integration Flow

Server-to-Server (S2S) 3DS Flow

Checkout Session 3DS Flow

Implementation Guide

Step 1: Initiate the Charge

Step 2: Check for 3DS Requirement

Step 3: Redirect the Customer

Step 4: Handle the Return

Step 5: Handle the Result

When is 3DS Required?

Error Handling

3DS Failures

Common Mistakes

Testing 3DS

Test Cards

Testing Flow

Liability Shift