Documentation Index
Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt
Use this file to discover all available pages before exploring further.
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?..."
}
}
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.