> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/tokenization/implement-tokenization/card-tokenization-request/processing-the-decision/decision-engine.md).

# Decision engine

## Decision engine

D1’s decision engine evaluates available signals and returns a Tokenization decision to the payment network **TSP** (for example, **MDES** or **VTS**) on behalf of the **Issuer**.

The decision is one of:

* **GREEN**: approve
* **YELLOW**: approve with **step-up authentication**
* **RED**: decline

For the end-to-end flow, see [Processing the decision](/tokenization/implement-tokenization/card-tokenization-request/processing-the-decision.md).

{% hint style="info" %}
**Terminology in the D1 API**

* The **End User** is called a **consumer** in the D1 API (for example, `consumerId`).
* A **token requestor** can be an **xPay Wallets** provider (such as Apple Pay, Google Pay, or Samsung Pay) or an e-commerce merchant.
  {% endhint %}

### Data used for decisioning

The D1 decision engine combines the following data:

* **Card** data.
* **End User (consumer)** data provided by the Issuer (check [Get Started](/tokenization/get-started.md) section for details).
* **Token requestor** signals forwarded by the payment network TSP (for example, wallet/device signals for xPay Wallets).

<figure><img src="/files/tQaMnJClWlx2ayG2VPpv" alt=""><figcaption><p>High-level view of decision inputs across the Issuer backend, D1, the payment network TSP, and the token requestor</p></figcaption></figure>

### Rule categories

D1 evaluates signals in five categories:

* Card
* End User data
* Counters
* Card capture
* Wallet scoring

The Issuer configures decisioning preferences for some rules during **D1 onboarding**.

{% stepper %}
{% step %}

### Card

D1 performs a set of mandatory checks to ensure the card can be tokenized.

If any of the checks below fail, D1 returns **RED (decline)**:

| Check           | Result | Description                                                                                         |
| --------------- | ------ | --------------------------------------------------------------------------------------------------- |
| Card not found  | RED    | D1 cannot retrieve the card using the provided card details (for example, **PAN** and expiry date). |
| Card terminated | RED    | The card exists, but it has been deleted or replaced.                                               |
| Invalid **CSC** | RED    | The card exists, but the provided **CSC** does not match **CVV2** or **dCVV2**.                     |
| Card suspended  | RED    | The card exists, but it is suspended (for example, reported lost or stolen).                        |
| Card expired    | RED    | The card exists, but it is expired.                                                                 |

{% hint style="warning" %}
**Validating CSC (CVV2/dCVV2)**

* If you provide the card product **CVK** during **D1 onboarding**, D1 can validate **CVV2**/**dCVV2**.
* If the CVK was already generated and is already used by the Issuer, provide the CVK protected under a **ZMK**, based on your Issuer key-ceremony process.
* If you do not provide the CVK, D1 can call your **Issuer backend** using the [Verify card API](/tokenization/integrate-the-d1-api/d1-api-summary.md) (depending on your configured integration model).
  {% endhint %}
  {% endstep %}

{% step %}

### End User (consumer)

If the payment network TSP provides a phone number in the Tokenization request, D1 can compare it to the phone number you provided for the **End User**.

Comparison is performed on the subscriber number (MSISDN format). If the values are not comparable (for example, invalid formatting), the rule does not apply.

| Check                 | Result        | Description                                                                |
| --------------------- | ------------- | -------------------------------------------------------------------------- |
| Phone number mismatch | RED or YELLOW | The End User phone number does not match the token requestor phone number. |

You choose whether the mismatch results in **RED** or **YELLOW** during **D1 onboarding**.

{% hint style="warning" %}
D1 cannot verify End User information. It is the Issuer’s responsibility to provide validated End User data to D1 and keep it up to date.
{% endhint %}
{% endstep %}

{% step %}

### Counters

Counters are **optional** checks used to rate-limit Tokenization requests.

When enabled, the Issuer configures thresholds during **D1 onboarding**.

| Check                                                                    | Result | Description                                                                           |
| ------------------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------- |
| Tokenization count exceeds limit for the same **PAN**                    | RED    | Limits the maximum number of digital cards that can be associated with a single card. |
| Tokenization count exceeds limit for the same device                     | RED    | Limits the maximum number of digital cards that can be stored on a single device.     |
| Too many Tokenization requests on the same device in a given time window | RED    | Limits the Tokenization rate for a device.                                            |
| Too many **CSC** verification attempts                                   | RED    | Limits repeated **CSC** failures.                                                     |
| {% endstep %}                                                            |        |                                                                                       |

{% step %}

### Card capture

The **CSC** is a 3- or 4-digit number associated with a card. Depending on how the card details were captured, the CSC may or may not be available.

For example, with **Card-on-file (COF)**, the CSC is typically not stored and may not be present.

D1 applies the following rules:

| Check                                                      | Result | Description                                             |
| ---------------------------------------------------------- | ------ | ------------------------------------------------------- |
| Capture method indicates in-app, token, or COF             | GREEN  | The CSC is not required.                                |
| Digital card type is e-commerce                            | GREEN  | The CSC is not required.                                |
| Digital card type is not e-commerce and the CSC is missing | YELLOW | Missing CSC increases fraud risk for this capture type. |
| {% endstep %}                                              |        |                                                         |

{% step %}

### Wallet scoring

Some token requestors (typically **xPay Wallets**) provide risk signals through the payment network TSP, such as:

* A recommendation
* A device score

D1 combines these signals into a single score from **1** (highest risk) to **5** (lowest risk). The Issuer maps each score to a D1 decision (GREEN/YELLOW/RED) during **D1 onboarding**.

| Score | Typical mapping | Description                                        |
| ----- | --------------- | -------------------------------------------------- |
| 1     | RED or YELLOW   | Strong risk indication from the token requestor.   |
| 2     | RED or YELLOW   | Elevated risk indication from the token requestor. |
| 3     | YELLOW or GREEN | Insufficient signals to assert low risk.           |
| 4     | YELLOW or GREEN | Low risk indication.                               |
| 5     | YELLOW or GREEN | Strong low-risk indication.                        |

{% hint style="warning" %}
Token requestors do not provide details about how they compute scoring.

They only indicate that **1** is the worst score (highest risk) and **5** is the best score (lowest risk).
{% endhint %}

For merchants, wallet/device signals are typically not available because the digital card is stored in the cloud.

{% hint style="info" %}
D1 does not evaluate device risk by itself. It relies on signals provided by the token requestor (when available) through the payment network TSP.
{% endhint %}
{% endstep %}
{% endstepper %}

### How D1 computes the final decision

The decision returned to the payment network TSP is always one of the three outcomes described in [Processing the decision](/tokenization/implement-tokenization/card-tokenization-request/processing-the-decision.md).

To keep decisioning predictable and aligned with payment network protocols, D1 evaluates categories in this order:

1. Card, End User data, counters, and card capture
2. Wallet scoring (when available)

Wallet scoring is evaluated last because it is optional, depends on the token requestor, and may not be provided for merchants.

The final decision is the **most restrictive** outcome across all checks:

* If any check returns **RED**, the final decision is **RED**.
* Otherwise, if any check returns **YELLOW**, the final decision is **YELLOW**.
* Otherwise, the final decision is **GREEN**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/tokenization/implement-tokenization/card-tokenization-request/processing-the-decision/decision-engine.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.