🚧

Before setting up digital wallet in-app 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, the owner of your Apple developer account (the account holder) must submit a request using Apple's Apple Pay In-App Provisioning request form.

The form asks a series of program-related questions. Be prepared to provide:

1. Card issuer name: the name of your company, e.g., PayPal
2. App name: the name of your app, e.g., PayPal Mobile
3. Apple/Adam ID: can be found from App Store Connect
4. A description of how your app will use this capability
5. The sponsor bank you are working with to offer your debit or credit product
6. Whether you plan to offer both a physical and digital card for customers
7. Whether you plan to use a third party in the development and/or management of your app when using Apple Pay (if so, the company name)

Once Apple Pay approves your request, they will follow up with the remaining setup steps, 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>

Entitlements from Samsung

To obtain entitlements from Samsung, your dev team must create an account and request access to the Samsung Pay developer portal. Once access has been granted, complete the following onboarding steps in the portal:

1. Create a push provisioning service, providing service details such as the service name and issuer name
2. Register the app that will handle push provisioning card enrollment, or select an existing one
3. Submit a service release request with your production app for Samsung's review
4. Once Samsung approves the request, release the service to make push provisioning available

Your developers can find detailed set-up instructions in the portal and reach out to Samsung with any inquiries.

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 & Samsung, 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).

Push Provisioning with Samsung

Push provisioning with Samsung Pay uses the Samsung Pay SDK and requires access to the Samsung Pay developer portal (see Entitlements from Samsung). As with Google, Lithic acts as the Token Service Provider that generates and encrypts the payload Samsung provisions to the wallet.

1. Your user triggers push provisioning by pressing the “Add to Samsung Wallet” button in your app. Use Samsung’s official button assets and follow their button design guidelines; the assets are available through the Samsung Pay developer portal.
2. Your app confirms Samsung Wallet is ready and gathers the wallet and device identifiers Samsung provides.
3. If the card is on the Visa network, you will need to pass these as the additional fields: client_wallet_account_id and client_device_id in your /cards/{card_token}/provision request.
4. Lithic returns a base64 encoded provisioning_payload representing the card.
5. Your app hands this payload to the Samsung Pay SDK to complete provisioning.

For SDK setup, method signatures, and how to pass the payload, see Samsung’s push provisioning documentation.

Provision Card - Digital Wallet

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

Object containing the fields required to add a card to Apple Pay. Applies only to Apple Pay wallet. The details may vary based on the digital wallet provider; consult the wallet's documentation for more info.

{
  "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="
}