# Direct API 3DS Instructions

{% hint style="warning" %}
These instructions can be ignored if your site is hosted by Checkout Champ.

3DS handling is built into the platform.
{% endhint %}

{% hint style="info" %}
You can test the 3DS process flow by using test cards. See [Test Cards](https://help.checkoutchamp.com/crm/admin-setup/test-cards)
{% endhint %}

***

### 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](https://apidocs.checkoutchamp.com/#275a54c6-b4b0-414c-819b-7387e9a81f58)  or  [Import Upsale](https://apidocs.checkoutchamp.com/#46b9bc0a-687a-4a87-a57c-266f9914681f) request but with the **redirectsTo** and **errorRedirectsTo** parameters included.

{% hint style="info" %}
Not all cards are 3DS enabled and will simply process through the normal way.
{% endhint %}

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

{% hint style="info" %}
3DS requires that **redirectsTo** and **errorRedirectsTo** be included on [Import Order](https://apidocs.checkoutchamp.com/#275a54c6-b4b0-414c-819b-7387e9a81f58) and [Import Upsell](https://apidocs.checkoutchamp.com/#46b9bc0a-687a-4a87-a57c-266f9914681f) requests.
{% endhint %}

#### 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

```json
{
    "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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval)

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

#### **Example script to handle both responses**

```javascript
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.