创建卡片 - Fluz

使用 createVirtualCard 变更来创建一张可配置资金来源、限额与生命周期控制的虚拟卡。

先决条件： 具有 CREATE_VIRTUALCARD 范围的用户访问令牌，以及一个 CreateVirtualCardInput 对象。要查找 offerId，请参见获取虚拟卡优惠。

账单地址必须可验证。 无论以内联的 billingAddress 传入，还是通过 userAddressId 引用，账单地址都必须为真实、可投递的美国地址（US、USA 或 United States），且城市、州和邮编正确；不接受邮政信箱（PO Box）。在设置持卡人时会基于 USPS 数据（通过 Smarty）进行验证。若无法验证，卡片不会被创建，请求将以 VC-0025（UnableToCreateAuthUser）失败，返回于 extensions.code。参见地址格式要求。

沙盒测试优惠

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）。参见地址格式要求与虚拟卡错误代码。

cURL 示例

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 {
  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 扣款，排除预付和奖励资金。

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

示例响应

{
  "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。

​沙盒测试优惠

​重要注意事项

​参数

​CreateVirtualCardInput 字段

​VirtualCardBillingAddressInput 字段

​cURL 示例

​示例变更

​示例变更 — 仅现金余额

​示例响应

​响应字段

​后续步骤

显示卡片信息

获取虚拟卡优惠

沙盒测试优惠

重要注意事项

参数

CreateVirtualCardInput 字段

VirtualCardBillingAddressInput 字段

cURL 示例

示例变更

示例变更 — 仅现金余额

示例响应

响应字段

后续步骤