> ## 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 (3DS) > Add 3DS authentication to card payments for fraud reduction and liability shift 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. ```bash theme={null} 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. ```json theme={null} { "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`: ```javascript theme={null} // 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: ```bash theme={null} 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 ```javascript theme={null} 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 | 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 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 Number | Behavior | | ------------------ | ------------------------------------- | | `4000002500003155` | 3DS required, authentication succeeds | | `4000008260003178` | 3DS required, authentication fails | | `4242424242424242` | No 3DS required (frictionless) | | `4000000000003220` | 3DS2 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.