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

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

Info icon

Information – €3,000 limitation

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

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

X-Pay Apps
Note icon

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

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's PAN)
  • The end user receives an SMS or an Email to authenticate and allow the tokenization.
  • We send 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.

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 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
  • We send 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 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_OR_WRISTBAND Watch or wristband, including a fitness band, smart strap, disposable band, watch add-on,security/ ID Band
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
GET /cardDigitalizations Search for Card Digitalizations read_only
GET /cardDigitalizations/{cardDigitalizationId} Retrieve a Card Digitalization read_only
PUT /cardDigitalizations/{cardDigitalizationId} Update the status of a payment Token read_write
DELETE /cardDigitalizations/{cardDigitalizationId} Delete a payment Token read_write
POST /issuerInitiatedDigitizationDatas Request the issuerInitiatedDigitizationDatas read_write
GET /issuerInitiatedDigitizationDatas Search for issuerInitiatedDigitizationDatas requests read_only
books icon

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

Last Updated: 4/10/2024, 7:14:25 AM