🚧

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, and runs through Google’s TapAndPay SDK. The integration is called Unified Android Push Provisioning.

🚧

Google is ending support for legacy in-app push provisioning at the end of 2026. Every app with an in-app “Add to Google Wallet” button must be migrated before then. If you are still using the previous in-app provisioning, see Migrating to Google UPP for what to change.

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 TSP (Token Service Provider) in Google’s parlance, to generate and encrypt an OPC (Opaque Payment Card).

🚧

This guide shows using the UPP (Unified Push Provisioning) flow. This requires API Version 2026-07-01. Apple Pay and Samsung Pay behavior is unchanged on this version.

Google Pay UPP is not available in the sandbox environment.

“This API version” means 2026-07-01. On 2026-07-01, all Google Pay in-app push provisioning routes through UPP, whether or not you send server_session_id and google_opc_requested. Apple Pay and Samsung Pay integrations that call the same endpoint are not affected.

📘

The Google UPP parameters below — the server_session_id and google_opc_requested request parameters, and the google_provisioning_payload response parameter — require the api-version: 2026-07-01 request header. On earlier API versions the request and response are unchanged.

api-version is a request header that selects which version of the Lithic API serves a given request. Its value is a date, sent with no v prefix, e.g. "api-version: 2026-07-01". Send it alongside your Authorization header on the /cards/{card_token}/provision call. The version dropdown in these docs prefixes the same version with a v, but the header value should not include it. See API Versioning for the full list of versions and how to choose one.

1. Your user triggers push provisioning by pressing the “Add to Google Wallet” button in your app.
2. Your app calls Google’s TapAndPay SDK. When the SDK calls back into your app for the payment credentials, make your /cards/{card_token}/provision request from inside that callback, passing client_wallet_account_id and client_device_id. On API version 2026-07-01, client_device_id is optional, and you can additionally send server_session_id and google_opc_requested if you need the FPAN (Funding Primary Account Number) payload.
3. Lithic returns a base64 encoded provisioning_payload representing the card, which drives the tokenization flow. On API version 2026-07-01, when you send google_opc_requested as true, the response also carries google_provisioning_payload for the FPAN flow.
4. Your app returns the payloads to the TapAndPay SDK to complete provisioning.

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 TSP 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. Pass client_wallet_account_id and client_device_id in your /cards/{card_token}/provision request. Both are required regardless of network, though the values are only used for cards on the Visa network.
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"
}
'

Sending server_session_id or google_opc_requested on an earlier API version is accepted and silently ignored.

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. On API version 2026-07-01, a Google Pay response also carries google_provisioning_payload; see the sample below.

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

Sample Response: Google Pay with UPP (API version 2026-07-01)

On API version 2026-07-01, a Google Pay request that sets google_opc_requested to true and supplies server_session_id returns both payloads. google_provisioning_payload is a base64 encoded, encrypted payload representing card data for the Google Pay UPP FPAN flow.

{
  "provisioning_payload": "eyJjYXJkSW5mbyI...Q3MjRFRUEzQkI3OEU=",
  "google_provisioning_payload": "eyJlbmNyeXB0ZWREYXRhIjo...RjA5QUIxMkM0RA=="
}

On API version 2026-07-01, a Google Pay response carries google_provisioning_payload: it is populated when google_opc_requested was true, and returned as null rather than omitted when it was not. On earlier API versions the parameter is absent from the response entirely:

{
  "provisioning_payload": "eyJjYXJkSW5mbyI...Q3MjRFRUEzQkI3OEU=",
  "google_provisioning_payload": null
}

🚧

google_provisioning_payload is returned by the UPP flow, which is in Beta and is not currently available in the sandbox environment.