Direct API 3DS Instructions

This article describes how to handle 3DS processing only if using Direct API instead of CheckoutChamp funnels.

These instructions can be ignored if your site is hosted by Checkout Champ.

3DS handling is built into the platform.

You can test the 3DS process flow by using test cards. See Test Cards

---

About 3DS

The 3D-Secure process involves sending the consumer to a URL or executing a script for the consumer’s bank.

The consumer must enter additional security information to authenticate identity.

3DS is a more complicated transaction flow than the standard Import Order and Upsell API calls.

The benefit is a secure checkout and a liability shift for chargebacks due to fraud.

---

3DS Processing Flow Overview

To begin the 3DS process flow, first send the standard Import Order or Import Upsale request but with the redirectsTo and errorRedirectsTo parameters included.

Not all cards are 3DS enabled and will simply process through the normal way.

If the issuing bank requires a 3DS authentication, then the API response will indicate that with a MERC_REDIRECT response.

Your page then must take additional action to process the sale in the form of redirecting to a specified URL or executing specified JavaScript.

---

Required API Parameters

3DS requires that redirectsTo and errorRedirectsTo be included on Import Order and Import Upsell requests.

redirectsTo

The URL where the browser should redirect on a successful transaction. This is usually an upsell or thank you page URL.

errorRedirectsTo

The URL where the browser should redirect on a failed transaction. This is usually your checkout page URL.

---

API 3DS Response Types

CheckoutChamp has two different 3DS response types:

1. 3DS redirect URL response:

This response indicates that the user's browser should be redirected to a specific URL

{
    "result": "MERC_REDIRECT",
    "message": {
        "url": "https://redirecttheuserhere.com"
    }
}

2. 3DS JavaScript response:

This response indicates that the user's browser should execute the supplied JavaScript. The JS eval function can be used for this

{
    "result": "MERC_REDIRECT",
    "message": {
        "script": "var iframe=document.createElement(\\'IFRAME\\');iframe.innerHTML=..."
    }
}

Example script to handle both responses

if (result === "MERC_REDIRECT") {
    if (message && message.url) {
        window.location.href = message.url;
    } else if (message && message.script) {
        eval(message.script);
    }
}

---

3DS Results

On completion of the 3DS process, one of 2 events will occur:

1. 3DS FAILURE

On failure, the consumer will be redirected back to the URL provided in the errorRedirectsTo parameter. Additionally, the errorMsg parameter will be sent as part of the URL query string Ex. GET https://mysalesPage.com/lander/index.php?errorMsg=Description+of+bank+error

2.3DS SUCCESS

On success, the browser will initiate a POST request to the URL provided in the redirectsTo parameter. The request will contain two POST parameters: finalizeTransaction=1&orderData={}

which contains the same json-encoded response order information as a successful non-3DS Import Order request.