> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Virtual Account Documents

> Generate payment instructions, paycheck direct-deposit forms, and account status letters as PDFs for a spend account's virtual account number.

Three queries return ready-to-share PDF documents for a spend account's [virtual account number](/features/virtual-account-numbers). 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

```graphql theme={null}
query getSpendAccountPaymentInstructions($userCashBalanceId: UUID!) {
  getSpendAccountPaymentInstructions(userCashBalanceId: $userCashBalanceId) {
    fileName
    pdfBase64
  }
}
```

```javascript theme={null}
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);
```

<Warning>
  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.
</Warning>

***

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

```graphql theme={null}
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](/api-reference/queries/get-spend-account-payment-instructions)

***

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

```graphql theme={null}
query paycheckDepositForm(
  $userCashBalanceId: UUID!
  $virtualAccountNumberId: UUID
  $depositType: PaycheckDepositType!
  $depositAmount: Float
  $depositPercentage: Float
) {
  getSpendAccountPaycheckDepositForm(
    userCashBalanceId: $userCashBalanceId
    virtualAccountNumberId: $virtualAccountNumberId
    depositType: $depositType
    depositAmount: $depositAmount
    depositPercentage: $depositPercentage
  ) {
    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.                                                                                   |

<Warning>
  **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.
</Warning>

```json Variables theme={null}
{
  "userCashBalanceId": "9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74",
  "depositType": "PERCENTAGE",
  "depositPercentage": 25
}
```

[API reference](/api-reference/queries/get-spend-account-paycheck-deposit-form)

***

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

```graphql theme={null}
query statusLetter(
  $userCashBalanceId: UUID!
  $virtualAccountNumberId: UUID
  $displayBalance: Boolean
) {
  getSpendAccountStatusLetter(
    userCashBalanceId: $userCashBalanceId
    virtualAccountNumberId: $virtualAccountNumberId
    displayBalance: $displayBalance
  ) {
    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. |

[API reference](/api-reference/queries/get-spend-account-status-letter)

***

## Choosing the Right Document

```mermaid theme={null}
flowchart TD
    Q{"Who is the user\ngiving this to?"}
    Q -->|Their employer| A["Paycheck Deposit Form\ngetSpendAccountPaycheckDepositForm"]
    Q -->|A customer, vendor,\nor outside bank| B["Payment Instructions\ngetSpendAccountPaymentInstructions"]
    Q -->|A landlord, lender,\nor auditor| C["Account Status Letter\ngetSpendAccountStatusLetter"]
```

***

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