Create a Single-Use Virtual Card

A single-use card is a virtual card that locks itself as soon as one transaction completes. It is the standard control for one-time payouts, trial signups, and any charge you want to guarantee cannot repeat. There is no cardType: SINGLE_USE parameter. cardType is a response field, not an input. You get single-use behavior by setting lockCardNextUse: true when you issue the card.

Locking is reversible. This is not a hard one-time-use guarantee.A locked card can be reopened with unlockVirtualCard by anyone with access to it, and once unlocked it will authorize again. lockCardNextUse is an automation, not an irreversible control.If your risk model requires that a card can never transact twice, pair the lock with a spendLimit sized to the expected charge and a near-term lockDate — see Making it stick.

Issue the card

Restricted Access

This mutation requires a Bearer token with the CREATE_VIRTUALCARD scope.

Set lockCardNextUse: true on createVirtualCard. Everything else about the request is a normal card issuance.

mutation CreateVirtualCard($input: CreateVirtualCardInput!) {
  createVirtualCard(input: $input) {
    virtualCardId
    cardholderName
    virtualCardLast4
    expiryMonth
    expiryYear
    status
    cardType
    initialAmount
    usedAmount
    createdAt
  }
}

{
  "input": {
    "idempotencyKey": "63b2c9e0-62d1-42ab-b1c2-1a7ee2f8c0a9",
    "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
    "spendLimit": 75.00,
    "spendLimitDuration": "LIFETIME",
    "lockCardNextUse": true,
    "cardNickname": "Vendor payout — one time",
    "primaryFundingSource": "FLUZ_BALANCE",
    "userCashBalanceId": "b1155504-ad30-4b2f-873d-b8795277b128"
  }
}

The relevant fields

Field	Type	Description
`lockCardNextUse`	`Boolean`	When `true`, the card locks automatically once its next transaction completes. Defaults to `false`.
`spendLimit`	`Float!`	Maximum chargeable amount. Minimum `$5`. You are only charged for what is actually used.
`spendLimitDuration`	`VirtualCardSpendLimitDuration`	Use `LIFETIME` for single-use cards so the limit never refreshes. Defaults to `LIFETIME`.
`lockDate`	`String`	Date the card locks regardless of use. Format `yyyy-mm-dd`. Defaults to 47 months out.

cardType in the response is not a reliable single-use indicator. Read back the card’s lockCardNextUse setting rather than inferring one-time behavior from cardType, which reflects the card program rather than this setting.

Making it stick

lockCardNextUse on its own is reversible. For payout and disbursement flows where a second charge would be a real loss, stack the controls — each one fails closed independently:

Size the spend limit to the charge

Set spendLimit to the exact expected amount, with spendLimitDuration: LIFETIME so it never refreshes. Even if the card is unlocked, there is no headroom left to spend against.

Set a near-term lockDate

A card issued for a payout that should clear within a week does not need to stay open for 47 months. lockDate locks the card on that date whether or not it was ever used, which also cleans up abandoned cards.

Restrict the funding composition

Set usePrepaymentBalance: false and useRewardsBalance: false so the card draws only from the userCashBalanceId you nominate, rather than reaching into prepaid or rewards balances.

Reconcile against the ledger

Do not treat issuance as completion. Confirm the charge landed with getVirtualCardTransactions before marking the payout settled in your own system.

{
  "input": {
    "idempotencyKey": "8f14c2b1-9d3e-4a77-b0c5-2e6f1a8d4b93",
    "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
    "spendLimit": 75.00,
    "spendLimitDuration": "LIFETIME",
    "lockCardNextUse": true,
    "lockDate": "2026-08-24",
    "primaryFundingSource": "FLUZ_BALANCE",
    "userCashBalanceId": "b1155504-ad30-4b2f-873d-b8795277b128",
    "usePrepaymentBalance": false,
    "useRewardsBalance": false,
    "cardNickname": "Payout #48812"
  }
}

Converting an existing card

lockCardNextUse is also editable after issuance through editVirtualCard, so you can retire a multi-use card by letting its next transaction be its last.

mutation EditVirtualCard($input: EditVirtualCardInput!) {
  editVirtualCard(input: $input) {
    virtualCardId
    virtualCardLast4
    status
    cardType
  }
}

{
  "input": {
    "idempotencyKey": "d3b07384-d9a0-4f1e-9b2c-7a5e8c1f2d64",
    "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
    "lockCardNextUse": true
  }
}

To stop a card immediately rather than after one more transaction, use lockVirtualCard instead — that takes effect at once and does not wait for a transaction.

Issuing in bulk

lockCardNextUse is available per order item on createVirtualCardBulkOrder, which is the right call for batch disbursements rather than looping createVirtualCard.

mutation CreateVirtualCardBulkOrder($input: CreateVirtualCardBulkOrderInput!) {
  createVirtualCardBulkOrder(input: $input) {
    orderId
    orderStatus
  }
}

{
  "input": {
    "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
    "orderItems": [
      {
        "quantity": 100,
        "spendLimit": 50,
        "spendLimitDuration": "LIFETIME",
        "lockCardNextUse": true,
        "cardNickname": "Q3 rebate",
        "primaryFundingSource": "FLUZ_BALANCE"
      }
    ]
  }
}

Bulk orders are asynchronous. Poll getVirtualCardBulkOrderStatus and handle partial failures — an order can complete with fewer cards than requested.

Edge cases

These are the situations where “one transaction” turns out to be ambiguous. Design for them before you ship a payout flow.

Situation	What to expect
Verification auths	Some merchants run a $0 or$ 1 authorization to validate the card before the real charge. If that counts as the card’s use, the card locks before the intended purchase and the real charge declines. Test against your specific merchant category.
Declined transactions	A decline is not a completed transaction and should not consume the card. Confirm the card is still `ACTIVE` before reissuing — reissuing on a false assumption leaves a live card outstanding.
Partial authorizations	A merchant may authorize less than the full amount. Reconcile against actual transaction amounts rather than assuming `spendLimit` was captured.
Refunds after lock	If a refund needs to land on a card that has already locked, confirm the credit posts before you close out the payout in your own system.
Recurring merchants	A single-use card will fail the second billing cycle by design. Do not issue single-use cards for subscriptions — use `lockDate` to bound a recurring card instead.

Locked is not deleted. Virtual cards cannot be deleted. A locked card stays visible and queryable on the account indefinitely, with its transaction history intact. Plan for accumulation if you are issuing single-use cards at volume, and use cardNickname and transactionCategory at issuance so they remain reconcilable later.

Common mistakes

Passing cardType: SINGLE_USE to createVirtualCard

CreateVirtualCardInput has no cardType field — the request fails with ARG-0001. cardType only appears in the response. Set lockCardNextUse: true instead.

Treating the lock as irreversible

unlockVirtualCard reopens a locked card, and the card will authorize again if spend headroom remains. If a second charge would be a real loss, constrain spendLimit and lockDate as well rather than relying on the lock alone.

Using a refreshing spend limit

spendLimitDuration: DAILY or MONTHLY refreshes the available limit on schedule. On a card that gets unlocked, that restores spending capacity you thought was spent. Use LIFETIME for single-use cards.

Marking the payout complete at issuance

Issuing a card is not the same as money moving. The card may never be used, may be used for less than the limit, or may lock on a verification auth. Reconcile against getVirtualCardTransactions before closing the payout.

Issue Cards

The full createVirtualCard reference.

Create Bulk Order

Issue single-use cards at volume in one asynchronous request.

Lock Virtual Card

Stop a card immediately instead of after its next transaction.

Merchant-Locked Cards

Restrict a card to one merchant instead of one transaction.

​Issue the card

Restricted Access

​The relevant fields

​Making it stick

​Converting an existing card

​Issuing in bulk

​Edge cases

​Common mistakes

Issue Cards

Create Bulk Order

Lock Virtual Card

Merchant-Locked Cards

Issue the card

The relevant fields

Making it stick

Converting an existing card

Issuing in bulk

Edge cases

Common mistakes