Push Provisioning
Learn how to add cards to digital wallets with push provisioning.
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:
- Obtaining Entitlements from the wallets
- Sharing your Entitlements with Lithic
- 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:
- Issuer Name: the name of your company, e.g., PayPal
- Country [Country Code]: e.g., Germany [DE]
- Developer Team ID: can be found here or here.
- Adam ID: can similarly be found from App Store Connect.
- 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:
- Push Provisioning API Access Request: https://support.google.com/faqs/contact/pp_api_allowlist?authuser=1
- 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:
- Application Identifiers
- Adam ID
- 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).
- First, your user triggers push provisioning by pressing the “Add to Apple Wallet” button in the app.
- Your app will then call Apple, who will generate Public Certificates and a nonce. Those determine how Lithic encrypts payment data.
- The Apple Public Certificates and nonce are provided to your app.
- 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). - We then return several pieces of information to your app: an
ephemeralPublicKey
,encryptedPassData
, andactivationData
. - 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)
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
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"
}
'
card_token (required, path parameter) | Globally unique identifier for the card to be added to a device's digital wallet. String. Permitted values: 36-digit version 4 UUID (including hyphens). |
certificate (only applicable if digital_wallet is APPLE_PAY ) | Apple's public leaf certificate, provided by the device's wallet. Omit to receive only activationData in the response. String. Permitted values: Base64 encoded in PEM format with headers ( -----BEGIN CERTIFICATE----- ) and trailers omitted. |
client_wallet_account_id (only applicable if digital_wallet is GOOGLE_PAY or SAMSUNG_PAY and the card is on the Visa network) | Consumer ID that identifies the wallet account holder entity. |
client_device_id (only applicable if digital_wallet is GOOGLE_PAY or SAMSUNG_PAY and the card is on the Visa network) | Stable device identification set by the wallet provider. |
digital_wallet (required) | Name of digital wallet to which the card will be added. String. Permitted values: APPLE_PAY , GOOGLE_PAY , SAMSUNG_PAY . |
nonce (only applicable if digital_wallet is APPLE_PAY ) | Number provided by the device's wallet to prevent replay attacks. Omit to receive only activationData in the response. String. Permitted values: Base64 cryptographic nonce. |
nonce_signature (only applicable if digital_wallet is APPLE_PAY ) | Device-specific signature for the nonce provided by the device's wallet. Omit to receive only activationData in the response. String. Permitted values: Base64 nonce signature. |
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="
}
Updated 3 months ago