Add to Wallet

Apple Pay and Google Wallet Unified Push Provisioning (UPP) use the same endpoint. google_pay is the Legacy Google Pay integration for existing integrations. Reach out to your Imprint team to coordinate wallet enablement for your program.

Overview

Add to Wallet lets a customer provision their Imprint card into a device wallet — Apple Pay or Google Wallet — without leaving your app. The platform wallet SDK is the wallet framework the operating system provides: PassKit (PKAddPaymentPassViewController) on iOS, and the TapAndPay client on Android. Apple and Google ship it, not Imprint, and your app links it to show the native Add to Wallet sheet. Your app collects the values supplied by the platform wallet SDK, passes them to Imprint, and Imprint returns the encrypted payload the SDK needs to finish adding the card. Imprint never asks you to handle the card number. The provisioning payload is encrypted for the wallet provider, so your app acts purely as a courier between the platform wallet SDK and Imprint. What this unlocks: a customer who has just been approved for a card can tap Add to Apple Wallet in your app and start making contactless payments immediately — before the physical card arrives in the mail.

What you need

Requirement	Notes
A native iOS or Android app	This flow is only supported for mobile applications. See Not supported for web.
Wallet enablement for your program	Reach out to your Imprint team to coordinate wallet enablement for your program. This is not self-serve — provisioning calls fail until your program is enabled.
Wallet entitlements from Apple or Google	Apple requires the `com.apple.developer.payment-pass-provisioning` entitlement; Google requires allowlisting for the TapAndPay push-provisioning API. Both are granted by the platform, not by Imprint.
An API key with card write access	Contact your Imprint team if provisioning calls return `403`.
The `payment_method_id` of a card in `ACTIVE` status	Retrieved from Retrieve a payment method or the Payment Method Event Notification webhook.

How the flow works

The critical detail: your app talks to the platform wallet SDK first. The wallet SDK produces the values Imprint needs. Only then do you call Imprint.

Your app asks the platform wallet to begin

The customer taps Add to Wallet. Your app starts the platform’s add-card flow (PKAddPaymentPassViewController on iOS, Google Wallet UPP through TapAndPay on Android).

The wallet SDK hands your app the values Imprint needs

On iOS this is a certificate chain, a nonce, and a nonce signature — a single-use handshake. On Android, Google’s payment-credentials callback supplies the active wallet ID, stable device ID, Google OPC request flag, and a server session ID when the Google OPC is requested.

Your app calls Imprint

POST /v2/payment_methods/{payment_method_id}/provision/{wallet}, forwarding the handshake.

Imprint returns an encrypted provisioning payload

Imprint validates that the payment method belongs to you, then requests the encrypted payload from the card network on your behalf.

Your app hands the payload back to the wallet SDK

The SDK decrypts it and adds the card. The customer sees the card appear in their wallet.

Apple Pay only: the handshake from step 2 is single-use and short-lived. You cannot cache an Imprint provisioning response and replay it later, and you cannot call Imprint with a nonce from a previous attempt. If provisioning fails, dismiss and restart PKAddPaymentPassViewController from step 1 so PassKit issues a fresh nonce.For Google Wallet UPP, call Imprint inside Google’s payment-credentials callback. If the attempt fails, start a new UPP attempt and use its callback values. Do not reuse an earlier payload or server session ID. Legacy Google Pay retries may re-send the same stable wallet_id and device_id.

In every flow the provisioning payload Imprint returns is single-use: hand it straight to the platform wallet SDK and never cache or persist it.

The endpoint

POST /v2/payment_methods/{payment_method_id}/provision/{wallet}

Parameter	In	Description
`payment_method_id`	path	The payment method to provision.
`wallet`	path	The target device wallet: `apple_pay`, `google_wallet`, or `google_pay` (Legacy).

Request body options

Option	`wallet` path value	Request body
Option 1: Apple Pay	`apple_pay`	`certificates`, `nonce`, and `nonce_signature` from PassKit.
Option 2: Google Wallet UPP	`google_wallet`	`wallet_id`, `device_id`, and `google_opc_requested` from Google’s payment-credentials callback; `server_session_id` when Google requests the additional OPC.
Option 3: Google Pay Legacy	`google_pay`	`wallet_id` from `TapAndPayClient.getActiveWalletId()` and `device_id` from `TapAndPayClient.getStableHardwareId()`.

See the API reference for the full request and response schemas.

Apple Pay (`apple_pay`)

Request

Take these three values from your PKAddPaymentPassViewControllerDelegate callback:

addPaymentPassViewController:generateRequestWithCertificateChain:nonce:nonceSignature:

PassKit gives you certificateChain as [Data] and nonce / nonceSignature as Data. Base64-encode each one before sending it — Imprint rejects raw bytes with invalid_request. Do not otherwise transform the values.

let body: [String: Any] = [
    "certificates": certificateChain.map { $0.base64EncodedString() },
    "nonce": nonce.base64EncodedString(),
    "nonce_signature": nonceSignature.base64EncodedString(),
]

{
  "certificates": ["MIIEg...leaf", "MIIDx...intermediate"],
  "nonce": "3vT9Kw==",
  "nonce_signature": "R0hJSkt..."
}

Field	Type	Description
`certificates`	`string[]`	Base64-encoded. The leaf certificate followed by the intermediate certificate, in the order PassKit supplied them.
`nonce`	`string`	Base64-encoded nonce from PassKit.
`nonce_signature`	`string`	Base64-encoded nonce signature from PassKit.

Response

{
  "wallet": "apple_pay",
  "provisioning_payload": {
    "activation_data": "YWN0aXZhdGlvbg==",
    "encrypted_pass_data": "ZW5jcnlwdGVkUGFzcw==",
    "ephemeral_public_key": "ZXBoZW1lcmFsS2V5"
  }
}

Map the payload onto PKAddPaymentPassRequest. Base64-decode each value first — Imprint returns Base64 strings, but the PassKit properties are Data. Assigning the strings without decoding hands PassKit the wrong bytes and provisioning fails.

Imprint field	`PKAddPaymentPassRequest` property
`activation_data`	`activationData`
`encrypted_pass_data`	`encryptedPassData`
`ephemeral_public_key`	`ephemeralPublicKey`

let request = PKAddPaymentPassRequest()
request.activationData = Data(base64Encoded: response.activationData)
request.encryptedPassData = Data(base64Encoded: response.encryptedPassData)
request.ephemeralPublicKey = Data(base64Encoded: response.ephemeralPublicKey)

Then pass the request to the completion handler PassKit gave you in the delegate callback.

Imprint uses elliptic-curve key exchange, so ephemeral_public_key is always the key field in the response. You do not need to handle the RSA wrappedKey variant.

Google Wallet UPP (`google_wallet`)

Use google_wallet for new Android integrations. Start provisioning through the TapAndPay SDK with a PaymentCredentialsGenerator, then call Imprint from inside Google’s GeneratePaymentCredentialsRequest callback. The callback tells you whether Google also needs an opaque payment card for the cardholder’s Google Account; pass that decision through rather than setting it yourself.

Inputs before Google’s callback

Build a PushTokenizeRequest and pass it to TapAndPayClient.pushTokenize. These inputs come from your app’s existing card and customer data; they are available before you call Imprint’s provisioning endpoint.

Input	Value or source	How to pass it to Google
Payment credentials generator	Your implementation of `PaymentCredentialsGenerator`. Its `generate(request)` method calls your backend, which calls Imprint for the selected payment method.	`setPaymentCredentialsGenerator(generator)`
Card network	`TapAndPay.CARD_NETWORK_VISA`, `TapAndPay.CARD_NETWORK_MASTERCARD`, or `TapAndPay.CARD_NETWORK_AMEX`.	`setNetwork(cardNetwork)`
Token service provider	Derived from that same card network using the mapping below.	`setTokenServiceProvider(...)`. This value is not supplied by the provisioning response or the `wallet` path parameter.
Display name	A user-facing name for the card, such as the card name, card program, or brand name.	`setDisplayName(displayName)`
Last four digits	The selected payment method’s `card.last4` or `secured_credit_card.last4`.
Customer address (optional)	Used to prefill the billing address in the add to Google Wallet flow.

Use constants from com.google.android.gms.tapandpay.TapAndPay:

Card network	`setNetwork`	`setTokenServiceProvider`
Visa	`TapAndPay.CARD_NETWORK_VISA`	`TapAndPay.TOKEN_PROVIDER_VISA`
Mastercard	`TapAndPay.CARD_NETWORK_MASTERCARD`	`TapAndPay.TOKEN_PROVIDER_MASTERCARD`
American Express	`TapAndPay.CARD_NETWORK_AMEX`	`TapAndPay.TOKEN_PROVIDER_AMEX`

Request

Google invokes PaymentCredentialsGenerator.generate(request) with a GeneratePaymentCredentialsRequest after you start pushTokenize. Read all four fields from that callback for the current attempt:

{
  "wallet_id": "3a5f9c21e8b74d6f",
  "device_id": "9b1c7e04f2a8",
  "google_opc_requested": true,
  "server_session_id": "<server session ID from Google>"
}

Partner API field	Kotlin callback value	Origin and meaning	Requirement
`wallet_id`	`request.walletId`	Google supplies the active wallet’s identifier.	Required, nonblank.
`device_id`	`request.stableHardwareId`	Google supplies its stable hardware identifier for this device in the `GeneratePaymentCredentialsRequest` callback.
`google_opc_requested`	`request.googleOpaquePaymentCardRequested`	Google decides whether this attempt also needs a Google OPC for the customer’s Google Account.	Send Google’s boolean unchanged. The API defaults to `false` if omitted.
`server_session_id`	`request.serverSessionId`	Google’s server generates the provisioning session ID and supplies it through the callback.	Required when `google_opc_requested` is `true`; otherwise optional.

For example, inside generate(request), build the JSON body to forward through your backend:

val body = JSONObject()
    .put("wallet_id", request.walletId)
    .put("device_id", request.stableHardwareId)
    .put("google_opc_requested", request.googleOpaquePaymentCardRequested)
    .apply {
        request.serverSessionId?.let { put("server_session_id", it) }
    }

Google generates serverSessionId for this UPP attempt and supplies it in the Android GeneratePaymentCredentialsRequest callback. It identifies the intended provisioning session for the Google opaque payment card. It is not a Lithic or Imprint response field: send the callback value unchanged as server_session_id in your request to Imprint, which forwards it to Lithic. See Google’s Google OPC specification and Lithic’s UPP request guidance. When Google supplies googleOpaquePaymentCardRequested: false, send false and omit server_session_id if Google did not supply one. Do not force the flag to true or invent a session ID. If the required wallet or device ID is missing, do not fabricate one.

Response

{
  "provisioning_payload": {
    "opaque_payment_card": "eyJraWQiOi...",
    "google_provisioning_payload": "ZXlKcmFXUWlPaS4uLg=="
  }
}

Field	Type	Description
`opaque_payment_card`	`string`	Always present. The TSP opaque payment card for provisioning the device token used for contactless payments.
`google_provisioning_payload`	`string`	Present only when `google_opc_requested` was `true`. The Google opaque payment card for saving the card to the customer’s Google Account for online payments.

The Google Wallet response does not include a wallet, network, or wallet_type field. The TapAndPay request still needs the card network and its token service provider, which your app must obtain from its existing card or program configuration, not this response. In the PaymentCredentialsGenerator callback, map the response as follows:

val payload = response.provisioningPayload
val credentials = GeneratePaymentCredentialsResponse.Builder()
    .setOpaquePaymentCard(payload.opaquePaymentCard.toByteArray(StandardCharsets.UTF_8))

if (request.googleOpaquePaymentCardRequested) {
    val googleOpc = requireNotNull(payload.googleProvisioningPayload)
    credentials.setGoogleOpaquePaymentCard(googleOpc.toByteArray(StandardCharsets.UTF_8))
}

return credentials.build()

If Google requested the additional OPC but Imprint did not return it, fail the callback; do not fall back to the device-token-only path. Keep your Imprint API key on your backend, never in the Android app, and do not log, cache, or persist either payload.

Google Wallet UPP requires Google issuer-app access and launch validation. Coordinate testing and wallet enablement with your Imprint team before release.

Google Pay Legacy (`google_pay`)

google_pay is the Legacy flow: it obtains the opaque payment card before starting TapAndPay push tokenization. New integrations should use google_wallet UPP.

Request

{
  "wallet_id": "3a5f9c21e8b74d6f",
  "device_id": "9b1c7e04f2a8"
}

Field	Type	Description
`wallet_id`	`string`	The active wallet ID from the TapAndPay client.
`device_id`	`string`	A stable hardware-scoped device identifier from the TapAndPay client.

Response

{
  "wallet": "google_pay",
  "provisioning_payload": {
    "opaque_payment_card": "eyJraWQiOi...",
    "network": "VISA",
    "wallet_type": "GOOGLE_PAY"
  }
}

Field	Type	Description
`opaque_payment_card`	`string`	The encrypted payload for TapAndPay. Pass through unmodified.
`network`	`string`	The card network returned by the issuing processor. Required in a successful Legacy response.
`wallet_type`	`string`	Echoes the wallet you provisioned. Always `GOOGLE_PAY`.

opaque_payment_card is the only value that must come from this response. Build the rest of the PushTokenizeRequest from values you already have:

`PushTokenizeRequest` setter	Where the value comes from
`setOpaquePaymentCard`	`opaque_payment_card` from this response
`setNetwork`	`network` from this response, or the known card network for your program, mapped to a TapAndPay `CardNetwork` constant
`setTokenServiceProvider`	The network’s token service provider — not returned by this endpoint
`setDisplayName`	Your own copy, or the cardholder name
`setLastDigits`	The payment method object

wallet_type is not a TokenServiceProvider. TapAndPay requires setTokenServiceProvider on every request, and its value is derived from the card network (for example a Visa card uses TOKEN_PROVIDER_VISA), not from the wallet you are provisioning into. Passing "GOOGLE_PAY" there will fail.Confirm the correct network and token service provider constants with your Imprint team during integration.

Errors

Provisioning errors use the standard Imprint error envelope described in Error handling, with a machine-readable code:

422

{
  "error": {
    "code": "device_ineligible",
    "message": "this device cannot accept this card"
  }
}

Status	`code`	What to do
`400`	`invalid_request`	A required field is missing, a PassKit value is invalid, or `google_opc_requested` is `true` without `server_session_id`. Correct the input and start a fresh wallet attempt.
`400`	`wallet_unsupported`	The `wallet` path value is not a wallet Imprint supports yet.
`403`	`permission_denied`	Your API key lacks the `CARD_WRITE` scope. Contact your Imprint team.
`404`	`payment_method_not_found`	The payment method does not exist, or does not belong to your program.
`409`	`already_provisioned`	This card is already in this wallet on this device. Treat as success in your UI.
`422`	`device_ineligible`	The device cannot accept this card. Surface a message; retrying will not help.
`504`	—	An upstream timeout. The request may or may not have been applied; check the wallet state before retrying, and get a fresh Apple Pay handshake first.

Do not blind-retry a failed Apple Pay call. Each PassKit nonce is single-use, so replaying the original request body fails with invalid_request — you must go back through PKAddPaymentPassViewController for a new one.Google Wallet UPP retries must restart the Google flow and use values from a new payment-credentials callback. Legacy Google Pay may re-send its stable wallet_id and device_id, but must request a fresh provisioning payload.

Not supported

	Why
Web / browser push provisioning	Adding a card to a wallet from a web page has materially different request and response shapes. It is deliberately out of scope for this contract rather than bolted on. Talk to your Imprint team if you need it.
Samsung Pay	Not currently supported. The `wallet` path parameter is designed so additional wallets can be added without a breaking change.

Security notes

Provisioning payloads are encrypted for the wallet provider. Your app cannot read the card number from them, and neither can anyone intercepting them.
Payloads are single-use. Do not log them, cache them, or persist them.
Ownership is enforced server-side. Imprint verifies that the payment_method_id belongs to the program your API key is scoped to. A payment method from another program returns 404, not 403, so the endpoint does not reveal whether an unknown ID exists.
Keep your API key server-side. You must call this endpoint through your app’s backend proxy — your Imprint API key must never ship inside your mobile app binary.

Getting Started

Applications

Cards

Transactions

Rewards

Account Linking

Webhook Event Notifications

API Keys

Servicing

Sandbox Testing

SDK Reference

Overview

What you need

How the flow works

The endpoint

Request body options

Apple Pay (`apple_pay`)

Request

Response

Google Wallet UPP (`google_wallet`)

Inputs before Google’s callback

Request

Response

Google Pay Legacy (`google_pay`)

Request

Response

Errors

Not supported

Security notes

​Overview

​What you need

​How the flow works

​The endpoint

​Request body options

​Apple Pay (apple_pay)

​Request

​Response

​Google Wallet UPP (google_wallet)

​Inputs before Google’s callback

​Request

​Response

​Google Pay Legacy (google_pay)

​Request

​Response

​Errors

​Not supported

​Security notes

Overview

What you need

How the flow works

The endpoint

Request body options

Apple Pay (`apple_pay`)

Request

Response

Google Wallet UPP (`google_wallet`)

Inputs before Google’s callback

Request

Response

Google Pay Legacy (`google_pay`)

Request

Response

Errors

Not supported

Security notes