Send a Card to Someone

This Quickstart walks through the complete Send Cards lifecycle. You’ll create a staging application, mint a scoped Bearer token, choose a card program, retrieve a funded spend account, generate hosted virtual card links, experience the recipient activation flow, verify issuance, then deactivate an unused link. By the end you’ll have successfully completed every public Send Cards operation:

generateVCShareLinks
getVCShareLinks
deactivateVCShareLinks

—all in the sandbox, where no real customer funds move.

Prerequisites

A Fluz account — you’ll create staging API credentials and mint a scoped access token in Steps 1–2 below.
Requests go to the sandbox GraphQL endpoint. Hosted recipient links use the standard Fluz activation experience, but all API operations use your staging environment.
Your account must have Send Cards enabled (send_virtual_cards_enabled) or every Send Cards operation returns a permissions error.
This Quickstart uses a funded Spend Account as the funding source. Cards are funded when claimed, not when links are generated.

Before you begin

Except for minting your token (Step 2), every request in this guide is sent to the Fluz GraphQL API using your Bearer access token.

POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>
Content-Type: application/json

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "query":"query { getVirtualCardOffers { offerId programName rewardValue } }"
  }'

Every GraphQL operation below uses this endpoint and your Bearer token. The only exception is Step 2, which exchanges your application credentials for an access token through the OAuth service.

The full flow

Create a staging application

Create a Fluz account, then open the Developer Console and create a Staging application.When your application is created you’ll receive:

clientId
clientSecret

Copy both values somewhere safe. Your clientSecret is only shown once.If you haven’t already created a staging application, see Prepare your accounts.

Exchange your credentials for a scoped Bearer token

Send your application credentials to the OAuth service to generate a short-lived user access token.This token authorizes every Send Cards operation that follows.

curl -X POST https://oauth-service.fluzapp.com/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query":"mutation ($clientId:String!,$clientSecret:String!,$scopes:[Scope!]!){generateUserAccessToken(clientId:$clientId,clientSecret:$clientSecret,scopes:$scopes){accessToken expiresIn scopes}}",
    "variables":{
      "clientId":"<APPLICATION_CLIENT_ID>",
      "clientSecret":"<APPLICATION_CLIENT_SECRET>",
      "scopes":[
        "CREATE_SHARE_LINK",
        "LIST_PAYMENT"
      ]
    }
}'

{
  "data": {
    "generateUserAccessToken": {
      "accessToken": "eyJhbGciOi...",
      "expiresIn": 3600,
      "scopes": [
        "CREATE_SHARE_LINK",
        "LIST_PAYMENT"
      ]
    }
  }
}

Save the returned accessToken.You’ll use it as:

Authorization: Bearer <YOUR_USER_ACCESS_TOKEN>

for every remaining request.

CREATE_SHARE_LINK authorizes every Send Cards operation.This Quickstart also requests LIST_PAYMENT so you can retrieve the Spend Account that funds your hosted cards.

Never expose your clientSecret inside a browser or mobile application.Generate Bearer tokens server-side and forward only the access token to your client.

Retrieve a funded Spend Account

Hosted virtual cards are funded from one of your Spend Accounts.Unlike regular virtual cards, no funds are reserved when the link is generated.Instead, the selected Spend Account is charged only when the recipient successfully claims the card.Retrieve your available Spend Accounts.

query GetSpendAccounts {
  getSpendAccounts {
    userCashBalanceId
    nickname
    availableBalance
    currency
  }
}

{
  "data": {
    "getSpendAccounts": [
      {
        "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "nickname": "Primary Spend Account",
        "availableBalance": 5000,
        "currency": "USD"
      }
    ]
  }
}

Save the userCashBalanceId.You’ll supply this value when generating your hosted card links.

The selected Spend Account must belong to your account and must contain sufficient funds when the recipient claims the card. If there isn’t enough available balance at claim time, card issuance fails.

Choose the card program

Every hosted card is issued against a virtual card offer.The offer determines the issuing program, available rewards, and the limits that apply to every generated card.Retrieve the offers available to your account.

query GetVirtualCardOffers {
  getVirtualCardOffers {
    offerId
    programName
    rewardValue
    programLimits {
      dailyLimit
      weeklyLimit
      monthlyLimit
    }
  }
}

{
  "data": {
    "getVirtualCardOffers": [
      {
        "offerId": "11111111-2222-3333-4444-555555555555",
        "programName": "Virtual Card",
        "rewardValue": "1.5%",
        "programLimits": {
          "dailyLimit": 500,
          "weeklyLimit": 2000,
          "monthlyLimit": 5000
        }
      }
    ]
  }
}

Save the offerId for the program you’d like to issue against.

The selected offer must be:

active
share-enabled

If generation fails because the offer isn’t eligible for Send Cards, confirm with your Fluz representative which offers are enabled for hosted sharing.

Generate two hosted card links

You’re ready to create hosted Send Card links.Each generated link represents one future virtual card.At this stage:

No card has been issued.
No funds have been withdrawn.
Each link begins in the PENDING state.

The selected Spend Account is charged only when a recipient claims a link.For this Quickstart we’ll generate two links:

Link A — you’ll claim this as the recipient.
Link B — you’ll leave unclaimed so it can later be revoked.

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

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "daysUntilExpiration": 14,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8ac...c1",
        "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      ]
    }
  }
}

The response returns one hosted activation URL for every generated card.Save both URLs.We’ll refer to them as:

Link A
Link B

throughout the remainder of this Quickstart.

Understanding the generation settings

cardLimit

Int

required

The amount loaded onto each hosted card when it’s claimed.Each generated card receives its own independent limit.

offerId

UUID

required

The hosted virtual card program to issue against.The offer must be active and enabled for Send Cards.

quantity

Int

required

The number of hosted links to generate.One share request and one hosted URL are created for every requested quantity.

Controls how recipients receive their links.

GENERATE_URL returns hosted URLs for you to distribute.
EMAIL emails recipients automatically.
PHONE_NUMBER sends recipients an SMS.

userCashBalanceId

UUID

required

The Spend Account that funds every generated card.Although this field appears optional in the GraphQL schema, it is required in practice.

daysUntilExpiration

Int

How long recipients have to claim the hosted link.If omitted, the program default is used.The resulting expiration date also becomes the issued card’s lock date.

Deliver cards by email or SMS instead

Instead of distributing hosted URLs yourself, Fluz can send every recipient their own activation link.

Email

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "shareMethod": "EMAIL",
    "recipientListEmail": [
      "alice@example.com",
      "bob@example.com"
    ],
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

SMS

{
  "input": {
    "cardLimit": 25,
    "offerId": "<OFFER_ID>",
    "quantity": 2,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": [
      "+18883606660",
      "+18885551234"
    ],
    "userCashBalanceId": "<USER_CASH_BALANCE_ID>"
  }
}

Recipient list length must exactly equal quantity.If they don’t match, validation fails and no links are created.Phone numbers must:

include the country code
contain no spaces
be supplied as strings

Example:

+18883606660

Generating hosted links does not reserve funds.If the selected Spend Account doesn’t contain sufficient available balance when the recipient claims the card, card issuance fails.

The generation response intentionally returns only the hosted URLs.It does not return:

shareRequestBatchId
shareRequestDisplayId

You’ll retrieve those in the next step.

Retrieve the generated share requests

Although you already have the hosted URLs, you’ll usually also want the underlying share request records.These contain:

lifecycle status
batch identifiers
display IDs
issued virtual card IDs
expiration information

Immediately after generation, retrieve your pending share requests.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    linkExpirationDate
    virtualCardId
    linkUrl
  }
}

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

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestBatchId": "BATCH123",
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkExpirationDate": "2026-08-01T00:00:00Z",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
      },
      {
        "shareRequestBatchId": "BATCH123",
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkExpirationDate": "2026-08-01T00:00:00Z",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      }
    ]
  }
}

Match each returned linkUrl with the URLs returned during generation.Save:

the shared shareRequestBatchId
both shareRequestDisplayId values

You’ll use them later when deactivating the unused link.At this point both links should have:

Status: PENDING
Virtual Card ID: null

which confirms that:

the links were created successfully
no recipient has claimed them yet
no virtual cards have been issued

Claim one link as the recipient

Open Link A in your browser.This is exactly the experience your recipient sees.The hosted flow guides recipients through card activation without requiring any API integration.During activation the recipient:

Opens the hosted activation page.
Signs in or creates a Fluz account.
Completes identity verification.
Completes two-factor authentication.
Adds a billing address if one isn’t already on file.
Creates a card PIN.
Receives their hosted virtual card.

Only after the final step does Fluz:

issue the virtual card
fund it from your Spend Account
assign it to the recipient

The recipient becomes the authorized holder of that card only.They do not gain access to:

your Fluz account
your Spend Accounts
your balances
any other generated cards

Once issued, the recipient can:

view the card
spend online
add it to Apple Pay or Google Wallet (where supported)
view future transactions

Leave Link B untouched.We’ll use it to demonstrate link revocation in the next section.

Verify the card was issued

After the recipient claims Link A, retrieve the share requests again.This time you’ll see the claimed link transition from PENDING to ISSUED.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestDisplayId
    shareObjectStatus
    virtualCardId
    linkUrl
  }
}

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

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "ISSUED",
        "virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387",
        "linkUrl": "https://fluz.app/virtual-prepaid-card/3f8ac...c1"
      },
      {
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "PENDING",
        "virtualCardId": null,
        "linkUrl": "https://fluz.app/virtual-prepaid-card/9b2dd...77"
      }
    ]
  }
}

Your two links should now be in different lifecycle states.

Link	Expected status	Meaning
Link A	`ISSUED`	The recipient successfully claimed the card and a virtual card has been created.
Link B	`PENDING`	The link has not yet been claimed.

The appearance of a virtualCardId confirms that card issuance has completed successfully.

Understanding Send Card statuses

Every hosted Send Card progresses through one of four lifecycle states.

Status	Meaning
`PENDING`	The hosted link has been generated but hasn’t yet been claimed.
`ISSUED`	The recipient successfully claimed the link and received a virtual card.
`USED`	The issued card has completed at least one transaction.
`EXPIRED`	The hosted link expired naturally or was deactivated before being claimed.

Only links in the PENDING state can be deactivated.Once a card reaches ISSUED, deactivating the original link does not revoke the card.

Deactivate the unused link

Suppose the second recipient never needed their card, or a batch was generated accidentally.You can revoke any unclaimed hosted link using either:

shareRequestBatchIds
shareRequestDisplayIds

For this Quickstart we’ll deactivate only Link B using its display ID.

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

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

{
  "data": {
    "deactivateVCShareLinks": "1 share requests successfully deactivated!"
  }
}

Deactivation immediately prevents the hosted link from ever being claimed.If a recipient later opens the link they’ll receive an expired or revoked experience instead of the activation flow.

Deactivation only affects unclaimed links.If a recipient has already claimed a card (ISSUED or USED), the hosted link can no longer be used to revoke it.To stop spend on an issued card, use the appropriate virtual card lifecycle controls such as Lock Virtual Card.

Confirm the final lifecycle

Retrieve the share requests one final time.

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    shareRequestDisplayId
    shareObjectStatus
    virtualCardId
  }
}

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

{
  "data": {
    "getVCShareLinks": [
      {
        "shareRequestDisplayId": "SR-000001",
        "shareObjectStatus": "ISSUED",
        "virtualCardId": "c8dbe6d8-2f2f-4c90-8d7e-15ef5b06e387"
      },
      {
        "shareRequestDisplayId": "SR-000002",
        "shareObjectStatus": "EXPIRED",
        "virtualCardId": null
      }
    ]
  }
}

You’ve now exercised the complete Send Cards lifecycle.

Link	Final status	Result
Link A	`ISSUED`	Successfully claimed and issued to a recipient.
Link B	`EXPIRED`	Successfully revoked before it could be claimed.

At this point you’ve successfully used all three public Send Cards operations:

✅ generateVCShareLinks
✅ getVCShareLinks
✅ deactivateVCShareLinks

You’re done 🎉

You’ve completed the full hosted Send Cards lifecycle—from generation through recipient activation, lifecycle tracking, and link revocation. Along the way you:

Generated hosted virtual card links.
Selected the Spend Account that funds recipient cards.
Retrieved and tracked share request records.
Claimed a hosted card as the recipient.
Verified the transition from PENDING to ISSUED.
Revoked an unused hosted link.
Confirmed the final EXPIRED state.

From here you can explore more advanced Send Cards workflows.

Send Cards overview

Recipient experience, program rules, lifecycle states, and complete error reference.

Generate Share Links

The detailed API reference for every Send Cards operation.

Get Spend Accounts

Retrieve and manage the Spend Accounts used to fund hosted cards.

Manage Virtual Cards

Lock and manage cards after they’ve been issued to recipients.

Want to learn more?Contact us at support@fluz.app to speak with our experts or request a demo.

Get started

Fluz Dashboard

Quickstarts

Send a Card to Someone

Before you begin

The full flow

Understanding the generation settings

Email

SMS

You’re done 🎉

Send Cards overview

Generate Share Links

Get Spend Accounts

Manage Virtual Cards

​Before you begin

​The full flow

​Understanding the generation settings

​Email

​SMS

​You’re done 🎉

Send Cards overview

Generate Share Links

Get Spend Accounts

Manage Virtual Cards

Before you begin

The full flow

Understanding the generation settings

Email

SMS

You’re done 🎉