> 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/classic-tokenization/get-started/api-basics/api-protocol.md).

# API protocol

### Protocol and message format <a href="#protocol-and-message-format" id="protocol-and-message-format"></a>

The Issuer Gateway API is an RPC-style API. Each method maps to an HTTP endpoint. Requests and responses use JSON payloads.

A `200 OK` HTTP status means the request succeeded.

### Swagger files <a href="#swagger-files" id="swagger-files"></a>

The Tokenization Service API (Issuer Gateway API) is available as a Swagger (OpenAPI) definition. Use it to generate client code and validate requests.

Download the OpenAPI definitions:

* [Inbound (issuer backend → Tokenization Service)](/classic-tokenization/api-reference/issuer-gateway-api/inbound-from-issuer.md)
* [Outbound (Tokenization Service → issuer backend)](/classic-tokenization/api-reference/issuer-gateway-api/outbound-to-issuer.md)

### API overview <a href="#api-overview" id="api-overview"></a>

The API has inbound and outbound endpoints:

* **Outbound**: Tokenization Service calls the **issuer backend**.
* **Inbound**: the **issuer backend** calls Tokenization Service.

**Outbound**

| THALES TO ISSUER REQUEST  | DESCRIPTION                                                                                                                                                                                                 |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NotifyVirtualCardChange   | This request is used by Tokenization Service to notify the issuer backend about any change in a token state.                                                                                                |
| RequestCardDigitalization | This request is used by Tokenization Service to request the issuer backend’s consent to digitize the funding card.                                                                                          |
| CheckCardEligibility      | This request is used by Tokenization Service to check whether a funding card is eligible for Tokenization.                                                                                                  |
| SendOTP                   | This request is used by Tokenization Service to send the OTP generated by the payment network for step-up authentication. The issuer backend must send the OTP to the end user through the selected method. |

**Inbound**

| ISSUER TO THALES REQUEST | DESCRIPTION                                                                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UpdateCard               | <p>This request is used by the issuer backend to update card information, such as:<br>- Funding card PAN and expiry date (for card renewal)<br>- Card profile</p> |
| UpdateCardState          | This request is used by the issuer backend to request an update to a card or token state.                                                                         |
| GetCardInfo              | This request is used by the issuer backend to retrieve token information issued for a given funding card.                                                         |
| SendMessage              | Apple Pay only. This request is used by the issuer backend to send a text message to the end user in the wallet application.                                      |

### Development considerations <a href="#development-consideration" id="development-consideration"></a>

The Issuer Gateway API is stateful for most operations. Your issuer backend must manage session state to handle Tokenization Service requests correctly.

*Enrollment*

* Use several API calls.
* Store the required information returned at each step.
* Use the `x-correlation-id` header to correlate all requests from the same session.

*LCM (life cycle management)*

* Rely on Tokenization Service to manage completion and non-completion scenarios.
* Use the `x-correlation-id` header to correlate all requests from the same session.

<br>


---

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

```
GET https://docs.payments.thalescloud.io/classic-tokenization/get-started/api-basics/api-protocol.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.