🚧

Note: Before setting up digital wallet push provisioning, the implementation steps for digital wallets must be complete.

Push provisioning allows your cardholders to add their virtual or physical cards to their digital wallets with the tap of a button in your mobile app. This lets them skip manually typing in their card information.

Guide: Enabling Push Provisioning

There are three main steps to enabling push provisioning:

1. Obtaining Entitlements from the wallets
2. Sharing your Entitlements with Lithic
3. Setting up the Add to Wallet button

1. Obtaining Entitlements from the Wallets

Entitlements from Apple

To obtain entitlements from Apple, have the owner of your Apple developer account send the following to the Apple Pay Entitlements team at [email protected]:

Subject: Apple Pay Entitlement & Whitelisting Request - Issuer Name - [Country Code]
e.g. Apple Pay Entitlement & Whitelisting Request - MyBank - [DE]

Body:

1. Issuer Name: the name of your company, e.g., PayPal
2. Country [Country Code]: e.g., Germany [DE]
3. Developer Team ID: can be found here or here.
4. Adam ID: can similarly be found from App Store Connect.
5. App Name: the name of your app, e.g., PayPal Mobile

If approved by Apple Pay, the team should send you an email with additional steps to complete, including entitlement configuration, and metadata/payment data configuration.

Entitlements from Google

To obtain entitlements from Google, request access to Google’s Push Provisioning API here:

1. Push Provisioning API Access Request: https://support.google.com/faqs/contact/pp_api_allowlist?authuser=1
2. Push Provisioning API UX Review Request: https://support.google.com/faqs/contact/pp_api_ux

2. Sharing Entitlements with Lithic

Once you’ve completed the entitlements process with the digital wallets, you’ll need to share the following with Lithic:

Apple:

1. Application Identifiers
2. Adam ID
3. Application Launch URL

Share these with your implementation or customer success manager.

For Google, you'll need to obtain Push Provisioning API Access (see link above) to be added to Google's allowlist.

3. Setting up the Add to Wallet button

Once you’ve shared your entitlements with Lithic, you’re ready to set up your Add to Wallet button in your mobile app! When your users click Add to Wallet, you’ll make a series of calls to the wallets and Lithic to kick off the digital wallet tokenization process.

Push Provisioning with Apple

Push provisioning with Apple Wallet involves several parties: your app, Apple Wallet/Servers, and Lithic (your issuer).

1. First, your user triggers push provisioning by pressing the “Add to Apple Wallet” button in the app.
2. Your app will then call Apple, who will generate Public Certificates and a nonce. Those determine how Lithic encrypts payment data.
3. The Apple Public Certificates and nonce are provided to your app.
4. Your app then passes this certificate and nonce to Lithic as part of your call to the /cards/{card_token}/provision endpoint (see Provision Card - Digital Wallet).
5. We then return several pieces of information to your app: an ephemeralPublicKey, encryptedPassData, and activationData.
6. Your app passes this data to Apple, who coordinates with the card network to kick off the regular digital wallet tokenization flow.

Check out Apple's Wallet documentation for more detail.

Push Provisioning with Apple (activationData Only)

If you only require activationData (e.g. a card is already added to Apple Wallet and only needs to be activated) you can omit steps 2 and 3 above. By omitting the certificate, nonce, and nonce_signature in the /cards/{card_token}/provision request body you will only receive the activationData in the response body which can then be passed to Apple.

Push Provisioning with Google

Push provisioning with Google Wallet is similar. Once you’ve been approved for access to Google’s Push Provisioning API, go to Google’s Integration Steps page to see their documentation.

For Google, you’ll work with us (the “Token Service Provider”, or TSP, in Google’s parlance) to generate and encrypt an Opaque Payment Card (OPC).

Provision Card - Digital Wallet (Enterprise)

API Reference: Provision card (Digital Wallet)

As part of the push provisioning flow, when your user presses the “Add to Wallet” button, you’ll want to call Lithic to generate an encrypted provisioning_payload. This cryptographic payload represents a payment card that can be passed to a device's digital wallet.

To determine if a transaction originated from a card once provisioned to the wallet, use the token_info field in ASA.

POST https://api.lithic.com/v1/cards/{card_token}/provision

Sample Request

curl https://api.lithic.com/v1/cards/f5f905f5-8a8e-49bf-a9b4-c0adaa401456/provision \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "digital_wallet":"APPLE_PAY"
}
'

Sample Response: Apple Pay

{
     "provisioning_payload": {"activationData": "...", "ephemeralPublicKey": "...", "encryptedData": "..."}
}

Sample Response: Google Pay or Samsung Pay

The provisioning_payload is a base64 encoded JSON payload. The details of this payload may vary based on the digital wallet provider; consult the wallet's documentation for more info.

{
     "provisioning_payload": "eyJjYXJkSW5mbyI...Q3MjRFRUEzQkI3OEU="
}