> ## 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` 範圍。
* 接收識別消費帳戶的 `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
  }
}
```

| Argument                 | Type    | Required | Description                |
| ------------------------ | ------- | -------- | -------------------------- |
| `userCashBalanceId`      | `UUID!` | Yes      | 欲入金之消費帳戶。                  |
| `virtualAccountNumberId` | `UUID`  | No       | 要出文件的特定 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
  }
}
```

| Argument                 | Type                   | Required    | Description                                                  |
| ------------------------ | ---------------------- | ----------- | ------------------------------------------------------------ |
| `userCashBalanceId`      | `UUID!`                | Yes         | 薪資應入帳的消費帳戶。                                                  |
| `virtualAccountNumberId` | `UUID`                 | No          | 預設為該帳戶的主要 VAN。                                               |
| `depositType`            | `PaycheckDepositType!` | Yes         | 雇主應匯入每次薪資的比例：`FULL` 表示全額，`FIXED` 表示固定金額，`PERCENTAGE` 表示一定比例。 |
| `depositAmount`          | `Float`                | Conditional | **當 `depositType` 為 `FIXED` 時必填。**                           |
| `depositPercentage`      | `Float`                | Conditional | **當 `depositType` 為 `PERCENTAGE` 時必填。** 值介於 1–100。           |
| `employerName`           | `String`               | No          | 列印在表單雇主欄的名稱，1–150 字元。若省略則留白。                                 |
| `employeeName`           | `String`               | No          | 列印為帳戶持有人姓名，1–150 字元。預設為帳戶的法定名稱，若有 DBA 名稱則於第二行顯示。             |
| `eSignForm`              | `Boolean`              | No          | 將帳戶持有人之印刷體姓名以斜體預先填入簽名欄位。預設關閉，留白以供手寫簽名。                       |

<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
  }
}
```

| Argument                 | Type       | Required | Description                                                                                               |
| ------------------------ | ---------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `userCashBalanceId`      | `UUID!`    | Yes      | 要出具文件的消費帳戶。                                                                                               |
| `virtualAccountNumberId` | `UUID`     | No       | 預設為該帳戶的主要 VAN。                                                                                            |
| `displayBalance`         | `Boolean`  | No       | 在信函中包含帳戶餘額。預設關閉。                                                                                          |
| `balanceCheckDate`       | `DateTime` | No       | 以該日（美東時區）結束時的可用餘額取代目前餘額，並以該日期標示信函的 as-of 行。不可為未來時間。**僅在 `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"]
```

***

**想了解更多？** 與我們的專家洽談以取得更多資訊或申請示範。