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

# 虚拟账户文件

> 为消费账户的虚拟账户号生成付款说明、工资直接存款表格和账户状态信函的 PDF。

三个查询会为某个消费账户的[虚拟账户号](/features/virtual-account-numbers)返回可直接分享的 PDF 文档。每个文档按需生成，作为**base64 编码字符串**返回，需解码后在你的界面中渲染或提供下载。

三者均：

* 需要 `LIST_PAYMENT` scope。
* 接收标识消费账户的 `userCashBalanceId`。
* 可选接收 `virtualAccountNumberId`。**若省略，则使用该消费账户的主 VAN。**
* 返回 `SpendAccountPdfDocument!`。

***

## 解码响应

```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>
  这些 PDF 包含完整、未遮罩的路由号与账号。请勿在用户会话之外缓存、记录日志或存储它们。改为按需重新生成。
</Warning>

***

## 付款说明

`getSpendAccountPaymentInstructions` 会生成包含为虚拟账户号入金所需路由与账户详细信息的 PDF。当用户需要告知客户、供应商，或其外部银行将资金汇往何处时使用。

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

| 参数                       | 类型      | 必填 | 说明                        |
| ------------------------ | ------- | -- | ------------------------- |
| `userCashBalanceId`      | `UUID!` | 是  | 资金应入账的消费账户。               |
| `virtualAccountNumberId` | `UUID`  | 否  | 要出具文件的特定 VAN。默认为账户的主 VAN。 |

[API reference](/api-reference/queries/get-spend-account-payment-instructions)

***

## 工资存款表格

`getSpendAccountPaycheckDepositForm` 会生成一份预填的直接存款授权表格，用户可提交给其雇主的薪资部门。该路径用于将全部或部分工资路由至 Fluz 消费账户。

```graphql theme={null}
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
  }
}
```

| 参数                       | 类型                     | 必填   | 说明                                                         |
| ------------------------ | ---------------------- | ---- | ---------------------------------------------------------- |
| `userCashBalanceId`      | `UUID!`                | 是    | 工资应入账的消费账户。                                                |
| `virtualAccountNumberId` | `UUID`                 | 否    | 默认为账户的主 VAN。                                               |
| `depositType`            | `PaycheckDepositType!` | 是    | 雇主应汇入每次工资的比例：`FULL` 表示全额，`FIXED` 为固定金额，`PERCENTAGE` 为一定比例。 |
| `depositAmount`          | `Float`                | 条件必填 | **当 `depositType` 为 `FIXED` 时必填。**                         |
| `depositPercentage`      | `Float`                | 条件必填 | **当 `depositType` 为 `PERCENTAGE` 时必填。** 取值 1–100。          |
| `employerName`           | `String`               | 否    | 表格雇主一栏显示的名称，1–150 个字符。省略则留空。                               |
| `employeeName`           | `String`               | 否    | 显示为账户持有人的姓名，1–150 个字符。默认为账户的法定名称，若有 DBA 名称则显示在第二行。         |
| `eSignForm`              | `Boolean`              | 否    | 用斜体的账户持有人打印名预填签名行。默认关闭，留空以便手写签名。                           |

<Warning>
  **校验在服务端强制执行。** 若发送 `depositType: FIXED` 但未提供 `depositAmount`，或发送 `depositType: PERCENTAGE` 但未提供 1–100 之间的 `depositPercentage`，将返回错误。请在你的界面中先行校验再调用。
</Warning>

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

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

***

## 账户状态信函

`getSpendAccountStatusLetter` 会生成一封确认账户存在且状态良好的信函——相当于银行出具的证明。将 `displayBalance` 设为 `true` 可在信函中包含当前余额；若用户仅需证明账户存在，可不勾选。

```graphql theme={null}
query statusLetter(
  $userCashBalanceId: UUID!
  $virtualAccountNumberId: UUID
  $displayBalance: Boolean
  $balanceCheckDate: DateTime
) {
  getSpendAccountStatusLetter(
    userCashBalanceId: $userCashBalanceId
    virtualAccountNumberId: $virtualAccountNumberId
    displayBalance: $displayBalance
    balanceCheckDate: $balanceCheckDate
  ) {
    fileName
    pdfBase64
  }
}
```

| 参数                       | 类型         | 必填 | 说明                                                                                                         |
| ------------------------ | ---------- | -- | ---------------------------------------------------------------------------------------------------------- |
| `userCashBalanceId`      | `UUID!`    | 是  | 要出具文件的消费账户。                                                                                                |
| `virtualAccountNumberId` | `UUID`     | 否  | 默认为账户的主 VAN。                                                                                               |
| `displayBalance`         | `Boolean`  | 否  | 在信函中包含账户余额。默认关闭。                                                                                           |
| `balanceCheckDate`       | `DateTime` | 否  | 报告该日（美国东部时区）结束时的可用余额，而非当前余额，并在信函的“截至”行标注该日期。不得是未来时间。**仅当 `displayBalance` 为 `true` 时生效**——否则信函不包含余额且忽略该日期。 |

<Warning>
  `balanceCheckDate` 需要完整的 RFC-3339 时间戳——诸如 `"2026-07-01"` 的裸日期会被拒绝。仅使用该时间戳在**美国东部时区**所落之日，因此请将其锚定为东部时间：`"2026-07-01T00:00:00Z"` 在东部时间是 6 月 30 日晚 8 点，报告的是 6 月 30 日的余额。
</Warning>

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

***

## 选择正确的文件

```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"]
```

***

**想进一步了解？** 与我们的专家交流，获取更多信息或请求演示。