​
Overview

This provides a convenient way for cardholders to store and use their payment cards securely. When the card is added to the digital wallet, the card’s sensitive data, i.e. the PAN, expiration date and CVV, is replaced with a token. This token serves as a reference to the card, and is used when the cardholder makes a payment using the digital wallet. This guide describes what features can be implemented as part of the Digital Wallet & Tokenization process:

Token provisioning methods

how a card can be added to a digital wallet an

Token lifecycle management

functions (e.g. token suspension) and webhooks for token status changes
The Digital Wallet & Tokenization feature can only be tested in the production environment.

​
Prerequisites

Before you can launch the digital wallet feature, the following steps must be completed:
  1. Your card BIN is tokenized - Synctera works with your sponsor bank to get the BIN tokenized with the network.
  2. You have submitted the required assets (such as digital wallet card art) to Synctera
  3. For in-app provisioning, you have gained entitlement access from the digital wallet providers, added the feature to your app (integrated with digital wallets and Synctera), and gained app UI/UX approval from the digital wallet providers
  4. You have fulfilled the testing requirements
Synctera’s Implementation & Onboarding Team will guide you through this process.

​
Adding a Card to a Digital Wallet

The integration steps depend on the provisioning method you want to support. The first two methods can be enabled directly on the card product, whereas in-app provisioning requires additional integration steps.

​
Manual provisioning:

The cardholder opens the wallet app (Apple Pay / Google Wallet) on a mobile device and manually adds the virtual or physical card to the wallet by typing in the card details.

​
Card-on-file:

The cardholder has already added a card to one device, but now wants to add it to another device. The card details that are available on-file are used to provision a separate token for the new device. Alternatively, this can happen when a customer submits their card to a merchant to be saved for future purchases. The merchant can then tokenize the card outside of our system, and we will get the token pushed to us by the network.

​
In-app provisioning:

This method is also called push-provisioning or instant issuance. Cardholder can “push” the card to the digital wallet from within your app, for example through a “Add to Wallet” button. You need to integrate with the digital wallet provider (instructions provided by Synctera) and with the Synctera platform by calling the correct endpoint based on the type of device: For Apple Pay compatible devices, call: 
POST /v0/cards/{card_id}/digital_wallet_tokens/applepay
Sample Request: 
{
  "device_type": "MOBILE_PHONE",
  "provisioning_app_version": "2.13.7",
  "certificates":  [
    "MIIEPDCCA+KgAwIBAgICEAAwCQYHKoZIzj...",
    "MIIDZjCCAw2gAwIBAgIJAJx22AGaEPSgMA..." ],
  "nonce": "vXWJaBidcTLaJJCF",
  "nonce_signature": "jD4Aphu+93N2wbBn"
}
For Google Wallet compatible devices, call: 
POST /v0/cards/{card_id}/digital_wallet_tokens/googlepay
Sample Request: 
{
  "device_type": "MOBILE_PHONE",
  "provisioning_app_version": "2.13.3",
  "wallet_account_id": "ae25OGhjZTk2dsr452dgsr51",
  "device_id": "W85OGhjZTk2dsr452dgsr51j"
}
See API reference for more information about Digital Wallet Tokens API.

​
Token approval process - step-up verification:

All token provisioning requests go through a token approval process, where the legitimacy of the request is scored. Based on the score, the request can either be automatically approved/declined or step-up verification is required. During step-up verification, the cardholder gets a one-time passcode (OTP) through email or SMS, based on preferences, and enters the code in the wallet for verification. This requires that all cardholders have an email and mobile phone number on file (enforced through the Synctera onboarding journey). Synctera offers support through the Synctera UI for resolving any issues that your customers may run into while adding their card to their digital wallet.

​
Token lifecycle

During its lifecycle, a card token can have the following states:
  • REQUESTED
  • REQUEST_DECLINED
  • ACTIVE - only from REQUESTED/SUSPENDED states
  • SUSPENDED - only from ACTIVE state
  • TERMINATED - irrevocable state
To change the state of a token, you can call: 
PATCH /v0/cards/digital_wallet_tokens/{digital_wallet_token_id}
Sample Request: 
{
  "token_status": "ACTIVE"
}
Sample Response: 
{
  "card_id": "ea4fe485-b688-4fc8-b861-a136245ab931",
  "device_id": "044B3013EE56800192111170603027118DE08E4001501681",
  "device_type": "MOBILE_PHONE",
  "id": "de0ebd60-4dd5-413a-a0cc-afbd91798f7c",
  "last_modified_time": "2022-05-06T18:58:02.587813Z",
  "requested_time": "2022-05-06T18:11:19Z",
  "state": "ACTIVE",
  "type": "APPLE_PAY"
}
Anytime a token state changes, a webhook event is generated:
  • card.digitalwallettoken.created - This webhook is published whenever the provisioning of a new token is requested, regardless of what provisioning method was used (manual, card-on-file, in-app).
  • card.digitalwallettoken.updated - This webhook is published whenever a digital wallet token status is updated. This update can be triggered directly by the PATCH endpoint or as a result of another action, e.g. when a pending token provisioning request gets approved or when a card is terminated or reissued.
To get a list of all tokens that have been provisioned for a card, including information on token state, call: 
GET /v0/cards/digital_wallet_tokens
Sample Response: 
{
  "digital_wallet_tokens": [
    {
      "card_id": "ea4fe485-b688-4fc8-b861-a136245ab931",
      "device_id": "044B3013EE56800192111170603027118DE08E4001501681",
      "device_type": "MOBILE_PHONE",
      "id": "de0ebd60-4dd5-413a-a0cc-afbd91798f7c",
      "last_modified_time": "2022-05-06T18:58:02.587813Z",
      "requested_time": "2022-05-06T18:11:19Z",
      "state": "ACTIVE",
      "type": "APPLE_PAY"
    },
    {
      "card_id": "6cfe1b97-f737-49e3-8aee-55bd19afa739",
      "device_id": "044B3013EE56800192111170603027118DE08E4001501681",
      "device_type": "MOBILE_PHONE",
      "id": "8fdf0a38-055d-41bd-a238-d79269335b7f",
      "last_modified_time": "2022-06-08T23:46:38.736908Z",
      "requested_time": "2022-05-16T20:48:18Z",
      "state": "ACTIVE",
      "type": "ANDROID_PAY"
    }
  ]
}
To get the details of a specific token, call: 
GET /v0/cards/digital_wallet_tokens/{digital_wallet_token_id}
Sample Response: 
{
  "card_id": "6cfe1b97-f737-49e3-8aee-55bd19afa739",
  "device_id": "044B3013EE56800192111170603027118DE08E4001501681",
  "device_type": "MOBILE_PHONE",
  "id": "8fdf0a38-055d-41bd-a238-d79269335b7f",
  "last_modified_time": "2022-06-08T23:46:38.736908Z",
  "requested_time": "2022-05-16T20:48:18Z",
  "state": "ACTIVE",
  "type": "ANDROID_PAY"
}
  • When a card is reissued through the POST /cards endpoint, the token associated with the old card is automatically transferred to the new card
  • When a card is terminated through the PATCH /cards endpoint, the token associated with the card is automatically TERMINATED
  • When a virtual card moves to a new cardholder through the PATCH /cards endpoint, the tokens associated with the card that were provisioned to the old cardholder are automatically TERMINATED
See API reference for more information about Digital Wallet Tokens API.