Skip to content

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.

Wallets on Apple, Samsung and Android phones

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).

Info icon

Information – €3,000 limitation

A limitation of €3000 per X-Pay payment is enforced.

Lexicon
TermDefinition
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 providerThe actor who requests the DPAN generation (PAN tokenization), stores and offers it as a payment method (Apple, Samsung, Google…).
Token providerThe 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.
IssuerInitiatedDigitizationDataCryptogram 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 provisioningMethod of digitization, initiated from the Wallet Provider's mobile app.
In-App provisioningMethod of digitization, initiated from your mobile application.
Note icon

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.

X-Pay Apps
Note icon

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

Thumbs icon

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 icon

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.

Info icon

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
books icon

Reading – Refer to the wallet provider documentation

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

X-Pay In-App provisioning

Credentials request

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

Example

bash
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}.

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

Updating the status of DPAN

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

Parameters

AttributestringDescription
status stringCan take the following values:
  • unsuspend – Removes the suspension
  • suspend– Suspends the payment token
reasonCode stringCan 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

bash
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)

ValueDescription
PHONEA mobile phone
TABLETTablet computer
TABLET_OR_EREADERTablet computer or e-reader
WATCHWatch
WATCH_OR_WRISTBANDWatch or wristband, including a fitness band, smart strap, disposable band, watch add-on, security / ID Band
CARDCard
STICKERSticker
PCPC or Laptop
DEVICE_PERIPHERALDevice peripherals, such as a mobile phone case or sleeve
TAGTag, such as a key fob or mobile tag
JEWELRYJewelry, such as a ring, bracelet, necklace, and cuff links
FASHION_ACCESSORYFashion accessory, such as a purse, bag charm, glasses
GARMENTGarment, such as a dress
DOMESTIC_APPLIANCEDomestic appliance, such as a refrigerator, washing machine
VEHICULEVehicle, including vehicle attached devices
MEDIA_OR_GAMING_DEVICEMedia or gaming device, including a set-top box, media player, television
UNDEFINEDDevice type that is not yet defined

Activation methods (activationMethod)

ValueDescription
TEXT_TO_CARDHOLDER_NUMBERText message to Cardholder’s mobile phone number. Value will be the Cardholder’s masked mobile phone number
EMAIL_TO_CARDHOLDER_ADDRESSEmail to Cardholder’s email address. Value will be the Cardholder’s masked email address
CARDHOLDER_TO_CALL_AUTOMATED_NUMBERCardholder-initiated call to automated call center phone number. Value will be the phone number for the Cardholder to call
CARDHOLDER_TO_CALL_MANNED_NUMBERCardholder-initiated call to manned call center phone number. Value will be the phone number for the Cardholder to call
CARDHOLDER_TO_VISIT_WEBSITECardholder to visit a website. Value will be the website URL
CARDHOLDER_TO_USE_MOBILE_APPCardholder to use a specific mobile app to activate token. Value will be replaced by a formatted string
ISSUER_TO_CALL_CARDHOLDER_NUMBERIssuer-initiated voice call to Cardholder’s phone. Value will be the Cardholder’s masked voice call phone number.

Endpoints

EndpointScope
/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
books icon

Reading – More information in the Support Center

Don't hesitate to consult the X-Pay articles on the Treezor Support Center.