Digital Wallet Push Provisioning

Use the getCardProvisioningUrl query to mint a short-lived URL that — when opened on your end-user’s phone — launches Fluz on the device and adds a specific virtual card to Apple Pay (iOS) or Google Pay (Android). You can deliver the URL however you like: a QR code, an SMS, an email, or an in-app button. Fluz handles the wallet-provisioning flow from there.

When to use it

Anywhere you would normally hand the user a virtual card and want them to be able to tap it in their phone’s wallet without typing the card number. Typical flows:

After creating a card offer for the user, present a QR code on screen.
Text or email the URL to the cardholder.
Embed an “Add to Apple Pay / Google Pay” button in your own mobile app.

Prerequisites: an OAuth access token for the end-user that includes the CREATE_VIRTUALCARD scope, and something to select the card with. Either the virtualCardId returned by createVirtualCard, or an offerId accessible to the account. If the offer hasn’t been redeemed into a card yet, one is created as part of the provisioning flow.

Basic-auth (client_id / client_secret) is not accepted on this query — it must be a user-context bearer token.

The query

By card (recommended):

query ProvisionCard($virtualCardId: String!) {
  getCardProvisioningUrl(input: { virtualCardId: $virtualCardId, platform: IOS }) {
    url
    expiresAt
  }
}

By offer, when the account holds at most one active card on it:

query ProvisionCard($offerId: String!) {
  getCardProvisioningUrl(input: { offerId: $offerId, platform: IOS }) {
    url
    expiresAt
  }
}

Input

Supply exactly one of virtualCardId or offerId.

Field	Type	Required	Description
`virtualCardId`	`String` (UUIDv4)	one of	The card to provision, as returned by `createVirtualCard`. Must belong to the caller’s account and be `ACTIVE`. Prefer this: it names the card unambiguously.
`offerId`	`String` (UUIDv4)	one of	The virtual-card offer to provision. Must be active, tokenization-eligible, and accessible to the user’s account. Only resolves while the account holds at most one active card on that offer.
`platform`	`ProvisioningPlatform`	no	Hint about where the user will open the URL. Defaults to `IOS`. See below — this does not lock the URL to one platform.

An offer can back many cards on the same account. Once there is more than one active card on an offer, offerId no longer identifies a single card and the query fails with VirtualCard.AMBIGUOUS_CARD_SELECTION rather than picking one for you. If you issue more than one card per offer, use virtualCardId.

`ProvisioningPlatform`

The returned URL is platform-aware: iOS users automatically get the App Clip experience, Android users automatically get the Fluz app deep link. The platform value only affects what happens when the URL is opened somewhere other than an iOS or Android device (e.g. a desktop browser).

Value	Desktop / unknown-device fallback
`IOS` (default)	Apple App Clip launcher
`ANDROID`	Fluz Android deep link
`OTHER`	Fluz web app

Pick the value that best matches where you expect the URL to be opened. If in doubt, leave it as IOS.

Output

Field	Type	Description
`url`	`String!`	The short URL to deliver to the user. Targets exactly one card.
`expiresAt`	`String!`	ISO-8601 timestamp. The URL stops working at this time (≈ 5 minutes after creation).

Example

Request

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ virtualCardId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "11111111-2222-4333-8444-555555555555" }
  }'

Or select by offer instead:

curl -X POST https://transactional-graph.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <user_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id:String!){ getCardProvisioningUrl(input:{ offerId:$id, platform:IOS }){ url expiresAt } }",
    "variables": { "id": "66666666-7777-4888-9999-000000000000" }
  }'

Response

{
  "data": {
    "getCardProvisioningUrl": {
      "url": "https://fluz.app.link/abc123XYZ",
      "expiresAt": "2026-05-26T17:42:11.000Z"
    }
  }
}

How to deliver the URL

The URL is opaque and carries no card number, but it is a bearer secret: whoever opens it can add that card to their wallet. Deliver it to the cardholder over a channel you trust. Common patterns:

QR code on a screen — generate a QR from url and show it; the user scans with their phone camera.
SMS / email — send the link directly to the user’s phone or inbox.
In-app deep link — wire a button in your mobile app that opens url.

Whatever the delivery channel, the user must open the URL on a mobile device — that’s where the wallet provisioning happens.

Lifetime & re-issuing

Each call returns a fresh URL targeting one card.
The URL is valid until expiresAt (≈ 5 minutes).
Opening the URL does not immediately invalidate it. It stays redeemable for a short grace window after first use, so treat it as a bearer secret: deliver it over a private channel, and don’t log or cache it.
If a user doesn’t act in time, simply call getCardProvisioningUrl again to mint a new one. There is no separate “refresh” endpoint.
To provision several cards, call the query once per card with each card’s virtualCardId.

Error handling

All errors come back in the standard Fluz GraphQL error shape, with the error name in extensions.code.

Code	What it means	What to do
`Arguments.INVALID`	The id isn’t a valid UUID, or you supplied both selectors or neither.	Send exactly one of `virtualCardId` or `offerId`.
`VirtualCard.CARD_NOT_FOUND`	No such card on the caller’s account.	Confirm the `virtualCardId` and that it belongs to this account.
`VirtualCard.CARD_NOT_ACTIVE`	The card exists but isn’t `ACTIVE`.	Don’t retry; the card can’t be added to a wallet in this state.
`VirtualCard.AMBIGUOUS_CARD_SELECTION`	The account holds more than one active card on the `offerId` you sent.	Retry with `virtualCardId`.
`VirtualCard.OFFER_NOT_FOUND`	The card’s offer doesn’t exist or is inactive.	Confirm the offer id; create a new offer if needed.
`VirtualCard.OFFER_NOT_ACCESSIBLE`	The user’s account isn’t eligible for this offer (campaign access).	Surface a generic “not available” message.
`VirtualCard.OFFER_NOT_TOKENIZATION_ELIGIBLE`	The offer’s card program doesn’t support wallet provisioning.	Don’t offer “Add to wallet” for this card program.
`Auth.USER_REVOKED_DEVELOPER_ACCESS`	The user has revoked OAuth access to your app.	Send the user back through OAuth consent.
`Auth.INVALID_SCOPE`	The token doesn’t have `CREATE_VIRTUALCARD`.	Request the scope during OAuth.
`Generic.EXTERNAL_SERVICE_ERROR`	Transient downstream issue.	Retry — the call is safe to repeat.

FAQ

Does the URL contain the card number?

No. The URL carries a short-lived opaque lookup id only. Credentials are exchanged securely on the device once the user opens the link.

Can the same URL be reused?

Treat it as single-use: generate a new one each time you need to surface the flow. Opening the link doesn’t invalidate it instantly, so it stays redeemable for a short grace window. Deliver it privately and don’t log or cache it.

Can one URL add several cards?

No. Each URL targets exactly one card. Call the query once per card, passing that card’s virtualCardId.

What if the user is on desktop?

They’ll land on the fallback you selected with platform (App Clip launcher, Android deep link, or Fluz web app). For the wallet provisioning itself to work, they need to end up opening the URL on a mobile device.

Do I need to do anything different for iOS vs. Android?

No. The same URL works for both — Fluz routes per-device automatically.

Next steps

Send cards

Distribute virtual cards to recipients by email, SMS, or share link.

Set a virtual card PIN

Set a PIN on eligible cards before in-person, PIN-prompted transactions.

​When to use it

​The query

​Input

​ProvisioningPlatform

​Output

​Example

​Request

​Response

​How to deliver the URL

​Lifetime & re-issuing

​Error handling

​FAQ

​Next steps

Send cards

Set a virtual card PIN

When to use it

The query

Input

`ProvisioningPlatform`

Output

Example

Request

Response

How to deliver the URL

Lifetime & re-issuing

Error handling

FAQ

Next steps