Card status, locks & limits

Status and lock are separate

status describes where the card is in its lifecycle. Whether it can authorize right now is a separate question, answered by its lock fields. A locked card still reports status: ACTIVE.

`VirtualCardStatus`	Meaning
`PENDING`	Card created; issuance not yet complete
`ACTIVE`	Issued and open. Check the lock fields to see whether it can authorize
`USED`	Used; applies mainly to single-use cards
`CANCELLED`	Closed permanently
`REFUNDED`	The card’s underlying purchase was refunded
`EXPIRED`	Closed by the expiry process
`DISPUTED`	In a dispute

LOCKED and CLOSED_EXPIRED are not status values.

Telling a locked card from an open one

Read authorizationSetting:

Field	Meaning
`lockedByUser`	Locked with `lockVirtualCard`
`lockedBySystem`	Locked by Fluz, for example by risk controls
`lockCardNextUse`	Locks itself after its next transaction
`lockDate`	Locks itself at this time

A card is usable only when status is ACTIVE and no lock applies.

After `lockDate` passes

The card stays ACTIVE but declines as locked. It doesn’t become EXPIRED. You can reopen a multi-use card:

call unlockVirtualCard, optionally passing a new lock date; or
call setVirtualCardLockDate with a future date, or clear it.

Reading a card’s current state and limit

Query getVirtualCards, filtered to the card:

query ($filter: VirtualCardFilterInput) {
  getVirtualCards(filter: $filter) {
    rows {
      virtualCardId
      status
      authorizationSetting {
        dailySpendLimit weeklySpendLimit monthlySpendLimit
        annualSpendLimit lifetimeSpendLimit
        lockDate lockedByUser lockedBySystem lockCardNextUse
      }
    }
  }
}

initialAmount is the amount requested when the card was created. It never changes, so it isn’t the current limit. Read the current limit from the authorizationSetting limit that matches the card’s duration.

Changing the limit

Send spendLimit and spendLimitDuration together on editVirtualCard. Sending only spendLimit may not apply the change. Confirm it by re-reading authorizationSetting, not initialAmount.

Closing a card permanently

There is no public mutation to cancel a card. For a temporary stop, use lockVirtualCard. To cancel permanently, contact support with the virtualCardId. VC-0008 UNABLE_TO_CANCEL comes from that support-side process. When a card is cancelled, its unspent funded balance goes back through the refund process. Authorizations that haven’t cleared are cleaned up with the card’s purchase; timing depends on the network. Locking a card doesn’t release its balance.

​Status and lock are separate

​Telling a locked card from an open one

​After lockDate passes

​Reading a card’s current state and limit

​Changing the limit

​Closing a card permanently

Status and lock are separate

Telling a locked card from an open one

After `lockDate` passes

Reading a card’s current state and limit

Changing the limit

Closing a card permanently