> ## 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.
# Create a Single-Use Virtual Card
> Issue a virtual card that locks itself automatically after one transaction.
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`](/features/unlock-virtual-card) 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](#making-it-stick).
***
## Issue the card
This mutation requires a Bearer token with the `CREATE_VIRTUALCARD` scope.
Set `lockCardNextUse: true` on [`createVirtualCard`](/features/create-card). Everything else about the request is a normal card issuance.
```graphql theme={null}
mutation CreateVirtualCard($input: CreateVirtualCardInput!) {
createVirtualCard(input: $input) {
virtualCardId
cardholderName
virtualCardLast4
expiryMonth
expiryYear
status
cardType
initialAmount
usedAmount
createdAt
}
}
```
```json theme={null}
{
"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:
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.
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.
Set `usePrepaymentBalance: false` and `useRewardsBalance: false` so the card draws only from the `userCashBalanceId` you nominate, rather than reaching into prepaid or rewards balances.
Do not treat issuance as completion. Confirm the charge landed with [`getVirtualCardTransactions`](/features/get-virtual-card-transactions) before marking the payout settled in your own system.
```json theme={null}
{
"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`](/features/edit-virtual-card), so you can retire a multi-use card by letting its next transaction be its last.
```graphql theme={null}
mutation EditVirtualCard($input: EditVirtualCardInput!) {
editVirtualCard(input: $input) {
virtualCardId
virtualCardLast4
status
cardType
}
}
```
```json theme={null}
{
"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`](/features/lock-virtual-card) instead — that takes effect at once and does not wait for a transaction.
***
## Issuing in bulk
`lockCardNextUse` is available per order item on [`createVirtualCardBulkOrder`](/features/create-bulk-order), which is the right call for batch disbursements rather than looping `createVirtualCard`.
```graphql theme={null}
mutation CreateVirtualCardBulkOrder($input: CreateVirtualCardBulkOrderInput!) {
createVirtualCardBulkOrder(input: $input) {
orderId
orderStatus
}
}
```
```json theme={null}
{
"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`](/features/get-bulk-order-status) 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
`CreateVirtualCardInput` has no `cardType` field — the request fails with `ARG-0001`. `cardType` only appears in the response. Set `lockCardNextUse: true` instead.
`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.
`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.
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.
***
The full `createVirtualCard` reference.
Issue single-use cards at volume in one asynchronous request.
Stop a card immediately instead of after its next transaction.
Restrict a card to one merchant instead of one transaction.