Open Loop Cards Overview

Prerequisites: a Bearer access token carrying the CREATE_SHARE_LINK scope. Basic auth is rejected. Contact your sales rep to enable access. See Authentication.

What “hosted” / “open-loop” means. A hosted link points to a Fluz-hosted activation page. Open-loop means the resulting virtual card is a network card (Visa/Mastercard-style) that can be spent at many merchants, subject to your program’s rules — not a single-brand closed-loop gift card.

How it works

You generate links

Call generateVCShareLinks with the offer, card limit, quantity, funding source, and a delivery method. Each link represents one card with its own limit, funded from the spend account you specify.

Fluz creates a share request per link

Each link maps to one share request (PENDING) and one hosted URL.

The link is delivered

With GENERATE_URL you get the URLs back to distribute yourself. With EMAIL or PHONE_NUMBER, Fluz delivers a link to each recipient for you.

The recipient activates and claims the card

The recipient opens the link and verifies their phone number with a one-time code — no app download, no password. The card limit is drawn against your spend account at claim time, not when the link is generated. The card isn’t auto-revealed on claim; revealing it prompts the recipient to enter their PIN, or create one if they haven’t set one yet. See Recipient Experience for the full walkthrough.

The recipient becomes an authorized user of that virtual card object only — they do not gain access to your account, balances, or any other cards. Send cards flow diagram

Availability & scope

Capability	Status
Single-load virtual cards	✅ Supported
Single-use virtual cards	✅ Supported
Reloadable cards	❌ Not supported
Generate links via API	✅ Supported
Generate links via CSV Import	❌ Coming Soon
Hosted gift-card links	❌ Not in scope (virtual cards only)

The card share-link object type is VIRTUAL_CARD and the card type is SINGLE_LOAD.

Gift cards: Despite the “virtual cards and gift cards” framing of the broader initiative, there is no hosted gift-card claim flow today. Gift-card balances appear in this area only as a potential funding source for hosted virtual cards (planned, not yet enabled). Document and build against virtual cards only.

Operation reference

There are three public operations, all gated by the CREATE_SHARE_LINK scope:

Operation	Type	Purpose
`generateVCShareLinks`	Mutation	Create one or more hosted virtual card links
`getVCShareLinks`	Query	List/inspect previously generated links
`deactivateVCShareLinks`	Mutation	Deactivate (expire) links you generated

All Send Cards operations are on the Fluz GraphQL API at POST https://<your-fluz-api-host>/api/v1/graphql with an Authorization: Bearer <access_token> header. The token must carry the CREATE_SHARE_LINK scope — without it, every operation returns “Missing permissions! Please contact your sales rep to get access to generate VC share links.”

generateVCShareLinks

Creates quantity share requests and returns one hosted link per request.

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

Input fields

Field	Type	Required	Description
`cardLimit`	`Int!`	Yes	Spend limit (and load amount) for each card, in whole currency units. Must be a whole number ≥ the program minimum.
`offerId`	`String!`	Yes	UUID v4 of the merchant offer the card is tied to. The offer must be active and its merchant must be shareable.
`quantity`	`Int!`	Yes	Number of links to generate. One distinct hosted URL is created per unit.
`shareMethod`	`ShareMethodType!`	Yes	How recipients are identified and links are delivered: `GENERATE_URL`, `EMAIL`, `PHONE_NUMBER`, `EXISTING_USER`, or `REGISTER_USER`.
`userCashBalanceId`	`UUID`	Yes*	The spend account used to fund the cards. Marked optional in the schema but required in practice — omitting it fails validation.
`daysUntilExpiration`	`Int`	No	Days until the link expires. Minimum 1. Defaults to the program default (30 days) if omitted. This date also becomes the card’s lock/freeze date — see Expiration & freeze.
`recipientListEmail`	`[String]`	Conditional	Required and non-empty when `shareMethod = EMAIL`. Length must equal `quantity`. Must be empty otherwise.
`recipientListPhone`	`[String]`	Conditional	Required and non-empty when `shareMethod = PHONE_NUMBER`. Length must equal `quantity`. Must be empty otherwise.
`recipientUserIds`	`[UUID]`	Conditional	Known Fluz user IDs to bind as recipients when `shareMethod = EXISTING_USER`. Length must equal `quantity`. Mutually exclusive with `recipientRegistrations`.
`recipientRegistrations`	`[ShareLinkRecipientRegistrationInput]`	Conditional	Inline pre-register payloads when `shareMethod = REGISTER_USER` — Fluz creates or reuses a placeholder user (no seat) per entry before generating links. Length must equal `quantity`. Mutually exclusive with `recipientUserIds`.
`usePrepaymentBalance`	`Boolean`	No	Set whether to use your Prepayment Balance as an additional funding source. The default is false. More information about how this is used: How funding works.
`useRewardsBalance`	`Boolean`	No	Set whether to use your Fluz Rewards Balance as an additional funding source. The default is false. More information about how this is used: How funding works.

Funding source. userCashBalanceId (a spend account belonging to your, the sender’s, account) is the primary and required funding source. Optionally set usePrepaymentBalance and/or useRewardsBalance to true to let Fluz fall back to your prepayment or rewards balance if the spend account doesn’t cover the full amount at claim time. Bank accounts and bank cards are not supported as funding sources.

Recipient identification & delivery (`shareMethod`)

Value	Behavior	Recipient field	Card created
`GENERATE_URL`	Fluz returns the hosted URLs in the response. You distribute them yourself.	Both lists must be empty/omitted.	At claim
`EMAIL`	Fluz emails a link to each recipient.	`recipientListEmail` required; length must equal `quantity`.	At claim
`PHONE_NUMBER`	Fluz texts a link to each recipient.	`recipientListPhone` required; length must equal `quantity`.	At claim
`EXISTING_USER`	Link is bound to a known Fluz user from the start; only that user can claim it. Delivered via the contact channel(s) already on file for that user.	`recipientUserIds` required; length must equal `quantity`.	Immediately, at generation time
`REGISTER_USER`	Fluz creates or reuses a placeholder user per entry, then binds the link to that user, same as `EXISTING_USER`.	`recipientRegistrations` required; length must equal `quantity`.	Immediately, at generation time

EXISTING_USER and REGISTER_USER both create the virtual card as part of the generateVCShareLinks call, rather than deferring card creation to claim time. See Register & Send for the full EXISTING_USER flow, including how to register a recipient first with registerUser.

Validation rules

cardLimit must be a whole number and at least the program minimum.
offerId must be a valid UUID v4 for an active offer whose merchant is shareable.
quantity must be a whole number.
The recipient field matching shareMethod (recipientListEmail, recipientListPhone, recipientUserIds, or recipientRegistrations) must have length equal to quantity. Mismatches return a clear error and create no records.
recipientUserIds and recipientRegistrations are mutually exclusive with each other and with the delivery-list fields.
Each ID in recipientUserIds must be a valid, existing Fluz user.
userCashBalanceId is required and must be a valid UUID v4 owned by the sender’s account. usePrepaymentBalance and useRewardsBalance are optional fallback sources and may both be enabled alongside it.
Invalid card types or malformed inputs return clear errors and create no records.

Examples

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 3,
      "shareMethod": "GENERATE_URL",
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 2,
      "shareMethod": "EMAIL",
      "recipientListEmail": ["recipient1@example.com", "recipient2@example.com"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 2,
      "shareMethod": "PHONE_NUMBER",
      "recipientListPhone": ["+12125550101", "+12125550102"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

  {
    "input": {
      "cardLimit": 25,
      "offerId": "11111111-2222-3333-4444-555555555555",
      "daysUntilExpiration": 30,
      "quantity": 1,
      "shareMethod": "EXISTING_USER",
      "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
      "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    }
  }

For EXISTING_USER, register the recipient first (or use an existing user’s ID directly) — see Register & Send for the full walkthrough, including the registerUser call and response handling.

Response

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1",
        "https://fluz.app/virtual-prepaid-card/9b2d...77",
        "https://fluz.app/virtual-prepaid-card/0c41...e3"
      ]
    }
  }
}

shareLinks is an array of hosted URLs, one per quantity, each of the form https://fluz.app/virtual-prepaid-card/{share_request_id}.

The response returns only the URLs. To retrieve the batch ID and display IDs for the links you just created (needed for listing and deactivation), use getVCShareLinks filtered by status.

getVCShareLinks

Lists previously generated share links so you can inspect status, recipients, expiration, and the issued card.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    senderAppId
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    recipientPhone
    recipientEmail
    linkExpirationDate
    virtualCardId
    linkUrl
    shareRequestDetails {
      cardLimit
      offerId
      daysUntilExpiration
      quantity
      shareMethod
      recipientListEmail
      recipientListPhone
      userCashBalanceId
    }
  }
}

Input fields

Field	Type	Description
`shareObjectStatuses`	`[ShareObjectStatus]`	Filter by status: `PENDING`, `ISSUED`, `USED`, `EXPIRED`.
`shareRequestBatchIds`	`[String]`	Return only links in these batches.
`shareRequestDisplayIds`	`[String]`	Return only the links with these display IDs.

Recommended flow. On the first call, filter by shareObjectStatuses only. The response gives you shareRequestBatchId and shareRequestDisplayId values; use those to filter precisely on subsequent calls (and to deactivate).

Response fields (`GeneratedShareLink`)

Field	Type	Description
`senderAppId`	`String`	The app/developer application that generated the link.
`shareRequestBatchId`	`String`	Batch identifier shared by all links generated in one call.
`shareRequestDisplayId`	`String`	Human-friendly per-link identifier.
`shareObjectStatus`	`ShareObjectStatus`	`PENDING`, `ISSUED`, `USED`, or `EXPIRED`.
`recipientEmail`	`String`	Recipient email, if delivered by email.
`recipientPhone`	`String`	Recipient phone, if delivered by SMS.
`linkExpirationDate`	`DateTime`	When the link expires / card freezes.
`virtualCardId`	`String`	The issued virtual card ID, once claimed.
`linkUrl`	`String`	The hosted URL for the link.
`shareRequestDetails`	`ShareRequestDetails`	The original configuration (card limit, offer, quantity, delivery, funding).

Examples

  { "input": { "shareObjectStatuses": ["PENDING", "ISSUED"] } }

  { "input": { "shareRequestBatchIds": ["ABC123", "XYZ789"] } }

  { "input": { "shareRequestDisplayIds": ["SR-000001", "SR-000002"] } }

deactivateVCShareLinks

Deactivates (expires) links you generated — for example, if a batch was sent in error or you need to revoke unclaimed links. Deactivating a link sets it to EXPIRED; an unclaimed link can no longer be claimed.

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

Input fields

Field	Type	Description
`shareRequestBatchIds`	`[String]`	Deactivate every link in these batches.
`shareRequestDisplayIds`	`[String]`	Deactivate only the links with these display IDs.

Get the batch IDs from getVCShareLinks.

{ "input": { "shareRequestBatchIds": ["ABC123"] } }

Returns a human-readable confirmation string, e.g. "3 share requests successfully deactivated!".

If a recipient has already claimed a link (status ISSUED/USED), deactivating the link does not claw back the issued card. To stop spend on an already-issued card, use the relevant card lifecycle/freeze controls.

Expiration & freeze

The link’s expiration date does double duty:

Link expiration — after this date, an unclaimed link can no longer be claimed.
Card freeze / lock date — for an issued card, this is the lock date (end of that day). After it, the card is frozen and cannot be spent.
Card expiry is aligned to the end of the month of the freeze date (e.g., a freeze date of 6/15/2026 yields a card expiry of 6/30/2026).

Set the window with daysUntilExpiration at generation time. If omitted, the program default (30 days) is used. This date is shown to the recipient (typically as a “Valid until” date) — see Recipient Experience.

Status & error reference

Status	Meaning
`PENDING`	Link generated, not yet claimed.
`ISSUED`	Recipient claimed the link; a virtual card was issued.
`USED`	The issued card has been used.
`EXPIRED`	Link expired or was deactivated; no longer claimable.

For the states a recipient sees when a link is expired, revoked, or already claimed, see Recipient-facing link errors.

Common API errors

Cause	Result
Missing/invalid Bearer token or missing `CREATE_SHARE_LINK` scope	Request rejected (unauthorized).
Recipient field (`recipientListEmail`, `recipientListPhone`, `recipientUserIds`, or `recipientRegistrations`) length ≠ `quantity`	Clear validation error; no records created.
`recipientUserIds` references a non-existent Fluz user	Validation error; no records created.
Inactive offer, non-shareable merchant, or invalid `offerId`	Validation error; no records created.
Missing/invalid `userCashBalanceId`	Validation error; no records created.

Notes & limitations

Returned URL is the hosted destination, not a short link. Internally, links are also wrapped by a short-link provider, but the API returns the canonical hosted URL (/virtual-prepaid-card/{share_request_id}). Distribute the URL exactly as returned.
userCashBalanceId is effectively required even though the schema marks it optional.
Hidden/internal fields are not part of this API. Object type and card type are fixed (VIRTUAL_CARD / SINGLE_LOAD). Bank account and bank card funding are not yet enabled; do not send them. usePrepaymentBalance and useRewardsBalance are the only supported additional funding sources today.
Gift-card hosted links are not supported. This API is for virtual cards only.

Next steps

Recipient experience

What your recipients see when they open a hosted link, and the rules that govern their card.

Register & Send

Use EXISTING_USER to register a recipient and create their card up front, instead of at claim.

Create a bulk order

Issue many cards at once for programmatic distribution.

​How it works

​Availability & scope

​Operation reference

​generateVCShareLinks

​Input fields

​Recipient identification & delivery (shareMethod)

​Validation rules

​Examples

​Response

​getVCShareLinks

​Input fields

​Response fields (GeneratedShareLink)

​Examples

​deactivateVCShareLinks

​Input fields

​Expiration & freeze

​Status & error reference

​Share object statuses

​Common API errors

​Notes & limitations

​Next steps

Recipient experience

Register & Send

Create a bulk order

How it works

Availability & scope

Operation reference

generateVCShareLinks

Input fields

Recipient identification & delivery (`shareMethod`)

Validation rules

Examples

Response

getVCShareLinks

Input fields

Response fields (`GeneratedShareLink`)

Examples

deactivateVCShareLinks

Input fields

Expiration & freeze

Status & error reference

Share object statuses

Common API errors

Notes & limitations

Next steps