Virtual Account Documents

Three queries return ready-to-share PDF documents for a spend account’s virtual account number. Each one is generated on demand, returned as a base64-encoded string, and is meant to be decoded and either rendered in your UI or offered as a download. All three:

Require the LIST_PAYMENT scope.
Take a userCashBalanceId identifying the spend account.
Take an optional virtualAccountNumberId. When omitted, the spend account’s primary VAN is used.
Return SpendAccountPdfDocument!.

Decoding the Response

query getSpendAccountPaymentInstructions($userCashBalanceId: UUID!) {
  getSpendAccountPaymentInstructions(userCashBalanceId: $userCashBalanceId) {
    fileName
    pdfBase64
  }
}

const { fileName, pdfBase64 } = data.getSpendAccountPaymentInstructions;

// Browser: turn the base64 payload into a downloadable file
const bytes = Uint8Array.from(atob(pdfBase64), (c) => c.charCodeAt(0));
const blob = new Blob([bytes], { type: "application/pdf" });
const url = URL.createObjectURL(blob);

const a = document.createElement("a");
a.href = url;
a.download = fileName;
a.click();
URL.revokeObjectURL(url);

These PDFs contain the full, unmasked routing and account number. Do not cache them, log them, or store them outside the user’s session. Regenerate on demand instead.

Payment Instructions

getSpendAccountPaymentInstructions produces a PDF containing the routing and account details needed to fund the virtual account number. Use it when a user needs to tell a customer, vendor, or their own outside bank where to send money.

query paymentInstructions(
  $userCashBalanceId: UUID!
  $virtualAccountNumberId: UUID
) {
  getSpendAccountPaymentInstructions(
    userCashBalanceId: $userCashBalanceId
    virtualAccountNumberId: $virtualAccountNumberId
  ) {
    fileName
    pdfBase64
  }
}

Argument	Type	Required	Description
`userCashBalanceId`	`UUID!`	Yes	The spend account the funds should land in.
`virtualAccountNumberId`	`UUID`	No	Specific VAN to document. Defaults to the account’s primary VAN.

API reference

Paycheck Deposit Form

getSpendAccountPaycheckDepositForm produces a pre-filled direct-deposit authorization form a user can submit to their employer’s payroll department. This is the intended path for routing all or part of a paycheck into a Fluz spend account.

query paycheckDepositForm(
  $userCashBalanceId: UUID!
  $virtualAccountNumberId: UUID
  $depositType: PaycheckDepositType!
  $depositAmount: Float
  $depositPercentage: Float
  $employerName: String
  $employeeName: String
  $eSignForm: Boolean
) {
  getSpendAccountPaycheckDepositForm(
    userCashBalanceId: $userCashBalanceId
    virtualAccountNumberId: $virtualAccountNumberId
    depositType: $depositType
    depositAmount: $depositAmount
    depositPercentage: $depositPercentage
    employerName: $employerName
    employeeName: $employeeName
    eSignForm: $eSignForm
  ) {
    fileName
    pdfBase64
  }
}

Argument	Type	Required	Description
`userCashBalanceId`	`UUID!`	Yes	The spend account the paycheck should land in.
`virtualAccountNumberId`	`UUID`	No	Defaults to the account’s primary VAN.
`depositType`	`PaycheckDepositType!`	Yes	How much of each paycheck the employer should send: `FULL` for the entire check, `FIXED` for a set dollar amount, or `PERCENTAGE` for a share of it.
`depositAmount`	`Float`	Conditional	Required when `depositType` is `FIXED`.
`depositPercentage`	`Float`	Conditional	Required when `depositType` is `PERCENTAGE`. Value from 1–100.
`employerName`	`String`	No	Name printed on the form’s employer line, 1–150 characters. Left blank when omitted.
`employeeName`	`String`	No	Name printed as the account holder, 1–150 characters. Defaults to the account’s legal name, with any DBA name on a second line.
`eSignForm`	`Boolean`	No	Pre-fill the signature line with the printed account-holder name, in italics. Default off, which leaves the line blank to be signed by hand.

Validation is enforced server-side. Sending depositType: FIXED without depositAmount, or depositType: PERCENTAGE without a depositPercentage between 1 and 100, returns an error. Validate in your UI before calling.

Variables

{
  "userCashBalanceId": "9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74",
  "depositType": "PERCENTAGE",
  "depositPercentage": 25,
  "employerName": "Acme Corp",
  "employeeName": "Jane Doe",
  "eSignForm": true
}

API reference

Account Status Letter

getSpendAccountStatusLetter produces a letter confirming the account exists and is in good standing — the equivalent of a bank letter. Set displayBalance to true to include the current balance on the letter; leave it off when the user only needs to prove the account exists.

query statusLetter(
  $userCashBalanceId: UUID!
  $virtualAccountNumberId: UUID
  $displayBalance: Boolean
  $balanceCheckDate: DateTime
) {
  getSpendAccountStatusLetter(
    userCashBalanceId: $userCashBalanceId
    virtualAccountNumberId: $virtualAccountNumberId
    displayBalance: $displayBalance
    balanceCheckDate: $balanceCheckDate
  ) {
    fileName
    pdfBase64
  }
}

Argument	Type	Required	Description
`userCashBalanceId`	`UUID!`	Yes	The spend account to document.
`virtualAccountNumberId`	`UUID`	No	Defaults to the account’s primary VAN.
`displayBalance`	`Boolean`	No	Include the account’s balance on the letter. Default off.
`balanceCheckDate`	`DateTime`	No	Report the available balance as of the end of this day (US Eastern) instead of the current balance, and label the letter’s as-of line with that date. Cannot be in the future. Only applies when `displayBalance` is `true` — otherwise the letter carries no balance and the date is ignored.

balanceCheckDate takes a full RFC-3339 timestamp — a bare date such as "2026-07-01" is rejected. Only the day the timestamp falls on in US Eastern is used, so anchor it to Eastern: "2026-07-01T00:00:00Z" is 8pm Eastern on June 30 and reports June 30’s balance.

API reference

Choosing the Right Document

Want to learn more? Speak with our experts for more info or to request a demo.

​Decoding the Response

​Payment Instructions

​Paycheck Deposit Form

​Account Status Letter

​Choosing the Right Document

Decoding the Response

Payment Instructions

Paycheck Deposit Form

Account Status Letter

Choosing the Right Document