Home / Guides/ Issue Cards

Add Cards to Digital Wallets

Overview

Digital Wallets require set up as outlined in Card Design.

Payment cards may be provisioned to digital wallets such as Apple Pay, Google Pay, and Samsung Pay. Payment cards may be added to a digital wallet in two ways:

  • Manual Entry An account holder opens a digital wallet app on their phone and manually enters their card details
  • Push Provisioning An account holder taps a button in your iOS or Android app and enters a provisioning flow native to the device

Digital wallet payments enhance security by creating a token - a digital account number that acts as a substitute value for a customer's personal account number (PAN). This token is presented to the merchant, rather than the PAN, so the merchant cannot see or retain the payment card’s information.

Simulate Token Provisioning

You can simulate generating a token and perform authorizations on various token statuses in the Test environment. It's a two step process to generate a token:

  1. Request Token: This step will request a card digital wallet token for a specific payment card.
  2. Activate Token: This step will activate the requested payment card digital wallet token based on a payment card digital wallet token id which is in requested state.

You can then query for the status of a token.

Simulate Token Activation

You can use the SimulateCardDigitalWalletTokenActivation mutation to request a digital wallet token for a Payment Card. This will create a card digital wallet token with a status as REQUESTED. The token is not ready for use until it is activated.

Simulate Token Activated

Use the SimulateCardDigitalWalletTokenActivated mutation to change an existing card digital wallet token which is in a REQUESTED state to ACTIVE.

Apple Pay Push Provisioning

At this time, only Card Products on the Mastercard network may use Push Provisioning.

Enable your account holders to provision their card to Apple Wallet/Apple Pay directly from your iOS app without manually entering card details.

The provisioning process will validate the following:

  • The paymentCardId provided is valid
  • The Payment Card has a status of ACTIVE
  • The Payment Card is allowed to be provisioned

If any of the above criteria fails validation, the request will be rejected. If all validations pass, the API will return the response required by Apple’s SDK for provisioning the Card to the Apple Wallet.

User Experience

You will need to add an "Add to Apple Wallet" call to action in your iOS app that uses the mutation AddPaymentCardToApplePayByDevicePushProvisioning.

Apple provides guidelines and assets for the button.

Apple Wallet Provisioning Experience

apple-pay_provisioning-flow.svg

Provisioning Flow

apple-pay-diagram.svg

Google Pay Push Provisioning

At this time, only Card Products on the Mastercard network may use Push Provisioning.

Enable your account holders to provision their card to Google Wallet/Google Pay directly from your Android app without manually entering card details.

The provisioning process will validate the following:

  • The paymentCardId provided is valid
  • The Payment Card has a status of ACTIVE
  • The Payment Card is allowed to be provisioned

If any of the above criteria fails validation, the request will be rejected. If all validations pass, the API will return the response required by Google SDK for provisioning the Card to the Google Wallet.

User Experience

You will need to add a "Save to Phone" call to action in your Android app that uses the mutation AddPaymentCardToGooglePayByDevicePushProvisioning.

Google provides assets for the button.

Google Wallet Provisioning Experience

google-pay_provisioning-flow.jpg

Provisioning Flow

google-pay-diagram.svg

Managing Digital Wallet Tokens

When a payment card is added to a digital wallet, a token provisioning request will be sent to the digital wallet, network, and Highnote. The request may go to PENDING_VERIFICATION state, which will require your account holder to verify their identity. The following verification methods may be configured for your product:

  • Email: A passcode will be sent by Highnote to the customer’s email which they will enter in the digital wallet.
  • SMS: A passcode will be sent by Highnote to the customer’s mobile phone which they will enter in the digital wallet.
  • Customer Service: The Account Holder will be able to view the phone number for Customer Service that they may call to complete verification.

The following states are associated with a digital wallet token provisioning request:

Token StateDescription
REQUESTEDAccount has requested a digital wallet token.
APPROVEDAccount Holder was successfully able to tokenize the payment card without additional identify verification. The token will be in an ACTIVE state and ready for transaction use.
DENIEDThe Payment Card cannot be tokenized and may be due to the payment card’s state or invalid data was provided.
PENDING_VERIFICATIONThe wallet provider, network, or issuer have requested additional identity details from the Account Holder to validate their identify.

A token always begins in a REQUESTED state. The token may systemically move to an ACTIVE state if no additional verification is required or once the customer has successfully verified their identity through the program's additional identity verification method. A token can move between a SUSPENDED state and an ACTIVE state. Once a token is TERMINATED, the token cannot move back to an ACTIVE state.

Token StateDescription
ACTIVEThe token has been provisioned and is available for transaction use.
REQUESTEDThe initial state of the token. The token is not yet available for use.
SUSPENDEDThe token has been blocked from transaction use and action may be required by the Account Holder. Tokens can be suspended by the Issuer, Program Owner, or Account Holder.
TERMINATEDThe token has been deleted and is no longer available for transaction use.

Find a Payment Card’s Tokens

You can search for digital wallet tokens on a given Payment Card or a digital wallet token’s associated payment card.

Suspend Token

Your Account Holders can suspend a token temporarily or a customer support agent may suspend a token if additional verification is required by the Account Holder.

Suspended tokens may have the following reasons associated with the token:

Suspended ReasonDescription
DEVICE_LOSTDevice is reported as lost.
DEVICE_STOLENDevice is reported as stolen.
FRAUDULENT_TRANSACTIONSFraudulent transactions have been reported by Highnote or the account holder.
OTHERAny other reason for suspending the card digital wallet token.

Unsuspend Token

You may provide your customer support agents or your Account Holders' the ability to reactivate or unsuspend a token after it has been suspended.

Suspended tokens that have been unsuspended or reactivated may have the following reasons associated with the token:

Unsuspend ReasonDescription
DEVICE_FOUNDA lost or stolen device has been found or recovered.
NON_FRAUDULENT_TRANSACTIONSAfter reviewing transaction history, the account holder or Highnote confirmed that there were no fraudulent transactions.
OTHERAny other reason for reactivating the card digital wallet token.

Terminate Token

A token may be terminated by your customer support agents or by your Account Holders. Once a token is terminated, the token is deleted and can no longer be used to transact. A new token must be created once it is terminated.

Terminated tokens may have the following reasons associated with the token:

Termination ReasonDescription
ACCOUNT_HOLDER_DELETEDAccount holder has been deleted.
DEVICE_LOSTDevice is reported as lost.
DEVICE_STOLENDevice is reported as stolen.
FRAUDULENT_TRANSACTIONSFraudulent transactions have been reported by Highnote or the account holder.
OTHERAny other reason for terminating the card digital wallet token.

View Token’s Status & Details

You can find the status of a given token and its historical state transitions using the cardDigitalWalletTokenId.

Provide Feedback

Was this content helpful?