Add Cards to Digital Wallets

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

Complete the steps in the Digital Wallet Product Preparation Guide before starting a push provisioning implementation.

Push provisioning is the process of remotely setting up and configuring a digital wallet application on a user's device so that it can be used to make mobile payments.

Before creating a push provisioning implementation, you must complete several prerequisite steps with the Highnote team. You can expect the steps outlined in this guide while preparing to implement Apple Pay and Google Pay push provisioning.

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

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

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

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.

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

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.

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

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

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.

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:

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:

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:

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