> ## 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` 变更来创建一张可配置资金来源、限额与生命周期控制的虚拟卡。
**先决条件：** 具有 `CREATE_VIRTUALCARD` 范围的用户访问令牌，以及一个 `CreateVirtualCardInput` 对象。要查找 `offerId`，请参见 [获取虚拟卡优惠](/features/get-card-offers)。
**账单地址必须可验证。** 无论以内联的 `billingAddress` 传入，还是通过 `userAddressId` 引用，账单地址都必须为真实、可投递的**美国**地址（`US`、`USA` 或 `United States`），且城市、州和邮编正确；**不接受邮政信箱（PO Box）**。在设置持卡人时会基于 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 Box）。 | 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 } }"
}'
```
## 示例变更
```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
}
}
```
## 示例变更 — 仅现金余额
将虚拟卡限制为仅从指定的 `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`。