X-Pay

The digitization of a Card is the act of tokenizing an existing Card and store it in a Google Pay, Apple Pay, or Samsung Pay wallet.

When digitized, the card sensitive information are substituted by a tokenized version of the Card (DPAN). Therefore, the wallets providers can offer the cards as a means of payment, while not holding the actual Cards PAN. A digitized Card can be temporarily or permanently disabled using the Treezor API.

There are two ways of digitizing Card: In-House and In-App, both methods must be made available to End Users (as required by the Wallet providers).

Lexicon

Term	Definition
PAN (Primary Account Number)	Card number as embossed or etched on a Physical or Virtual Card.
DPAN (Device Primary Account Number)	The tokenized version of the PAN. It allows to securely identify a Card, but cannot be used to pay on its own.
Wallet provider	The actor who requests the DPAN generation (PAN tokenization), stores and offers it as a payment method (Apple, Samsung, Google…).
Token provider	The actor who tokenizes the PAN to allow its storage as a DPAN by the Wallet provider. The token provider (e.g., Mastercard) also detokenizes the DPAN during payments.
IssuerInitiatedDigitizationData	Cryptogram generated by Treezor for the Token and Wallet providers. It allows the providers to authenticate a request. In is only used with the In-App method.
TAR (Tokenization Authorization Request)	Message sent to our card processor to verify the card configuration.
ACN (Activation Complete Notification)	Authentication message sent to a cardholder (by SMS or email).
TCN (Tokenization Complete Notification)	Informational message sent to a cardholder (by SMS or email).
In-House provisioning	Method of digitization, initiated from the Wallet Provider's mobile app.
In-App provisioning	Method of digitization, initiated from your mobile application.

Note – X-Pay wallets are different from Treezor Wallets

In the context of X-Pay, the term Wallet can be seen as a real-life wallet holding cards (DPANs). The wallets are in Google, Samsung, or Google (android) smartphones and hold representations of the Cards.

In-House provisioning

In-House provisioning is a digitization method initiated by the End User, using the Wallet Provider's mobile app (Google Pay App, Samsung Pay App, etc.).

This method is the simplest as it doesn't require any development on your side. The creation of the DPAN is usually as simple as taking a picture of the Card with an app that's already pre-installed on iOS and Android devices.

It however requires that the cardholder be authenticated by SMS or Email during the initial tokenization (similarly to 3DS). Otherwise, a person with temporary access to a card could add it to their own wallet without the cardholder's consent.

Note – Card Program setup

The preferred method of authentication and the card image displayed in the wallet are specified when you set up a Card Program.

Best practice – Your card should always look the same

Note that the card image should be similar or identical to your Physical or Virtual Cards design.

Procedure

• The end user opens the Google Pay app (Samsung Pay app or Apple Wallet app).
• The end user takes a picture of the Card (or enters the Card PAN).
• The end user receives an SMS or an Email to authenticate and allow the tokenization.
• Treezor sends you a cardDigitalizations.complete webhook.

Note – The User email address must be less than 50 characters

Only emails complying with this limit are used for the X-Pay provisioning OTP method. If you didn't enforce such limits when creating the user, you may want to update their email.

In-App provisioning

In-App provisioning (or app to app for Samsung, push provisioning for Google) is a digitization method initiated from your mobile application and manually managed on your side.

Information – This method requires a certification by the Wallet provider

Each Wallet provider has its own certification program. Google requires that you screen-record the process to ensure that it follows its guidelines while Apple subcontracts the certification to a specialized company that enforces stricter controls.

Procedure

• The End User authenticates against your application
• The End User requests the digitization of a Card using your mobile application
• You request credentials using the dedicated endpoint
• You forward the credentials to the End User's application
• The End User's application requests a cryptogram (TAV) using the Treezor public API
• Treezor returns the cryptogram (TAV) to the End User's application
• The End User's application sends the TAV to the Wallet provider (Google, Apple, Samsung)
• The Wallet provider sends a digitization request to the Token provider (e.g., Mastercard)
• The Token provider tokenizes the PAN and returns a DPAN to the Wallet provider
• The Wallet provider stores the DPAN on the End User's device
• Treezor sends you a cardDigitalizations.complete webhook

Reading – Refer to the wallet provider documentation

For implementation details you can refer to Google, Apple, and Samsung documentations.

Credentials request

The credentials request takes the Card unique identifier (cardId) and the Token requestor (tokenRequestor) as parameters.

Example

CURL

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

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 its id.

JSON

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

Cryptogram request

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}"'

Updating the status of DPAN

You can manage a DPAN using the /v1/digitalizedCard/{id} endpoint.

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

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

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: L (with suspend) – Cardholder confirmed token device lost S (with suspend) – Cardholder confirmed token device stolen T (with suspend) – Issuer or cardholder confirmed fraudulent token transactions F (with unsuspend) – Cardholder reported token device found or not stolen T (with unsuspend) – Issuer or cardholder confirmed no fraudulent token transactions Z – Other

Example

CURL

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

Here is a {payload} example:

JSON

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

Returns the Digitalized Card object, along with its id and the updated status.

JSON

{
  "id": "1234567",
  "cardId": "123456",
  "status": "S",
  "createdDate": "2022-12-07 23:54:03",
  "modifiedDate": "2023-12-07 14:44:05"
}

Status (status)

• A Active
• U Unmapped
• S Suspended
• D (or X) Deleted

Device types (deviceType)

Value	Description
PHONE	A mobile phone
TABLET	Tablet computer
TABLET_OR_EREADER	Tablet computer or e-reader
WATCH	Watch
WATCH_OR_WRISTBAND	Watch or wristband, including a fitness band, smart strap, disposable band, watch add-on, security / ID Band
CARD	Card
STICKER	Sticker
PC	PC or Laptop
DEVICE_PERIPHERAL	Device peripherals, such as a mobile phone case or sleeve
TAG	Tag, such as a key fob or mobile tag
JEWELRY	Jewelry, such as a ring, bracelet, necklace, and cuff links
FASHION_ACCESSORY	Fashion accessory, such as a purse, bag charm, glasses
GARMENT	Garment, such as a dress
DOMESTIC_APPLIANCE	Domestic appliance, such as a refrigerator, washing machine
VEHICULE	Vehicle, including vehicle attached devices
MEDIA_OR_GAMING_DEVICE	Media or gaming device, including a set-top box, media player, television
UNDEFINED	Device type that is not yet defined

Activation methods (activationMethod)

Value	Description
TEXT_TO_CARDHOLDER_NUMBER	Text message to Cardholder’s mobile phone number. Value will be the Cardholder’s masked mobile phone number
EMAIL_TO_CARDHOLDER_ADDRESS	Email to Cardholder’s email address. Value will be the Cardholder’s masked email address
CARDHOLDER_TO_CALL_AUTOMATED_NUMBER	Cardholder-initiated call to automated call center phone number. Value will be the phone number for the Cardholder to call
CARDHOLDER_TO_CALL_MANNED_NUMBER	Cardholder-initiated call to manned call center phone number. Value will be the phone number for the Cardholder to call
CARDHOLDER_TO_VISIT_WEBSITE	Cardholder to visit a website. Value will be the website URL
CARDHOLDER_TO_USE_MOBILE_APP	Cardholder to use a specific mobile app to activate token. Value will be replaced by a formatted string
ISSUER_TO_CALL_CARDHOLDER_NUMBER	Issuer-initiated voice call to Cardholder’s phone. Value will be the Cardholder’s masked voice call phone number.

Endpoints

Endpoint	Scope
/v1/{cardId}/digitalizedCards List digitalized cards for a given cardId
/v1/digitalizedCard/{id} Update a payment token status
/v1/digitalizedCard/{id} Deactivate a payment token
/v1/digitalizedCard/{id} Retrieve a payment token
/issuerInitiatedDigitizationDatas Request the issuerInitiatedDigitizationDatas	read_write
/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