> ## 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.
# 建立卡片
使用 `createVirtualCard` 這個 mutation 來建立可設定資金來源、消費上限與生命週期控管的虛擬卡。
**先決條件：** 具有 `CREATE_VIRTUALCARD` 權限範圍的使用者存取權杖，以及一個 `CreateVirtualCardInput` 物件。若需取得 `offerId`，請參考 [取得虛擬卡優惠](/features/get-card-offers)。
**帳單地址必須可驗證。** 帳單地址（無論是以 `billingAddress` 內嵌傳入，或由 `userAddressId` 參照）必須是可投遞的真實**美國**地址（`US`、`USA` 或 `United States`），並具有正確的城市、州別與郵遞區號；**不接受郵政信箱（PO boxes）**。在設定持卡人時，系統會透過 USPS 資料（經由 Smarty）進行驗證。若無法通過驗證，卡片將不會被建立，且請求會以 `VC-0025`（`UnableToCreateAuthUser`）失敗回應，其值會出現在 `extensions.code`。請參閱[地址格式要求](/concepts/address-formatting-requirements)。
## 沙盒測試優惠
| Offer ID | Program Name | Reward Value |
| -------------------------------------- | ---------------------------------------------- | ------------ |
| `ed669305-5e43-40a0-9a25-7a15ed174628` | Virtual Card | 1.5% |
| `b23630f6-8d91-43df-84aa-a541e7691197` | Virtual Card - Mastercard Prepaid | 1.5% |
| `592c394e-26cc-44ac-a145-a5f81301fe77` | Brand Locked Virtual Card - Mastercard Prepaid | 1.5% |
## 重要注意事項
* **資金來源：** 你可以使用 Fluz 餘額或已連結的銀行帳戶作為虛擬卡的主要資金來源。
* 若選擇銀行帳戶作為 `primaryFundingSource`，必須提供 `bankAccountId`。
* **消費上限：** 你設定的 `spendLimit` 必須符合所選 `spendLimitDuration` 的專案既定上限；若超出將產生錯誤。
* **餘額組成：** 預設情況下，虛擬卡可能同時從你指定的消費帳戶、預付（禮品卡）餘額與回饋餘額中撥款（若可用）。你可以在輸入中將 `usePrepaymentBalance: false` 與 `useRewardsBalance: false` 設定為僅從消費帳戶扣款。
* **交易註記：** 你可在建立卡片時選擇性附加 `memo` 與/或 `transactionCategory`。這些資訊將關聯至產生的交易，以利追蹤與整理。
* 若提供 `transactionCategory`，系統會在該帳戶中尋找或建立相符的分類。
* 不支援 `attachmentId`
## 參數
* `input`（`CreateVirtualCardInput!`）：包含新虛擬卡詳細資訊的輸入物件。
## CreateVirtualCardInput 欄位
| Field | Type | Description | Required |
| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- |
| `idempotencyKey` | `UUID!` | 由用戶端產生的唯一 UUID，確保請求只會被處理一次。 | Yes |
| `spendLimit` | `Float!` | 你可刷卡的最高金額。實際只會就使用的金額收費。 | Yes |
| `spendLimitDuration` | `VirtualCardSpendLimitDuration` | 卡片限額週期類型。預設為 `LIFETIME`。 | No |
| `lockDate` | `String` | 卡片將被鎖定的日期。預設為自建立日起 47 個月。格式：yyyy-mm-dd | No |
| `lockCardNextUse` | `Boolean` | 於卡片下一次使用後鎖定。預設為 `false`。 | No |
| `cardNickname` | `String` | 卡片暱稱。 | No |
| `primaryFundingSource` | `VirtualCardFundingSource` | 虛擬卡的主要資金來源。預設為 `FLUZ_BALANCE`。 | No |
| `bankAccountId` | `UUID` | 銀行帳戶的唯一識別碼。當 `primaryFundingSource` 為 `BANK_ACCOUNT` 時必填。 | No |
| `offerId` | `UUID` | 虛擬卡優惠的 Offer Id。使用 `getVirtualCardOffers` 取得有效優惠清單。 | No |
| `userCashBalanceId` | `UUID` | 用於該筆購買的現金餘額（消費帳戶）。 | No |
| `usePrepaymentBalance` | `Boolean` | 當為 `false` 時，卡片不會從預付（禮品卡）餘額扣款。預設為 `true`，保留可同時使用預付資金與指定消費帳戶的既有行為。 | No |
| `useRewardsBalance` | `Boolean` | 當為 `false` 時，卡片不會從回饋餘額扣款。預設為 `true`，保留可同時使用回饋與指定消費帳戶的既有行為。 | No |
| `billingAddress` | `VirtualCardBillingAddressInput` | 虛擬卡的帳單地址。若與使用者帳戶中的現有地址（依街道、城市、州別與郵遞區號比對）不相符，將建立新地址。除 streetAddressLine2 外其餘欄位皆必填。只支援美國地址。若提供 userAddressId，會忽略此欄位。 | No |
| `userAddressId` | `UUID` | 要用於虛擬卡的、使用者帳戶中現有帳單地址的 ID。若提供，會優先於 billingAddress。此 ID 必須參照到呼叫者所屬的 UserAddress。 | No |
| `memo` | `String` | 要附加至交易的選用備註。 | No |
| `transactionCategory` | `String` | 選用的分類名稱。系統會在帳戶中尋找或建立相符的分類。 | No |
## VirtualCardBillingAddressInput 欄位
| Field | Type | Description | Required |
| -------------------- | --------- | ----------------------------------------------- | -------- |
| `streetAddressLine1` | `String!` | 主要街道地址（例如 "123 Main St"）。發卡機構不接受郵政信箱（PO boxes）。 | Yes |
| `streetAddressLine2` | `String` | 選填的次要地址（例如公寓、套房或單位號）。 | No |
| `country` | `String!` | 國家名稱。目前僅支援 "United States"。 | Yes |
| `city` | `String!` | 城市名稱。 | Yes |
| `state` | `String!` | 州名（例如 "New York"）或兩碼美國州別縮寫（例如 "NY"）。 | Yes |
| `postalCode` | `String!` | 5 碼美國 ZIP 郵遞區號。 | Yes |
未通過驗證的地址會回傳 `VC-0025`（`UnableToCreateAuthUser`）。請參閱[地址格式要求](/concepts/address-formatting-requirements)與[虛擬卡錯誤代碼](/features/virtual-card-error-codes)。
## cURL 範例
```bash theme={null}
curl -X POST \
https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
-d '{
"query": "mutation CreateVirtualCard { createVirtualCard( input: { spendLimit: 150.00, idempotencyKey: \"63b2c9e0-62d1-42ab-b1c2-1a7ee2f8c0a9\", offerId: \"b3355504-ad30-4b2f-873d-b8795277b918\", spendLimitDuration: MONTHLY, lockCardNextUse: false, cardNickname: \"My New Test Card\", primaryFundingSource: FLUZ_BALANCE, memo: \"Office supplies\", transactionCategory: \"Expenses\" } ) { virtualCardId userId cardholderName expiryMonth expiryYear virtualCardLast4 status cardType initialAmount usedAmount createdAt } }"
}'
```
## 範例 Mutation
```graphql theme={null}
mutation {
createVirtualCard(
input: {
idempotencyKey: "07df5653-43a8-4532-9881-3ab5857bbe12"
spendLimit: 123.45
spendLimitDuration: DAILY
lockDate: "2030-10-10"
lockCardNextUse: true
cardNickname: "xyz789"
primaryFundingSource: FLUZ_BALANCE
offerId: "b3355504-ad30-4b2f-873d-b8795277b918"
userCashBalanceId: "b1155504-ad30-4b2f-873d-b8795277b128"
}
) {
virtualCardId
userId
cardholderName
expiryMonth
expiryYear
virtualCardLast4
status
cardType
initialAmount
usedAmount
createdAt
}
}
```
## 範例 Mutation — 僅使用現金餘額
限制虛擬卡僅從指定的 `userCashBalanceId` 扣款，不包含預付與回饋資金。
```graphql theme={null}
mutation {
createVirtualCard(
input: {
idempotencyKey: "07df5653-43a8-4532-9881-3ab5857bbe13"
spendLimit: 150.00
offerId: "b3355504-ad30-4b2f-873d-b8795277b918"
primaryFundingSource: FLUZ_BALANCE
userCashBalanceId: "b1155504-ad30-4b2f-873d-b8795277b128"
usePrepaymentBalance: false
useRewardsBalance: false
}
) {
virtualCardId
virtualCardLast4
status
initialAmount
}
}
```
## 回應範例
```json theme={null}
{
"data": {
"createVirtualCard": {
"virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
"userId": "07df5653-43a8-4532-9881-3ab5857bbe11",
"cardholderName": "xyz789",
"expiryMonth": "12",
"expiryYear": "27",
"virtualCardLast4": "7890",
"status": "ACTIVE",
"cardType": "MULTI_USE",
"initialAmount": 150.00,
"usedAmount": 0,
"createdAt": "2025-07-09T10:00:00Z"
}
}
}
```
### 回應欄位
| Field | Type | Description |
| ------------------ | ------------------- | ------------------------------- |
| `virtualCardId` | `UUID` | 新建立之虛擬卡的唯一識別碼。 |
| `userId` | `UUID` | 建立此虛擬卡的使用者唯一識別碼。 |
| `cardholderName` | `String` | 虛擬卡上所示的持卡人姓名。 |
| `expiryMonth` | `String` | 虛擬卡的兩位數到期月份（例如 "12" 代表 12 月）。 |
| `expiryYear` | `String` | 虛擬卡的兩位數到期年份（例如 "27" 代表 2027 年）。 |
| `virtualCardLast4` | `String` | 虛擬卡卡號的末四碼。 |
| `status` | `VirtualCardStatus` | 虛擬卡目前狀態（例如 ACTIVE、PENDING）。 |
| `cardType` | `VirtualCardType` | 指示卡片是 MULTI\_USE 或 SINGLE\_USE。 |
| `initialAmount` | `Float` | 建立卡片時設定的原始 spendLimit。 |
| `usedAmount` | `Float` | 目前已使用的總金額。 |
| `createdAt` | `DateTime` | 虛擬卡建立的時間戳。 |
## 後續步驟
取得 PAN、CVV 與到期日，以便實際使用該卡。
枚舉你帳戶可用的所有專案，以挑選合適的 `offerId`。