# 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](/crm/admin-setup/test-cards.md)
{% 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.checkoutchamp.com/crm/gateway-setup/direct-api-3ds-instructions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.