Add Cards to Digital Wallets

1. A Highnote account
2. An API key or the API Explorer
3. An approved tokenized card design

Digital wallets enhance security by creating a token: a digital account number that is 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 provision payment cards to digital wallets such as Apple Pay, Google Wallet, and Samsung Pay. Payment cards are added to digital wallets 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

This guide provides steps for creating a push provisioning implementation.

Apple requires you to complete the following steps before developing a push provisioning project. The Highnote team will assist with each step as you prepare for your push provisioning implementation:

1. Sign the Apple Pay Terms and Conditions and list Highnote as your program manager.
2. Email applepayentitlements@apple.com and implementation-team@highnote.com with the following information:

• A request to enable Apple Pay push provisioning in your app
• Your App name as it appears on AppStore Connect
• Your Developer team ID
• Your ADAM ID (Example: 13254705253)
• Your Bundle ID (Example: com.company.appname)
• Application Launch URL (Example: myapp://apple_wallet)
• Whether you already have an app published to the App Store

After receiving a response from the Apple Pay Entitlements team, you can expect to answer the following questions:

• Who is the sponsor bank you work with to offer your debit or credit product?
• Please provide an overview of your product and how you plan to use Apple Pay. For example, you can explain that your application provides users a method to add their card to Apple Pay directly using the Add to Wallet interface.
• Are you planning to offer both physical and virtual cards for customers? Answer yes or no depending on your card product details.
• What are your proposed use cases for in-app (push) provisioning? For example, you can explain you are adding the capability to add a card to Apple Pay directly from your application.
• Do you plan to use a third party in the development and/or management of Apple Pay? If yes, provide the third-party company name.
• In what country is your business headquarters located? Provide your headquarters' location.
• What is your Team Name? Provide the name of your company or division.

After completing the previous steps, you can access Apple Pay's Wallet API documentation for more information on building your push provisioning implementation.

Google requires you to complete the following steps before developing a push provisioning project. The Highnote team will assist with each step as you prepare for your push provisioning implementation:

1. Apply for Google Wallet documentation access.
2. Define package name for Activation Method. For example, com.grppl.android.shell.TheIssuer.
3. Define action for Activation Method. For example, action.open_issuerapp.
4. Define package name for App Launching. For example, com.grppl.android.shell.TheIssuer.
5. Define action for App Launching. For example, action.open_issuerapp.
6. Submit Google's Push Provisioning API Access request form.

After submitting the request form, you will receive a response prompting you to provide more information to describe your company. The Highnote team will assist with providing answers to additional information requests. You can expect the following responses:

• Select the option that best describes your company. For example, you might select a financial company or card issuer operating under a BIN Sponsor.
• Does your company have a signed CTA with Google?
• Does your BIN/Sponsor or Program Manager have a signed CTA agreement with Google?
• Name of program manager: For this response, you would provide the answer of Highnote.
• App Package name
• Launch date
• Please select the appropriate network(s): Visa or Mastercard

After completing the previous steps, you can complete Google's Push Provisioning API UX Review Request.

After completing the prerequisites for the digital wallets you wish to support, the Highnote team will secure payment network push provisioning approval and establish a kickoff meeting with your development team.

Google provides a standard solution that your development team can utilize. See Google's SDK releases for more information.

Warning: The Highnote test environment lets you explore the platform features and functionality freely. It is intended for experimenting, building integrations, and training your team.

To ensure the security of your real-world data, please don't use production data in the test environment. Production data includes sensitive information like customer details, financial data, or personally identifiable information (PII).

Use only dummy or test data explicitly created for testing purposes in the test environment.

You can simulate generating a token and perform authorizations on various token statuses in the test environment. Generating a token is a two-step process:

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 that is in the requested state.

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.

The Apple Pay push provisioning process will validate the following when an account holder adds a payment card to their Apple Wallet:

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

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

The following graphic is an example of an Apple Pay push provisioning user interface (UI) experience:

The following graphic displays the flow of data during the Apple Pay push provisioning process:

The Google Wallet push 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.

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

The following graphic is an example of a Google Wallet push provisioning user interface (UI) experience:

The following graphic displays the flow of data during the Google Wallet push provisioning process:

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 the 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 into the digital wallet.
• SMS: A passcode will be sent by Highnote to the customer’s mobile phone, which they will enter into 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:

You can search for digital wallet tokens on a given payment card or a digital wallet token’s associated payment card using the following query:

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:

Use the following mutation to suspend a 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:

Use the following mutation to unsuspend a token:

A token may be terminated by your customer support agents or 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:

Use the following mutation to terminate a token:

You can find the status of a token and its historical state transitions using the following query: