Register & Send

The standard hosted-link flow defers everything to the recipient: you mint a link, and Fluz doesn’t create the virtual card until the recipient opens it, verifies themselves, and claims it. This flow inverts that for recipients you’ve already identified. You register the recipient’s identity and billing address yourself with registerUser, then generate a share link with generateVCShareLinks using shareMethod: EXISTING_USER. Fluz creates the virtual card immediately, at generation time — not at claim — and binds it to that one recipient. The link is still delivered and claimed the normal way; only card creation moves earlier. Funding is still drawn at claim time, same as the standard flow — from userCashBalanceId, falling back to your prepayment or rewards balance if enabled and the spend account runs short.

When to use this instead of a plain share link

You already know exactly who the recipient is (by user ID) and want the card created and ready before you notify them, rather than waiting on them to claim it.
You want a hard guarantee that only the intended recipient can ever view the link — not “first person to click it.”
You’re sending to a batch of known recipients and want deterministic 1:1 mapping between recipient and card.

Before you start

You’ll need a Bearer access token. Basic auth is not accepted for either operation.

Operation	Scope	Also required
`registerUser`	—	Registration permission enabled on your application
`generateVCShareLinks`	`CREATE_SHARE_LINK`	An active virtual card offer, a spend account to fund from (optionally with prepayment/rewards balance as fallback)

User registration is not enabled by default. registerUser is a restricted mutation — your application must be explicitly approved by Fluz before it can create users. Contact your Fluz sales rep or account manager to have it enabled. Calls from an unapproved application fail with AUTH-0022.If the recipient already has a Fluz account, you can skip registration and go straight to generateVCShareLinks with their existing recipientUserIds.

See Authentication for how to mint a scoped token.

The flow

Call registerUser with the recipient’s profile, their billing address, and their acceptance of the cardholder agreement.

mutation RegisterUser(
  $firstName: String!
  $lastName: String!
  $phoneNumber: String!
  $regionCode: String!
  $emailAddress: String!
  $dateOfBirth: String!
  $billingAddress: VirtualCardBillingAddressInput!
  $acceptCardholderAgreement: Boolean!
) {
  registerUser(
    firstName: $firstName
    lastName: $lastName
    phoneNumber: $phoneNumber
    regionCode: $regionCode
    emailAddress: $emailAddress
    dateOfBirth: $dateOfBirth
    billingAddress: $billingAddress
    acceptCardholderAgreement: $acceptCardholderAgreement
  ) {
    success
    userId
    accountId
    billingAddressId
    error {
      code
      message
    }
  }
}

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "phoneNumber": "5555555555",
  "regionCode": "US",
  "emailAddress": "ada.lovelace@example.com",
  "dateOfBirth": "1990-01-31",
  "billingAddress": {
    "streetAddressLine1": "456 Market St",
    "streetAddressLine2": "Suite 200",
    "country": "United States",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105"
  },
  "acceptCardholderAgreement": true
}

acceptCardholderAgreement must be true — registration is rejected otherwise. Registration failures come back as HTTP 200 with success: false, not in the GraphQL errors array; always check success.Keep the returned userId — you’ll pass it into generateVCShareLinks in the next step. accountId and billingAddressId are also returned but aren’t needed for this flow.

This step does not create a card or a cardholder agreement. It only creates the user record, saves the billing address, and records that the agreement was accepted. Both the virtual card and the recipient’s binding to it are created in the next step.

AUTH-0026 and AUTH-0027 are not failures. They mean the person already has a Fluz account — common, since Fluz accounts aren’t scoped to your application. Skip registration and use their existing user ID directly.

Full parameter reference: registerUser.

Generate the share link

Call generateVCShareLinks with shareMethod: EXISTING_USER and recipientUserIds set to the user ID(s) from registration (or any other known Fluz user IDs). The length of recipientUserIds must equal quantity.

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

{
  "input": {
    "cardLimit": 100,
    "offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
    "daysUntilExpiration": 30,
    "quantity": 1,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

For multiple recipients, pass one user ID per card — order corresponds 1:1 with the generated links:

{
  "input": {
    "cardLimit": 100,
    "offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
    "quantity": 3,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": [
      "f1320ac4-52dc-4c67-9e80-24e506b18450",
      "3f8a1c2d-4e5f-4a67-9a10-2b3c4d5e6f70",
      "9b2d0e11-77aa-4c3b-8f9e-1a2b3c4d5e6f"
    ],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

Leave recipientListEmail and recipientListPhone unset — recipients are identified by recipientUserIds for this shareMethod, and Fluz already has contact details on file for each registered user.Optionally set usePrepaymentBalance and/or useRewardsBalance to true so Fluz can draw from your prepayment or rewards balance as a fallback if userCashBalanceId doesn’t cover the full amount at claim time:

With fallback funding

{
  "input": {
    "cardLimit": 100,
    "offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
    "quantity": 1,
    "shareMethod": "EXISTING_USER",
    "recipientUserIds": ["f1320ac4-52dc-4c67-9e80-24e506b18450"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "usePrepaymentBalance": true,
    "useRewardsBalance": true
  }
}

See funding sources for details.

Fluz creates the card and assigns the link

Unlike the standard flow, the virtual card is created now, at generation time, rather than deferred to claim. The recipient is assigned to that card and its link as soon as the call returns. Funding is still drawn at claim time, same as the standard flow — primarily from userCashBalanceId, with your prepayment or rewards balance used as a fallback if you set usePrepaymentBalance / useRewardsBalance and the spend account runs short.Each returned link is locked to its assigned recipient: only that recipient’s Fluz account can open and claim it. If a different user opens the URL, they’re shown an access-denied state after sign-in, same as any other already-bound link.

The link is delivered

The link is sent to the recipient the same way any hosted link is — via SMS or email, using the contact details Fluz has on file for that user. From there the recipient signs in, completes 2FA, and lands on their card. Since the card already exists, there’s no billing-address prompt or card-issuance wait at claim time — the card is funded at this point, same as the standard flow.

How this differs from the standard flow

	Standard (`GENERATE_URL` / `EMAIL` / `PHONE_NUMBER`)	This flow (`EXISTING_USER`)
Recipient identified by	Email / phone in `recipientListEmail` / `recipientListPhone`	Known Fluz `userId` in `recipientUserIds`
Card created	At claim, when the recipient completes onboarding	At `generateVCShareLinks` call time
Card funded	At claim time	At claim time (same as standard)
Who can claim the link	Whoever opens it first, if unclaimed	Only the assigned recipient — enforced from the moment the link is created
Recipient onboarding at claim	Sign-in, 2FA, billing address (if needed)	Sign-in, 2FA — no billing address prompt, since it was collected at registration
Revealing the card	Prompts for PIN (or PIN creation, if none set yet)	Prompts for PIN (or PIN creation, if none set yet)

See Send Open Loop Cards for the standard flow and Recipient Experience for the full claim walkthrough.

Notes and limitations

recipientUserIds must reference existing Fluz users. If the recipient isn’t registered yet, register them first with registerUser (this flow), or use the standard hosted-link flow and let Fluz onboard them at claim time.
recipientUserIds length must equal quantity. A mismatch returns a validation error and creates no records.
Card creation moves to generation time — funding does not. The virtual card object and recipient binding are created when you call generateVCShareLinks, but funds are still drawn at claim time, same as the standard flow: from userCashBalanceId first, then your prepayment or rewards balance as a fallback if usePrepaymentBalance / useRewardsBalance are set and the spend account is insufficient.
Registration is per-application and per-environment. Permission granted for staging does not carry to production. See Deploying to Production.
Never register real people in staging. See Staging vs. Live.

Next steps

Send Open Loop Cards

The standard flow — generate links and let Fluz issue the card at claim time.

Recipient Experience

What the recipient sees when they open and claim a hosted link.

Register Customers

Full reference for registerUser, including error handling and fallback patterns.

​Before you start

​The flow

​How this differs from the standard flow

​Notes and limitations

​Next steps

Send Open Loop Cards

Recipient Experience

Register Customers

Before you start

The flow

How this differs from the standard flow

Notes and limitations

Next steps