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.

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).

{
  // 📊 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:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>3D Secure Authentication</title>
    <style>
        /* 🎨 Basic styling for better UX */
        body {
            font-family: Arial, sans-serif;
            text-align: center;
            padding: 50px;
        }
        .loader {
            border: 4px solid #f3f3f3;
            border-top: 4px solid #3498db;
            border-radius: 50%;
            width: 40px;
            height: 40px;
            animation: spin 2s linear infinite;
            margin: 20px auto;
        }
        @keyframes spin {
            0% { transform: rotate(0deg); }
            100% { transform: rotate(360deg); }
        }
    </style>
</head>
<body onload="document.forms['3dsRedirectForm'].submit()">
    <!-- 🔄 Loading indicator for user feedback -->
    <h2>🔐 Redirecting to 3D Secure Authentication...</h2>
    <div class="loader"></div>
    <p>Please wait while we redirect you to your bank for verification.</p>
    
    <!-- 📝 3D Secure redirect form -->
    <form
      id="3dsRedirectForm"
      name="3dsRedirectForm"
      action="https://secure.xmoney.com/acs20..."
      method="POST"
    >
      <!-- 🔐 Hidden form parameters from API response -->
      <input type="hidden" name="PaReq" value="BASE64_STRING_HERE" />
      <input type="hidden" name="MD" value="SOME_TRANSACTION_ID_HERE" />
      <input type="hidden" name="TermsUrl" value="https://example.com/3ds/return" />
      
      <!-- 🚫 Fallback for users with JavaScript disabled -->
      <noscript>
        <button type="submit" style="padding: 10px 20px; font-size: 16px;">
          🔐 Continue to 3D Secure Authentication
        </button>
      </noscript>
    </form>
</body>
</html>

💡 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
📡 Setup Webhooks	Configure server-to-server notifications	Webhook Guide
📖 Learn More	Understand frictionless vs. challenge flows	3D Secure Overview
✅ Test	Validate your implementation in sandbox	Testing Guide

🎯 Key Benefits: Enhanced security, PSD2 compliance, reduced fraud, and improved customer trust through proper 3D Secure implementation.