Skip to main content
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:
FieldTypeDescription
typestring3ds_redirect, 3ds_challenge, or fingerprint
redirectUrlstringURL 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:
  1. Card issuer rules: Some issuers require 3DS for all online transactions
  2. SCA regulation (PSD2): Required for European card payments over certain thresholds
  3. Risk scoring: Axra’s risk engine may trigger 3DS for suspicious transactions
  4. 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

ScenarioResponse StatusWhat to Do
Card requires 3DSrequires_actionRedirect customer to redirectUrl
Customer cancels 3DSfailedShow error, allow retry
3DS authentication failsfailedShow error, suggest different card
3DS timeoutfailedShow error, allow retry
Card does not support 3DSsucceededPayment completes without 3DS (frictionless)

​
Common Mistakes

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

​
Testing 3DS

​
Test Cards

Card NumberBehavior
40000025000031553DS required, authentication succeeds
40000082600031783DS required, authentication fails
4242424242424242No 3DS required (frictionless)
40000000000032203DS2 required (newer protocol)

​
Testing Flow

  1. Use a sandbox/test API key
  2. Charge with a 3DS test card
  3. Follow the redirectUrl — in test mode the challenge auto-completes
  4. Confirm the payment
  5. 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.