Skip to main content
This Quickstart issues 100 virtual cards in one request. You’ll place an asynchronous bulk order, poll its status as cards are created, and retrieve the full card details — the same pattern whether you’re issuing 10 cards or 10,000.
Prerequisites
  • A Fluz account with a staging application — Steps 1–2 of any quickstart, or see Prepare your accounts and API credentials.
  • A token with CREATE_VIRTUALCARD to place the order and REVEAL_VIRTUALCARD to poll its status. Without the second, step 2 fails with AUTH-0031.
  • Enough available balance to cover the order — 100 cards × the spend limit you set.
  • A billing address on the account, or a billingAddress on each order item. Without one, card creation fails and the order completes with failedCardCreations equal to the order size.

​
The full flow

A bulk order is asynchronous. The mutation returns immediately with an orderId and a PENDING status; the cards are created in the background. The order and the cards succeed independently — an order can reach COMPLETED with some cards failed, so the order status alone never tells you whether you got what you asked for. Always reconcile successfulCardCreations and failedCardCreations against totalCards before treating an order as done. orderStatus has one more possible value not shown above — CANCELED — which, like FAILED, means the order will produce no more cards.

Place the bulk order

One createVirtualCardBulkOrder call creates all 100 cards. Each entry in orderItems is a card configuration with a quantity — here, 100 identical single-use disbursement cards.Unlike most money-moving mutations, this one takes no idempotencyKey — the input accepts only offerId and orderItems. See Idempotency for where the key does apply.
The offerId applies to every card in the order; mix configurations by adding more orderItems entries (e.g. 20 qty of $25 single-use + 80 qty of $100 monthly). lockCardNextUse: true makes each card self-destruct after its first charge — the standard disbursement pattern.
Bulk orders are asynchronous — the response is an orderId and PENDING, not cards. Save the orderId; it’s your handle for everything that follows.

Poll the order to completion

Track progress with getVirtualCardBulkOrderStatus. Cards populate incrementally while the order is PENDING:
Poll with backoff until orderStatus is COMPLETED (or FAILED) — while pending, successfulCardCreations climbs toward totalCards and virtualCards fills in.
The response contains full PANs, CVVs, and expiry dates in plaintext. Treat it as sensitive cardholder data: TLS only, never log it, surface it only to authorized users.

Handle partial failures

A bulk order can partially succeed: successfulCardCreations: 98, failedCardCreations: 2 on a completed order means 98 real, spendable cards and 2 that need retrying. Reconcile by comparing the counts to totalCards, then re-issue only the shortfall as a new order:
Persistent failures usually trace to program limits or funding — check Virtual Card Error Codes and your available balance.

​
You’re done 🎉

One hundred configured cards from one request, with a poll loop that’s production-ready as-is. Next:

Get virtual card transactions

Monitor spend across the whole batch — up to 10 cards per query, or account-wide by date.

Send cards to recipients

Distributing to people outside your org? Hosted claim links handle onboarding for you.
Want to learn more? Contact us at support@fluz.app to speak with our experts or request a demo.