3D Secure Authentication

# 3D Secure Redirects and Notifications When a shopper uses a card requiring **3D Secure authentication**, xMoney may return a special response instructing you to redirect the shopper for verification. This occurs before the payment can be finalized. Using Embedded Checkout? If you use the inline checkout SDK, most 3DS handling is managed by the SDK modal and background transaction refresh. See [Inline Checkout 3DS and payment results](/guides/checkout/inline-checkout/3ds-results). ## Redirect Response Below is an example of a **3D Secure redirect response** from xMoney. It indicates that the transaction requires a **3D Secure challenge** and provides the necessary information to forward the shopper to their card issuer's verification page (ACS). ```json { // 📊 Response Status "code": 201, "message": "Created", // 🔐 Transaction Data "data": { "orderId": 0, "transactionId": 0, "is3d": 1, "isRedirect": true, // 🔄 Redirect Information "redirect": { "url": "https://secure.xmoney.com/acs20...", "formMethod": "POST", "params": { "PaReq": "", "MD": "", "TermsUrl": "" } } } } ``` ## Interpreting the Redirect Fields ### Response Components | Field | Type | Description | Purpose | | --- | --- | --- | --- | | **`code`** | Status | Response status indicating transaction creation | ✅ Confirms 3DS transaction initiated | | **`message`** | Status | Response status indicating transaction creation | ✅ Confirms 3DS transaction initiated | | **`orderId`** | Integer | Order identifier in xMoney's system | 🆔 Reference for tracking | | **`transactionId`** | Integer | Transaction identifier in xMoney's system | 🆔 Reference for tracking | | **`is3d`** | Integer | 3D Secure requirement indicator (`1` = required) | 🔐 Confirms 3DS needed | | **`isRedirect`** | Boolean | Redirect instruction (`true`/`false`) | 🔄 Action required | ### Redirect Object Details | Field | Description | Required | | --- | --- | --- | | **`url`** | ACS endpoint for authentication | ✅ Yes | | **`formMethod`** | HTTP method (usually "POST") | ✅ Yes | | **`params`** | Form data key-value pairs | ✅ Yes | **⚠️ Important:** This response does not mean the transaction is completed. The shopper must be redirected to the `redirect.url`, submit the form data, and pass the 3D Secure challenge before the payment can finalize. ## How to Handle the Redirect Follow these **4 key steps** to properly handle 3D Secure redirects: ### Step 1: 📝 Create the Redirect Form Create a form with the following components: - **Action:** `redirect.url` - **Method:** `redirect.formMethod` (usually POST) - **Hidden fields:** Each key from `redirect.params` ### Step 2: 🚀 Submit the Form - **Automatic submission** (recommended for UX) - Or **manual submission** with a "Continue" button ### Step 3: 🔐 Shopper Authentication The shopper completes the challenge: - 🔑 Enters authentication credentials - 📱 Uses banking app verification - 🛡️ Completes biometric verification ### Step 4: ↩️ Return Processing - 🔄 Card issuer redirects back to your return URL - 📡 Receive final status from xMoney - ✅ Process **success** or ❌ **failure** result ## Example Redirect Form Here's a comprehensive HTML implementation showing the **automatic redirect flow**: ```html 3D Secure Authentication

🔐 Redirecting to 3D Secure Authentication...

Please wait while we redirect you to your bank for verification.

``` **💡 Pro Tip:** The form automatically submits on page load, providing a seamless user experience. The loading indicator helps users understand what's happening during the redirect process. ## Post-3DS Notification ### Authentication Flow Completion After the shopper finishes the **3D Secure challenge**, xMoney proceeds with authorization: | Outcome | Status | Description | | --- | --- | --- | | ✅ **Successful** | `complete-ok` | Payment authorized and processed | | ❌ **Failed/Canceled** | `complete-failed` | Authentication failed or user canceled | ### Webhook/Server-to-Server Notification In addition to returning the shopper to your success or fail page, xMoney also sends a **webhook (IPN)** to your notification endpoint with the final outcome. #### 🔧 Implementation Checklist | Step | Action | Status | | --- | --- | --- | | **1** | **Validate** the payload signature or **decrypt** if it's opensslResult | ⬜ | | **2** | **Respond** with `200 OK` and `OK` as the body to acknowledge receipt | ⬜ | | **3** | **Update** your order management system accordingly | ⬜ | ## Best Practices ### 🔒 Security Requirements | Practice | Description | Priority | | --- | --- | --- | | **🔐 Use HTTPS** | Always ensure redirect URLs and form submissions use HTTPS | 🔴 Critical | | **🛡️ Validate Webhooks** | Verify payload signatures for security | 🔴 Critical | | **🔑 Secure Data Handling** | Protect sensitive cardholder data during transmission | 🔴 Critical | ### 👤 User Experience - **📢 Clear Messaging:** Let shoppers know they're being redirected for **3D Secure** authentication - **⏱️ Loading Indicators:** Show progress during redirect to prevent abandonment - **📱 Mobile Optimization:** Ensure forms work seamlessly on mobile devices - **🌐 Multi-language Support:** Provide localized messaging when possible ### 🚨 Error Handling - **🔄 Retry Options:** If authentication fails, provide a retry mechanism - **📊 Monitoring:** Track authentication success/failure rates - **🔔 Webhook Reliability:** Implement proper webhook handling and retries **⚠️ Important:** If the shopper fails authentication or closes the browser, xMoney will mark the transaction as **complete-failed**. Always provide clear instructions and support options. ## Conclusion When **3D Secure** is required, xMoney returns a **redirect** object to guide the shopper through the necessary authentication steps. By properly handling the **3D Secure** redirect flow, you can help ensure smoother, more secure transactions for both your business and your customers. ### 🚀 Next Steps | Action | Description | Link | | --- | --- | --- | | 🛠️ **Implement** | Build your redirect form using the provided data | [Code Example](#example-redirect-form) | | 📡 **Setup Webhooks** | Configure server-to-server notifications | [Webhook Guide](#post-3ds-notification) | | 📖 **Learn More** | Understand frictionless vs. challenge flows | [3D Secure Overview](/guides/payments/3d-secure/3d-secure) | | ✅ **Test** | Validate your implementation in sandbox | [Testing Guide](/guides/general/get-started) | **🎯 Key Benefits:** Enhanced security, PSD2 compliance, reduced fraud, and improved customer trust through proper 3D Secure implementation.