建立卡片 - Fluz

使用 createVirtualCard 這個 mutation 來建立可設定資金來源、消費上限與生命週期控管的虛擬卡。

先決條件： 具有 CREATE_VIRTUALCARD 權限範圍的使用者存取權杖，以及一個 CreateVirtualCardInput 物件。若需取得 offerId，請參考取得虛擬卡優惠。

帳單地址必須可驗證。 帳單地址（無論是以 billingAddress 內嵌傳入，或由 userAddressId 參照）必須是可投遞的真實美國地址（US、USA 或 United States），並具有正確的城市、州別與郵遞區號；不接受郵政信箱（PO boxes）。在設定持卡人時，系統會透過 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 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）。請參閱地址格式要求與虛擬卡錯誤代碼。

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

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 扣款，不包含預付與回饋資金。

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 範例

​範例 Mutation

​範例 Mutation — 僅使用現金餘額

​回應範例

​回應欄位

​後續步驟

顯示卡片資訊

取得虛擬卡優惠

沙盒測試優惠

重要注意事項

參數

CreateVirtualCardInput 欄位

VirtualCardBillingAddressInput 欄位

cURL 範例

範例 Mutation

範例 Mutation — 僅使用現金餘額

回應範例

回應欄位

後續步驟