Home / Guides/ Issue Cards
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:
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.
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:
You can then query for the status of a token.
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.
Use the SimulateCardDigitalWalletTokenActivated
mutation to change an existing card digital wallet token which is in a REQUESTED
state to ACTIVE
.
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:
paymentCardId
provided is validACTIVE
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.
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.
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:
paymentCardId
provided is validACTIVE
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.
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.
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:
The following states are associated with a digital wallet token provisioning request:
Token State | Description |
---|---|
REQUESTED | Account has requested a digital wallet token. |
APPROVED | Account 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. |
DENIED | The Payment Card cannot be tokenized and may be due to the payment card’s state or invalid data was provided. |
PENDING_VERIFICATION | The 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 State | Description |
---|---|
ACTIVE | The token has been provisioned and is available for transaction use. |
REQUESTED | The initial state of the token. The token is not yet available for use. |
SUSPENDED | The 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. |
TERMINATED | The token has been deleted and is no longer available for transaction use. |
You can search for digital wallet tokens on a given Payment Card or a digital wallet token’s associated payment card.
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 Reason | Description |
---|---|
DEVICE_LOST | Device is reported as lost. |
DEVICE_STOLEN | Device is reported as stolen. |
FRAUDULENT_TRANSACTIONS | Fraudulent transactions have been reported by Highnote or the account holder. |
OTHER | Any other reason for suspending the card digital wallet 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 Reason | Description |
---|---|
DEVICE_FOUND | A lost or stolen device has been found or recovered. |
NON_FRAUDULENT_TRANSACTIONS | After reviewing transaction history, the account holder or Highnote confirmed that there were no fraudulent transactions. |
OTHER | Any other reason for reactivating the card digital wallet 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 Reason | Description |
---|---|
ACCOUNT_HOLDER_DELETED | Account holder has been deleted. |
DEVICE_LOST | Device is reported as lost. |
DEVICE_STOLEN | Device is reported as stolen. |
FRAUDULENT_TRANSACTIONS | Fraudulent transactions have been reported by Highnote or the account holder. |
OTHER | Any other reason for terminating the card digital wallet token. |
You can find the status of a given token and its historical state transitions using the cardDigitalWalletTokenId
.