X-Pay

The digitization of a Card is the act of tokenizing an existing Card and storing it in a Google Pay or Apple Pay wallet, also referred to as X-Pay.

Note – X-Pay wallets are different from Treezor Wallets

In the context of X-Pay, the term “wallet” refers to digital wallet holding cards (DPANs), such as Apple Pay (iOS), or Google Pay (android) mobile applications.

Introduction to digitization

Treezor allows you to digitize the cards so that your end users can add them to their Apple Pay or Google Pay wallets, hence facilitating payments with their devices.

When digitized, the card’s sensitive information is substituted by a tokenized version of the Card (DPAN). As a result, the wallet providers can offer the cards as a means of payment without holding the card’s PAN.

Similarly to your issued cards, the X-Pay feature relies on your Card Program both in terms of design and functionality.

A digitized Card can be temporarily or permanently disabled using the Treezor API.

Integrating your X-Pay solution

The Treezor API only handles card digitization. Your Apple Pay and Google Pay integration and certification are independent of Treezor services.

Here are the main steps to integrate X-Pay:

1. Project configuration

Contact your Treezor Implementation Manager to activate the X-Pay feature. They will help you meet the prerequisites and provide the relevant information to the card schemes.

2. Implementation of card digitization with Treezor

Implement the card digitization process that fits your project; the endpoints you use differ depending on whether you have already enrolled to PCI DSS services.

There are 2 ways of digitizing Cards. Wallet providers usually require the implementation of both:

• In-House – The end user enters card data into their wallet provider application.
• In-App – The end user clicks on the “Add to wallet” button in your application.

3. Wallet provider certifications

You must get certified by the Wallet providers for your X-Pay integration to be up and running.

Google requires you to screen-record the process to ensure it follows their guidelines. Apple subcontracts the certification to a specialized company that enforces stricter controls.

Please note that Treezor:

• Isn’t involved with Google Pay for your certification.
• Does exchange with the certifying organization for your Apple Pay certification.

This article only focuses on card digitization with the Treezor API. For Card digitization to work, the Online option of the issued card must be activated.

Alert – Wallet providers' privacy policies & requirements

Integration guides are not provided due to wallet provider policies. You must sign a non-disclosure agreement for your Apple Pay integration and be onboarded with Google Pay. These steps provide you with access to their documentation.

In-house provisioning

With the in-house provisioning method, the end user initiates the card digitization from the wallet application of their device.

To tokenize the card and generate the DPAN, the end user enters the card details in the app. Therefore, there is no development on your part.

In addition, in-house provisioning supports wearable devices (e.g., smartwatches) as well as Samsung Pay as a wallet provider.

In-house process

The in-house provisioning process goes as follows.

Step	Description
1	The cardholder enters the card details on their device application (Apple Pay, Google Pay, Samsung Pay).
2	Treezor handles the authorization messages before the tokenization: Account Status Inquiry (ASI) – Ensures the card exists. Tokenization Authorization Request (TAR) – Ensures the card is compatible with X-Pay. Treezor sends a cardDigitalizalitation.request notifying you that the digitization process started.
3	The card details are tokenized by the token provider (Mastercard or Visa).
4	The token provider sends back the token (DPAN) to the wallet application.
5	Treezor ensures the authentication by sending a one-time password (OTP) to the cardholder via email or SMS, and sends you the following webhooks: cardDigitalization.activation – The OTP was sent to the cardholder, starting the authentication process. Corresponds to the Activation Code Notification (ACN). cardDigitalization.complete – The card was successfully digitized and added to the wallet provider application. Corresponds to the Tokenization Complete Notification (TCN).

If the digitized card status is updated (suspension or deactivation), the wallet provider sends a Tokenization Event Notification (TVN), and Treezor notifies you with the cardDigitalization.update webhook.

For more information about token updates, please refer to the Token lifecycle section.

In-app provisioning

The in-app provisioning is initiated from your application. In such cases, your end users click on the “Add to Wallet” button in your interface.

Button examples

Please note the buttons must strictly follow the best practices of the wallet providers.

Once the user requests the card to be added to their Apple or Google Wallet, the following steps occur to complete the digitization.

Please remember that your Wallet Provider integration must be certified by Apple Pay and Google Pay, and that Treezor isn’t involved in those steps.

Flow

The flow can be simplified into 3 main steps:

1. Requesting credentials – Request your credentials from Treezor
2. Requesting cryptogram – Use the credentials to request your cryptogram from Treezor
3. Digitization request – Use the cryptogram to request tokenization from the Wallet Provider

Here is a more detailed sequence diagram.

Authorization messages & webhooks

Treezor handles the following authorization messages during the tokenization process.

Message	Description	Webhook
Account Status Inquiry (ASI)	Ensures the card exists.	N/A
Tokenization Authorization Request (TAR)	Ensures the card is compatible with X-Pay.	cardDigitalization.request
Tokenization Complete Notification (TCN)	Confirms the digitization of the card.	cardDigitalization.complete

Requesting credentials

The credentials request requires at least the cardId and tokenRequestor parameters. Additional information may be necessary for Apple Pay.

CURL

curl -X POST {baseUrl}/v1/issuerInitiatedDigitizationDatas \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

PCI DSS endpoints

If you have migrated to the PCI DSS services, then you must use the following endpoints instead:

• /cards/{cardId}/inappcryptogram/mastercard/apple-pay
• /cards/{cardId}/inappcryptogram/mastercard/google-pay
• /cards/{cardId}/inappcryptogram/visa/apple-pay
• /cards/{cardId}/inappcryptogram/visa/google-pay

Here is a {payload} example:

JSON

{
	"cardId": 0,
	"tokenRequestor": "APPLE",
	"additionnalData": 			// required for Apple Pay only
	{
		"certificates": [
		"string"
		],
		"nonce": "string",
		"nonceSignature": "string"
	}
}

Returns the issuerInitiatedDigitizationDatas object, along with the credential necessary for the next step.

JSON

{
	"issuerInitiatedDigitizationDatas": [
		{
		"id": 0,
		"cardId": 0,
		"statusId": 0,
		"credential": "string",
		"additionnalData": [
			"string"
		],
		"tokenRequestor": "string",
		"createdDate": "string",
		"modifiedDate": "string"
		}
	]
}

Requesting cryptogram

To retrieve your cryptogram (TAV), the following request is sent from the end user's device. Contact your Treezor Implementation Manager for the {specificURL}.

CURL

curl -X GET {specificURL}/issuerInitiatedDigitizationData \
	-d '"credential"="{credential}"'

Returns the base64-encoded TAV.

Digitization request

The digitization request is made with the obtained TAV, from the end user's device. This request isn't made with Treezor API but the Wallet Provider.

Depending on the Wallet Provider, you may need to either send the TAV as received (base64 encoded) or decoded in the form of a JSON object. Please refer to the documentation shared with you by your Treezor Implementation Manager for more information.

Merchant-initiated tokenization

It is not uncommon for merchants to tokenize their customers’ card on their websites, hence saving the card information securely for future payments.

The merchant-initiated request to tokenize the PAN of their consumers results in a token that can only be used by the merchant who initiated the request.

Information – Mandatory feature for all X-Pay subscribers

While Merchant-initiated tokenization isn’t directly related to X-Pay, it is a mandatory functionality set by the Token Providers.

Merchants usually initiate a tokenization request:

• While the transaction is made
• When a new card is added to the customer’s profile
• Per customer request, for any card attached to their profile

When such a tokenization scenario occurs, Treezor informs you with the cardDigitalization.complete webhook, which also contains information about the Merchant who digitized the card.

The token created can be used for the transaction and any transaction that might occur in the future, as long as the same PAN is used.

Flow

Authorization messages & webhooks

Treezor handles the following authorization messages from the merchant during the tokenization process.

Merchant message	Description	Webhook
Account Status Inquiry (ASI)	Ensures the card exists.	N/A
Tokenization Authorization Request (TAR)	Ensures the card is compatible with X-Pay.	cardDigitalization.request
Tokenization Complete Notification (TCN)	Confirms the digitization of the card.	cardDigitalization.complete

Token lifecycle

Once the digitization complete and the token active, the DPAN can be suspended if need be, and deactivated once no longer in use.

Please note that the digitized card statuses are independent of the card's. When blocking a card, it is your responsibility to suspend or deactivate the card token as well.

However, if you're using the most recent services for card digitization, when the card status is set to DESTROYED, Treezor automatically sets the corresponding card tokens to deactivated (X).

Updating the Card Token

You can suspend and unsuspend the digitized card token with the dedicated endpoint.

Parameters

Attribute	string	Description
status	string	Can take the following values: unsuspend – Removes the suspension suspend– Suspends the payment token
reasonCode	string	Can take the following values with suspend: L – Cardholder confirmed token device lost S – Cardholder confirmed token device stolen T – Issuer or cardholder confirmed fraudulent token transactions Z – Other Can take the following values with unsuspend: F – Cardholder reported token device found or not stolen T – Issuer or cardholder confirmed no fraudulent token transactions Z – Other

Request example

CURL

curl -X PUT {baseUrl}/v1/digitalizedCard/{id} \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

JSON

{
  "status": "suspend",
  "reasonCode": "L"
}

Returns the digitized card object, with the status set to S.

JSON

{
  "cardId": "12345",
  "createdDate": "2025-01-19 14:30:45",
  "id": "1234567",
  "modifiedDate": "2025-02-19 14:30:45",
  "status": "S"
}

Treezor also sends the cardDigitalization.update webhook.

Deactivating the Card Token

The token must be deactivated if the cardholder is CANCELED and/or the card is in a permanent locked status.

To do so, use the following request, with the reasonCode as a query parameter (for the Mastercard scheme only).

CURL

curl -X DELETE {baseUrl}/v1/digitalizedCard/{id}?reasonCode={C} \
	--header 'Authorization: Bearer {accessToken}'

Returns the digitized card object, with the status set to X.

JSON

{
  "cardId": "12345",
  "createdDate": "2025-01-19 14:30:45",
  "id": "1234567",
  "modifiedDate": "2025-02-19 14:30:45",
  "status": "X"
}

Treezor also sends the cardDigitalization.deactivated webhook.

Digitized card object

JSON

{
  "activationMethod": "TEXT_TO_CARDHOLDER_NUMBER",
  "cardDigitalizationExternalId": "12345",
  "cardId": "12345",
  "createdDate": "2025-02-19 14:30:45",
  "deviceId": "987654",
  "deviceName": "Chris' iPhone",
  "deviceType": "M",
  "expirationDate": "2025-02-19 14:30:45",
  "id": "1234567",
  "merchantName": "…",
  "modifiedDate": "2025-02-19 14:30:45",
  "status": "A",
  "tokenRequestor": "APPLE",
  "tokenUniqueReference": "…"
}

Statuses (status)

Value	Status	Description
A	Active	Initial status of your DPAN upon card digitization.
S	Suspended	DPAN suspended (card stolen, lost, or declared fraudulent).
X	Deactivated	DPAN deactivated (e.g., card expired).
I	Inactive	This is for Visa Scheme only.

Information – You can't suspend/unsuspend tokens with a U legacy status

Such attempts generate an HTTP 400 error. Please note that you can deactivate such tokens with the /v1/digitalizedCard/{id} request.

Reason codes (reasonCode)

Reason code	Description
C	Account closed
D	Issuer consumer deleted
F	Cardholder reported token device found or not stolen
L	Cardholder confirmed token device lost
S	Cardholder confirmed token device stolen
T	Issuer or cardholder confirmed fraudulent token transactions
Z	Other

Device types (deviceType)

Value	Description
A	Clothing or apparel
B	Media or Gaming device, e.g., Xbox, TV, set-top box
C	Card
D	Domestic application, e.g., fridge, washing machine
F	Fob or key-fob
G	Mobile tag, case, or sleeve
H	Fashion accessory, e.g., purse, glasses
J	Jewelry, e.g., necklace, rings, bracelets
M	Mobile phone
P	Personal computer or laptop
R	Wristband (no further detail.). Possibly includes rings too
S	Sticker
T	Tablet
U	Unknown
V	Vehicle
W	Watch
X	Mobile phone or tablet (sender unclear)

Activation methods (activationMethod)

Value	Description
TEXT_TO_CARDHOLDER_NUMBER	Text message to the cardholder’s mobile phone number.
EMAIL_TO_CARDHOLDER_ADDRESS	Email to cardholder’s email address.
CARDHOLDER_TO_CALL_AUTOMATED_NUMBER	Cardholder-initiated call to automated call center phone number.
CARDHOLDER_TO_CALL_MANNED_NUMBER	Cardholder-initiated call to manned call center phone number.
CARDHOLDER_TO_VISIT_WEBSITE	Cardholder to visit a website.
CARDHOLDER_TO_USE_MOBILE_APP	Cardholder to use a specific mobile app to activate token.
ISSUER_TO_CALL_CARDHOLDER_NUMBER	Issuer-initiated voice call to cardholder’s phone.

Endpoints

Information – Connection to services in Production only

There is no connection to Google Pay or Apple Pay services in Sandbox. Endpoints are available for technical testing only.

Endpoint	Scope
/issuerInitiatedDigitizationDatas Request the issuerInitiatedDigitizationDatas	read_write
/v1/{cardId}/digitalizedCards List digitalized cards for a given cardId	N/A
/v1/digitalizedCard/{id} Retrieve a payment token	N/A
/v1/digitalizedCard/{id} Update a payment token status	N/A
/v1/digitalizedCard/{id} Deactivate a payment token	N/A

Deprecated

Endpoint	Scope
/cardDigitalizations Search for Card Digitalizations	read_only
/cardDigitalizations/{cardDigitalizationId} Retrieve a Card Digitalization	read_only
/cardDigitalizations/{cardDigitalizationId} Update the status of a payment Token	read_write
/cardDigitalizations/{cardDigitalizationId} Delete a payment Token	read_write