API protocol

Protocol and message format

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

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)

• Outbound (Tokenization Service → issuer backend)

API overview

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	This request is used by the issuer backend to update card information, such as: - Funding card PAN and expiry date (for card renewal) - Card profile
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

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.