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

{
  "code": 201,
  "message": "Created",
  "data": {
    "orderId": 0,
    "transactionId": 0,
    "is3d": 1,
    "isRedirect": true,
    "redirect": {
      "url": "https://secure.xmoney.com/acs20...",
      "formMethod": "POST",
      "params": {
        "PaReq": "",
        "MD": "",
        "TermsUrl": ""
      }
    }
  }
}

Interpreting the Redirect Fields

code and message: Status indicating the creation of a new transaction that requires 3D Secure.
orderId, transactionId: Identifiers for the order and transaction in xMoney’s system.
is3d: Indicates the transaction is 3D Secure. (1 means 3D Secure required)
isRedirect: Instructs you to redirect the shopper to complete the 3DS challenge. (true or false)
redirect: Contains all the data needed to direct the shopper’s browser (or webview) to the 3D Secure authentication page (ACS – Access Control Server).
- url: The endpoint where you must send the shopper for authentication.
  - formMethod: Usually "POST".
  - params: Key-value pairs to include in the form submission (e.g., PaReq, MD, TermsUrl).

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

Create a Form (front end) or automatically redirect using a server-side approach:

Action: redirect.url
Method: redirect.formMethod (usually POST)
Hidden fields: Each key from redirect.params (e.g., PaReq, MD, TermsUrl).

Submit the form automatically or prompt the shopper to click a “Continue” button.
Shopper Completes the Challenge:

The shopper verifies their identity (e.g., enters a password, uses a banking app).

Return from 3DS:

The card issuer’s page redirects the shopper back to your return URL (or xMoney’s hosted return page, if applicable).
You can then receive a final status from xMoney (e.g., payment success or failure).

Example Redirect Form

Here’s a simplified HTML snippet showing how you might build the form:

<html>
  <body onload="document.forms['3dsRedirectForm'].submit()">
    <form
      id="3dsRedirectForm"
      name="3dsRedirectForm"
      action="https://secure.xmoney.com/acs20..."
      method="POST"
    >
      <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" />
      <noscript>
        <button type="submit">Continue 3D Secure</button>
      </noscript>
    </form>
  </body>
</html>

Upon page load, the form automatically submits, taking the shopper to the ACS page for 3D Secure verification.

Post-3DS Notification

After the shopper finishes the 3D Secure challenge, xMoney proceeds with authorization:

If successful, the payment moves to a complete-ok (authorized) status.
If failed or canceled, the payment moves to a complete-failed status.

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. Make sure to:

Validate the payload signature or decrypt if it’s opensslResult.
Respond with 200 OK and OK as the body to acknowledge receipt.
Update your order management system accordingly.

Best Practices

Use Secure HTTPS: Always ensure your redirect URLs and form submissions use HTTPS to protect sensitive cardholder data.
Display Clear Messaging: Let the shopper know they’re being redirected for 3D Secure authentication, so they don’t abandon the process.
Handle Failure: If the shopper fails authentication or closes the browser, xMoney will mark the transaction as complete-failed. Provide a retry option if needed.
Monitor Webhooks: The final status of the payment is communicated via IPN or direct response after 3DS. Keep an eye on this to confirm successful or failed transactions.

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:

Implement your redirect form using the provided data.
Listen for webhooks or server-to-server notifications to confirm the final outcome.
Refer to our 3D Secure Overview for more on frictionless vs. challenge flows.