> ## 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 Pass `returnUrl` on the charge. After 3DS the payer returns via Axra's page; we append `3ds=complete|failed` and `paymentId`. The URL is never shared with the card processor. ``` 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 returns via Axra's page, then | | | to returnUrl?3ds=complete|failed&paymentId=… | |<.............................| (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. After 3DS the customer returns via Axra's page; we then send them to your `returnUrl` with `3ds=complete` or `3ds=failed` and `paymentId` appended. Your `returnUrl` is never shared with the card processor. ```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", "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ...", "browserDetails": { "acceptHeaders": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "colorDepth": 24, "javaEnabled": false, "javascriptEnabled": true, "language": "en-US", "screenHeight": 1080, "screenWidth": 1920, "timeZone": -60 } }' ``` **`browser` and `browserDetails` are required in practice.** They are the EMV-3DS2 device signals the issuer uses to decide whether it can authenticate without challenging the cardholder. Omit them and the issuer will usually demand a challenge — and we have observed issuers **failing the authentication instead of presenting one**, so the payment dies with no prompt ever shown. We cannot fill them in for you: on a server-to-server charge the request reaches us from your server, not the cardholder's browser. See [Collecting the browser signals](/payments/card-payments) for a copy-paste snippet. ### 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 return via Axra's page and are then sent to your `returnUrl` with `3ds=complete|failed` and `paymentId`. 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.