> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payments.thalescloud.io/classic-tokenization/get-started/api-basics/api-protocol.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.