Apple Pay, Google Pay, etc.

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 Treezor's 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).

Information – €3,000 limitation

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

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, initated 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 most simple 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 (in a similar way 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 prefered method of authentication and the card image displayed in the wallet are specified when you setup 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's PAN)
• The end user receives an SMS or an Email to authenticate and allow the tokenization.
• Treezor sends you a cardDigitalizations.complete webhook

In-App provisioning

In-App provisioning (or app to app at Samsungs, push provisioning at Googles) 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 Treezor's 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 id (cardId) and the Token requestor (tokenRequestor) as parameters.

Example

Outputs an issuerInitiatedDigitizationDatas object, along with its id.

Cryptogram request

This request is sent from the End User's device.

Updating the status of DPAN

You can manage a DPAN using the PUT /cardDigitalizations endpoint.

Mandatory 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

Returns the Card Digitalizations object, along with its id.

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 handbag, bagcharm, 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 callcenter 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	Description	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
/issuerInitiatedDigitizationDatas	Request the issuerInitiatedDigitizationDatas	read_write
/issuerInitiatedDigitizationDatas	Search for issuerInitiatedDigitizationDatas requests	read_only

Reading – More information in the Support Center

Didn't find what you where looking for? You can consult our Support Center's articles regarding X-Pay (opens new window).