Generate Share Links

Generate hosted virtual card links ("open-loop" Send Cards) from your platform. You call one API to mint one or more links, then deliver those links to recipients however you like — by email, by SMS, or by handing back the raw URLs to embed in your own flows. When a recipient opens the link, they land on a Fluz-hosted page, verify themselves, and claim a single-load virtual card funded from your account.

📘

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.

🚧

Pre-requisites

Before using this mutation, review Share Virtual Cards for feature access requirements. Your application must be granted the CREATE_SHARE_LINK scope, and your account must be enabled for sending virtual cards. Contact your sales rep to get access. Reference: Application Scopes.

How it works

1. You generate links. Each link represents one card with its own limit, funded from the spend account you specify. Cards are configured with a card limit, an offer, and an optional expiration window.
2. The link is delivered. Fluz sends it via SMS or email on your behalf, or returns the raw URL for you to deliver through your own system (GENERATE_URL).
3. The recipient activates. The recipient opens the link, verifies their phone number with a one-time code, and sets a card PIN. No app download and no password — activation is anchored to the recipient's phone number, and every future card sent to that number activates the same way.
4. The card is funded at claim time. The card limit is drawn against your spend account when the recipient claims the card — not when the link is generated. The recipient can then view card details, spend online, and add the card to Apple Pay or Google Pay in one tap.

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.

See the recipient experience in action: desktop flow · mobile flow.

Availability & scope

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.

How it works

1. You generate links. Call generateVCShareLinks with the offer, card limit, quantity, funding source, and a delivery method.
2. Fluz creates a share request per link. Each link maps to one share request (PENDING) and one hosted URL.
3. Delivery happens. 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.
4. The recipient claims the card. They open the hosted page, authenticate, and a single-load virtual card is issued to them, funded from your account.

Authentication

All Send Cards operations are on the Fluz GraphQL API.

• Endpoint: POST https://<your-fluz-api-host>/api/v1/graphql
• Header: Authorization: Bearer <access_token>
• Required scope: CREATE_SHARE_LINK

You must use a Bearer access token (an OAuth/developer-application access token). Basic auth is rejected for these operations. The token must carry the CREATE_SHARE_LINK scope, or the request is rejected before it runs.

// When minting the sender's access token, request the scope:
{
  "scopes": ["CREATE_SHARE_LINK"]
}

📘

Account access

Your account must also have Send Cards enabled (the send_virtual_cards_enabled campaign flag). Without it, every operation returns a permissions error: "Missing permissions! Please contact your sales rep to get access to generate VC share links." If you see this, contact your Fluz representative.

Operation reference

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

generateVCShareLinks

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

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

Input fields

📘

Funding source

Today, the only supported funding source is a spend account (userCashBalanceId), and it must belong to your (the sender's) account. Cards are funded from the sender's account. Additional funding sources (bank account, bank card, prepayment/rewards balance) are not yet available.

Delivery methods (shareMethod)

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.
• When delivering by EMAIL or PHONE_NUMBER, the matching recipient list length must equal quantity. Mismatches return a clear error and create no records.
• Only one funding source may be supplied. userCashBalanceId must be a valid UUID v4 owned by the sender's account.
• Invalid card types or malformed inputs return clear errors and create no records.

Examples

Generate 3 raw URLs (no recipients):

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

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

Email a link to each of two recipients:

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 2,
    "shareMethod": "EMAIL",
    "recipientListEmail": ["[email protected]", "[email protected]"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Text a link to each of two recipients:

{
  "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"
  }
}

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 URL has the form:

https://fluz.app/virtual-prepaid-card/{share_request_id}

📘

Tracking what you generated

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

💡

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)

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

Get the batch IDs from getVCShareLinks.

Example

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

Response

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.

The recipient experience

When a recipient opens a hosted link (https://fluz.app/virtual-prepaid-card/{share_request_id}):

🖼️

Screenshot placeholder — hosted "Activate your card" landing page (from fluz.app/us/open-loop).

1. Landing & sign-in. The recipient sees the activation page branded with the sender's business. They sign in through the Fluz auth portal (new recipients onboard here).
2. Two-factor authentication. On initial load, existing users are taken to the 2FA screen. 2FA is required before the card can be viewed or claimed.
3. Billing address (if needed). If the recipient has no billing address on file, they're prompted to add one. Billing address is required for online purchases.
4. PIN (if not yet issued). Before the card is issued, the recipient sets a PIN.
5. Card issued & claimed. A single-load virtual card is created and assigned to the recipient, funded from the sender's account, with a lock date equal to the link's expiration date.
6. Use the card. Once claimed, the recipient can see card details, transactions, and (where supported) add the card to a mobile wallet.

🖼️

Screenshot placeholder — claimed virtual card details view (from fluz.app/us/open-loop).

📘

Already claimed?

If the same user opens a link they already claimed, they see their card details. If a different user opens a link that someone else already claimed, they're shown an access-denied state after 2FA.

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).

Program rules to communicate to recipients

These are program-level rules for hosted (open-loop) virtual cards. Confirm the exact values for your program with your Fluz representative — several are partner-negotiated.

Customer support for recipients: 1-888-360-6660 · [email protected]

📘

The full partner-facing reference (terminology, recipient walkthrough with screenshots, funding instructions, restricted categories, and support) lives in the Partner Guide — Hosted URL Virtual Cards. Ask your Fluz contact for the latest copy for your program.

Status & error reference

Share object statuses

Recipient-facing link errors

Common API errors

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) and other funding-source fields are not yet enabled; do not send them.
• Gift-card hosted links are not supported. This API is for virtual cards only.