Push provisioning (Android SDK)

Use it for: an Add to Wallet button on a card details screen that lets the cardholder add their Weavr-issued card to Apple Pay or Google Pay directly from your app, without retyping card details.

There are two methods for cardholders to add their cards to a digital wallet:

manual provisioning
push provisioning.

Our SDKs handle the implementation of push provisioning, so your cardholders can add a card to their wallet in a couple of taps.

Manual Provisioning

Cardholders manually input their card details into the device's digital wallet. Alternatively, they can use the device's camera to scan a physical card or a screen displaying a virtual card, allowing the details to be captured via Optical Character Recognition (OCR). Manual provisioning requires minimal effort on your part, but places greater responsibility on the cardholder to enter the details accurately.

Push Provisioning

Push provisioning, also known as "in-app provisioning," lets cardholders add their cards to a digital wallet without leaving your app. They tap an "Add to Wallet" button and the card is provisioned in place, with no card details to retype.

Certification requirements

Once integrated, you need certification from Google Pay and/or Apple Pay.

For Apple Pay, this includes lab certification through an Apple-affiliated test center. There are also specific launch conditions to consider, such as a minimum 30-day gap between launching Apple Pay and Google Pay. See our Apple Pay compliance overview for the app architectures Apple recognizes and what each path requires of your integration.

For Google Pay, a launch process must be followed. This includes a UX/branding review, allow-listing your app, and field testing payments. Details are available from the Google Developers site.

Achieving certification

The Weavr Support team guides you through the specific requirements to achieve certification for both Google Pay and Apple Pay.

How Push Provisioning works

Push provisioning lets a card assignee add their card to a digital wallet directly from your app. Here's how it works:

User initiates the process. The card assignee taps the Add to Wallet button in your app. This triggers the push provisioning workflow.
Card tokenization. The card details are securely tokenized by Weavr. Tokenization replaces sensitive card information with a unique identifier (token) that can be safely used for transactions by the different parties involved.
Secure communication with the wallet provider. The tokenized card data is sent to the respective digital wallet provider (Apple Pay or Google Pay) through a secure channel.
Verification and approval. The wallet provider verifies the tokenized data with the card issuer or network. This step ensures the card is valid and authorized to be provisioned.
Card added to wallet. On successful verification, the card is added to the digital wallet, ready for use in contactless payments (by tapping the phone), or online transactions.

Prerequisites

Before you can call the SDK to provision a card, you need:

Your app allow-listed by Token Service Providers (TSPs) and digital wallets.
An access token identifying the user.
The card data.
The card artwork, which must comply with the following rules:
- Be either vector PDF (recommended) or a raster PNG file.
- Have a resolution of 1536 x 969.
- Be no larger than 4 MB.
- Have square (not rounded) corners.
- Exclude elements that are only relevant for physical cards (such as the card number, hologram, or chip).
- Be in landscape orientation.
- Optionally include a contactless indicator (NFC payments).
The status of the card within the digital wallet.

Getting approval from Apple and Google

Both Apple Pay and Google Pay, as well as Token Service Providers, set their own standards and procedures to guarantee your app isn't impersonated by malicious actors during the provisioning flow. You need to provide details for your app as evidence that you meet these requirements.

For Apple Pay specifically, our Apple Pay compliance guides describe the certification paths Apple recognizes - including the primary mobile app (recommended) and primary + companion app routes - and the requirements for each.

Our support team can help you navigate the procedures required to get your app certified. Contact [email protected] for assistance.

Authenticating your user

To provision a card from your app, you must have a valid access token for a logged-in user.

You can obtain an access token via POST /login_with_password in conjunction with the appropriate mobile login component or biometric authentication component for your platform.

Fetching card data

Next, fetch the card data to provision it in your front-end. Use the GET /managed_cards endpoint.

note

Confirm the card can be provisioned before showing the Add to Wallet button:

state.state is ACTIVE. Cards in NOT_ENABLED, BLOCKED, or DESTROYED state can't be provisioned.
digitalWallets.pushProvisioningEnabled and digitalWallets.walletsEnabled are both true.
digitalWallets.artworkReference has an approved code (for example, XXX001). Coordinate approval with our support team.

For the full set of states and configuration that block provisioning, see Card states that block provisioning.

From the data received, pass these properties to the SDK during the provisioning flow:

Card id
Card friendlyName as the card description
cardNumberLastFour as the card's last four digits
nameOnCard as the card holder's name

Checking card status

Before showing the Add to Wallet button, confirm two things:

The card itself is in a valid state for provisioning (Weavr API).
The card isn't already in the wallet on the device (SDK).

If either check fails, hide the Add to Wallet button and display an explanatory message. The SDK doesn't always surface a clear error when provisioning fails for state-related reasons - the button can appear unresponsive, leaving cardholders without feedback.

Card states that block provisioning

A card can be provisioned only when all of the following are true. A single failing condition causes provisioning to fail.

Property	Required value	Notes
`state.state`	`ACTIVE`	Cards in `NOT_ENABLED`, `BLOCKED`, or `DESTROYED` state can't be provisioned. See virtual cards for the full state model.
`digitalWallets.pushProvisioningEnabled`	`true`	Set on the card itself, not just the programme. Returns `false` if missing or never configured.
`digitalWallets.walletsEnabled`	`true`	Covers both push and manual provisioning.
`digitalWallets.artworkReference`	Approved code	For example, `XXX001`. Coordinate approval with our support team.

Behind the scenes, our backend forwards the provisioning request to the card processor, which runs its own state check. For Mastercard cards on Thredd, a card that is BLOCKED at Weavr typically has its external status set to Suspended and card status set to 62 (Restricted card) - see Thredd's card status codes. The processor rejects the request even though our API accepted it.

Fraud-block flows. If your platform blocks cards as part of a fraud-prevention flow, unblock the card before the cardholder taps the Add to Wallet button. Unblocking after the SDK has already initiated the provisioning request is too late - the request has already failed at the processor.

Missing digital wallet configuration. If you create a managed card without specifying the digitalWallets field, the API populates it from your programme's defaults. If those defaults don't match the scheme being issued - for example, only a Visa artwork reference is configured but you're issuing Mastercard, or vice versa - the card may be created with pushProvisioningEnabled: false and walletsEnabled: false. The SDK then returns:

providerSelectionError (cantFindProviderToUse): No providers were received from the API

To avoid this, either set pushProvisioningEnabled, walletsEnabled, and artworkReference explicitly on POST /managed_cards, or confirm with our support team that your programme's defaults cover every scheme you're issuing.

Already provisioned in the wallet

Use getCardStatus to check whether the card is already provisioned in the wallet on the current device. If it is, hide the Add to Wallet button and display a message that the card has already been added.

tip

The brand guidelines for Apple and Google wallets are strict. Follow the platform documentation closely to avoid app rejection during reviews.

Each platform also has its own nuances regarding card states - refer to the platform documentation for details.

Triggering the provisioning process

Once you have the relevant data and have checked the card can be provisioned, display the Add to Wallet button to the user.

On interaction, the button triggers the provisioning flow:

Provisioning and the Weavr API

Two Weavr API endpoints (related to cards) accept information required for push provisioning:

Method	Endpoint	Description
POST	`/multi/managed_cards`	Create a managed card
PATCH	`/multi/managed_cards/{id}`	Update a managed card

Within these endpoints, the following optional parameters must be set for a card to work with Apple Pay and Google Pay:

Attribute	Description
`pushProvisioningEnabled`	Boolean. Set to `true` if the card should be turned on for push provisioning.
`walletsEnabled`	Boolean. Indicates whether the card is turned on for tokenization in a digital wallet. Applies to both push and manual provisioning.
`artworkReference`	Weavr-provided reference that identifies the artwork to be shown on the mobile device. Approved values are network-specific (Visa or Mastercard) and configured per programme - request the codes for your programme from our support team.

Always send digitalWallets on card creation

Send the digitalWallets block on every POST /managed_cards request - including all three fields (pushProvisioningEnabled, walletsEnabled, artworkReference).

If you omit the block, the API populates it from your programme's defaults. When those defaults don't match the scheme being issued (for example, only a Visa artwork reference is configured but you're issuing Mastercard), the card is created with pushProvisioningEnabled: false and walletsEnabled: false - and there is no API to flip those flags back on after creation. Such cards must be reissued or remediated by support, and any cardholder-facing Add to Wallet button on them is silently inert.

Example: create a card with digital wallet support

POST /multi/managed_cards
{
  "profileId": "115079696398155807",
  "friendlyName": "Demo card",
  "ownerId": {
    "id": "115134292391559225",
    "type": "CORPORATE"
  },
  "currency": "EUR",
  "mode": "PREPAID_MODE",
  "cardBrand": "MASTERCARD",
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "YOUR_PROGRAMME_MASTERCARD_REF"
  }
}

Replace YOUR_PROGRAMME_MASTERCARD_REF (or ..._VISA_REF) with the artwork code our support team has approved for your programme on that network.

Pre-flight checklist

Run through these checks before you invoke the provisioning SDK on the cardholder's device. A single failing condition causes provisioning to fail - and several modes fail silently, so the SDK call returns without a clear error:

Card state - state.state is ACTIVE. Cards that are BLOCKED, DESTROYED, or NOT_ACTIVATED_BY_CARDHOLDER cannot be provisioned. A card that is BLOCKED at Weavr is rejected by the downstream card processor (e.g. Thredd), but Weavr accepts the request - so nothing visible happens from your app's perspective. Activate the card before the cardholder taps Add to Wallet.
digitalWallets.pushProvisioningEnabled is true.
digitalWallets.walletsEnabled is true.
digitalWallets.artworkReference is set, and the value is approved for the network of the card being provisioned (Visa or Mastercard) on your programme.
Already provisioned check - the SDK's getCardStatus does not report the card as alreadyAdded / PROVISIONED for this device.

If any of the first four are false on an existing card, the card cannot be remediated by API - contact our support team.

Troubleshooting

The three failure modes most commonly seen in production:

Symptom	Likely cause	Fix
Add to Wallet button does nothing for the user	The card is `BLOCKED` (or otherwise not `ACTIVE`) at Weavr. Weavr accepts the provisioning request, but the card processor rejects it - no clear error reaches the SDK or your app.	Activate the card before the cardholder taps the button. If you block cards as part of a fraud flow, unblock first.
Newly created cards never offer push provisioning	The `digitalWallets` block was omitted on `POST /managed_cards`, so the card was created with `pushProvisioningEnabled` and `walletsEnabled` set to `false`. The flags can't be turned on after creation.	Always send the `digitalWallets` block (see preceding example). Affected cards must be reissued.
`providerSelectionError (cantFindProviderToUse)` from the SDK	The card was created with no providers - the artwork reference doesn't match the card's network, or `walletsEnabled` is `false`.	Set `pushProvisioningEnabled`, `walletsEnabled`, and a network-correct `artworkReference` explicitly on card creation, or confirm with our support team that your programme's defaults cover every scheme you issue.

Next steps

Follow the Set up guide to integrate the Android Push Provisioning SDK.

Manual Provisioning​

Push Provisioning​

Certification requirements​

How Push Provisioning works​

Prerequisites​

Getting approval from Apple and Google​

Authenticating your user​

Fetching card data​

Checking card status​

Card states that block provisioning​

Already provisioned in the wallet​

Triggering the provisioning process​

Provisioning and the Weavr API​

Example: create a card with digital wallet support​

Pre-flight checklist​

Troubleshooting​

Next steps​