Key concepts

Development

To send and receive requests, your issuer backend must implement the inbound and outbound Issuer Gateway API.

Your issuer backend must support PKCS#7 application-level encryption. Use it to protect sensitive data, such as the PAN and expiry date. Details are explained in Data encryption and security.

Use these keys from your Sandbox Environment configuration:

• Thales public key. Encrypt sensitive data sent to Thales.

• Sandbox private key. Decrypt sensitive data received from Thales.

In Production Environment, the issuer generates and stores the private key. Provide the issuer certificate to Thales in the production configuration portal.

Glossary and data model

The diagram and table below describe the main identifiers exchanged through the Issuer Gateway API.

Issuer Gateway API parameter	Description
issuerCardRefId	Identify the FPAN in the issuer backend. Use this identifier in future Issuer Gateway API calls for card-level use cases. Update this identifier if the PAN is replaced (for example, card replacement or renewal).
virtualCardId	Unique identifier of the token.
walletCardRefId	Identify the card as referenced by the wallet provider. Use this identifier in future API calls between the wallet provider and Thales. For co-badging, the payment network can generate this identifier. Map this value to walletCardRefId in the Issuer Gateway API and send it to the issuer backend. Map this value to cardRefId in the TSP API and send it to the TSP.
walletVirtualCardId	Identify the token PAN (DPAN). Use this identifier in future API calls between the wallet provider and Thales. For co-badging, the payment network generates this identifier for the primary token. Thales generates it for the auxiliary token.
tokenStorageId	Identify the token storage location on the device: Secure element ID for secure element-based devices. Application instance ID for HCE-based applications. Share this value with the issuer backend through the Issuer Gateway API in tokenStorageId.

Card digitization

Card digitization converts a physical card into a token. The token represents a digital card. This is also called card enrollment.

This process involves four main actors:

• The end user who wants to digitize a card.

• The wallet provider connected to the payment network.

• The TSP (token service provider) that issues the token.

• The issuer that owns the card account.

Thales TIG also participates in the flow. TIG acts as a gateway between payment networks and the issuer backend. It exposes the Issuer Gateway API and abstracts payment network APIs.

Each card enrollment requires an issuer decision. The issuer can:

• Accept the request without additional authentication.

• Accept the request with step-up authentication using ID&V (identification and verification).

• Reject the request.

The picture below shows a basic card digitization flow.

Each flow has a “color”. It represents the wallet provider recommendation and the issuer decision.

For end-to-end flows, see Use cases.

Flow colors

Depending on the wallet provider and payment network, the wallet provider can send a recommendation to:

• digitize (GREEN)

• digitize with step-up authentication (YELLOW)

• digitize with suspected fraud (ORANGE)

Based on this recommendation and the risk scoring, the issuer responds with a decision to:

• digitize (GREEN)

• digitize with step-up authentication (YELLOW)

• stop enrollment (RED)

The Issuer Gateway API manages the colors using the levelOfTrust parameter. This parameter is present in the card digitization API request (wallet provider) and response (issuer). The sections below describe the common cases.

Recommendation from the wallet provider

GREEN

• Recommend trusting the end user (for example, Card-on-file (COF) or device pairing). The issuer can usually trust the request.

YELLOW

• Recommend using an ID&V flow to authenticate the end user. The issuer should require ID&V.

ORANGE

• Indicate suspected fraud or a device integrity issue (for example, a rooted device). The issuer can reject the request or require ID&V (for example, via customer service).

Decision from the issuer

The issuer receives the wallet provider recommendation and scoring information. The issuer then returns its own levelOfTrust. The following cases are typical:

GREEN

• Trust the request and do not require additional verification. No ID&V flow is triggered.

YELLOW

• Require additional verification. Use when the request lacks trust signals. Example: missing CVV or YELLOW recommendation. The issuer returns supported ID&V methods.

RED

• Reject the request. Use when signals indicate high risk. Example: invalid CVV, repeated CVV failures, or ORANGE recommendation.