> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Issuer 3DS

> "Three Domain Secure" (3DS) is a protocol designed to be an additional security layer for credit and debit card transactions when there is no physical card present, such as in online purchases.

## Overview

When a merchant initiates the 3DS process the Synctera platform responds according to your configuration. You may specify the desired 3DS behaviour at the card product level or on a per-request basis.

### Card Product

Each product can be configured with a `three_ds_policy`. This field has two possible values: `SMS_OTP` and `EXEMPT`. If no value is specified, the default is `SMS_OTP`.

If you choose `SMS_OTP` then for each 3DS process involving the card product the cardholder will receive an SMS message with a one-time code which they must then supply to the merchant to verify their identity. The SMS will be sent to the customer's phone number that is stored in the platform.

If you choose `EXEMPT` then each 3DS process involving the card product will succeed with no further steps.

You may override the card product's 3DS policy by implementing a decision gateway.

### Decision Gateway

3DS decision gateways allow you to make real-time decision about each 3DS request. 3DS gateways are independent entities in the Synctera platform which can be associated with any number of card products. These associations are defined by the `three_ds_decision_gateways` endpoints, not the card product endpoints.

#### Creation

Create a 3DS decision gateway by calling `POST /v1/cards/three_ds_decision_gateways` with a body like this:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "is_active": true,
    "decision_url": "https://your.server/3ds_decision",
    "card_products": [
      "2957a146-ce3b-4d04-8328-ab3ea6e76cac"
    ],
    "fallback_decision": "EXEMPT",
    "custom_headers": {
      "X-Custom-Data": "arbitrary value"
    }
  }
  ```
</CodeGroup>

Every time the Synctera platform makes a 3DS decision for a card from the card products you specify, it will now attempt to send a `POST` request to your `decision_url`. The request will include all the `custom_headers` key-value pairs you specify as HTTP headers in the request.

Custom headers are optional to use as you see fit. For the purpose of authenticating requests, rather than using custom headers, you can [create a signature secret for request validation](/docs/webhooks-guide#integration-steps) and then check the `Synctera-Signature` HTTP header of each request to your gateway.

The `fallback_decision` will be used if something goes wrong and the Synctera platform can't get a response from your decision endpoint or the request times out. The values for `fallback_decision` are the same as the `three_ds_policy` options for a card product (`SMS_OTP` and `EXEMPT`) and have the same meaning.

If an active decision gateway is configured for a card product, then the API responses for that card product will indicate that the `three_ds_policy` is `DECISION_GATEWAY`. This means that the decision gateway overrides the `three_ds_policy` of the card product and if the Synctera platform can't get a response from the decision gateway it will use the gateway's `fallback_decision` rather than the card product's `three_ds_policy`.

#### 3DS Decision Request

The body of the request to your 3DS decision server will look like this:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "card_id": "f8c84f73-91a5-4dfe-9c12-a35bfa1df716",
    "card_product_id": "2957a146-ce3b-4d04-8328-ab3ea6e76cac",
    "acs_transaction_id": "a0c165f9-23ae-408c-b8c3-a7c486750b1e",
    "authentication_request_type": "PAYMENT",
    "client_ip_address": "10.1.2.3",
    "device_channel": "BROWSER",
    "transaction_amount": 6187,
    "currency_code": "USD",
    "transaction_type": "PAYMENT",
    "transaction_sub_type": "PURCHASE",
    "merchant": {
      "name": "Best Buy",
      "country_code": "840",
      "id": "345954985882",
      "category_code": "5732"
    }
  }
  ```
</CodeGroup>

The `transaction_amount` is in minor units of the currency (in this case, cents). The currency is specified in the `currency_code` field as a 3 character alphabetical code.

`authentication_request_type` is one of `PAYMENT`, `RECURRING`, `INSTALLMENT`, `ADD_CARD`, `MAINTAIN_CARD` or `EMV_CARDHOLDER_VERIFICATION`.

`device_channel` is one of `BROWSER`, `APP_BASED` or `THREEDS_REQUESTER_INITIATED`.

`transaction_type` is either `PAYMENT` or `NON_PAYMENT`.

`transaction_sub_type` is one of `PURCHASE`, `ACCOUNT_VERIFICATION`, `ACCOUNT_FUNDING`, `QUASI_CASH` or `PREPAID_ACTIVATION_AND_LOAD`.

The `merchant.country_code` is specified as the ISO 3166-1 three-digit numeric country code.

#### 3DS Decision Response

To indicate your 3DS decision, your 3DS decision server responds with HTTP status OK (200) and writes a single field the response body. For example:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "decision": "EXEMPT"
  }
  ```
</CodeGroup>

The allowed values for your `decision` are `SMS_OTP` and `EXEMPT`. These values have the same meaning as described above for the `three_ds_policy` of a card product.

If the Synctera platform sees a response status code other than 200 or can't decode the response body then it will use the gateway's `fallback_decision`.