Simulate Virtual Card Transactions

Staging virtual cards are real card records with real BINs, but they aren’t on a live payment network — no merchant can swipe them. To exercise your spend, balance, and reconciliation logic, Fluz injects an authorization against your card through the issuer processor’s test environment. Everything downstream of that point is the production code path: the same authorization service, the same spend controls, the same ledger entries, the same webhooks.

Staging onlySimulated transactions exist only in the staging environment (https://transactional-graph.staging.fluzapp.com/api/v1/graphql). No funds move, no interchange is generated, and nothing is submitted to Mastercard. In production, transactions arrive only from real merchant activity.

Simulations are triggered by FluzThere is no public mutation that injects a transaction onto a card. Authorization simulation happens in the issuer processor’s dashboard, which sits inside Fluz’s PCI environment and isn’t exposed to partners. Request the transactions you need through your integration channel (shared Slack channel or partnerships@fluz.app) and we’ll run them against your card, usually the same business day. Everything else on this page — issuing the card, reading the result — is fully self-serve.

Before you request a simulation

An authorization runs through the full control stack, so a card that isn’t set up correctly will decline for reasons that have nothing to do with your test.

The account has passed KYC

Cards can only be issued — and only authorize — on a verified account. See Testing KYC Flows for identities that return a pass.

You have an ACTIVE card

Issue one with createVirtualCard using an offer from Test Virtual Card Offers. Hold on to the virtual_card_id — it’s how we locate the card.

The card is funded and unlocked

The card draws on your Fluz balance. Confirm the spend limit covers your test amount and that the card hasn’t been locked, expired, or spent down. getVirtualCardBalance shows you remainingBalance at a glance.

What you can simulate

Ask for whichever leg of the lifecycle you need. Each maps to a distinct set of records and webhooks on your side.

Authorization (approval)

The base case: a purchase at a merchant you name, for an amount you name. The card’s available balance is reduced immediately and the transaction lands in a pending state. Use this to verify that spend controls, balance decrementing, and your TRANSACTION_CREATE handler all behave.

Clearing (capture)

The settlement leg that follows an authorization, sometimes days later in the real world. We can either capture in a single step alongside the authorization, or leave the authorization open so you can observe the pending state and then request the capture separately. The second option is the more faithful rehearsal of production.

Decline

A transaction the authorization service rejects. Tell us which decline you want to see — a control-driven decline (over the spend limit, wrong merchant on a brand-locked card, locked card) or an authentication decline (CVV mismatch). Declines surface a declineReason and declineCategory; see Decline Codes for the full set.

Reversal

An authorization released before it clears — the merchant abandoned the sale, or the terminal timed out. The held amount returns to the card. Worth testing if you reconcile on authorizations rather than clearings.

Refund

Value returned to the card after a purchase has cleared, in full or in part. Appears as a REFUND transaction type rather than a reduction of the original purchase, so your ledger needs to handle it as a separate record.

Zero-dollar and AVS checks

Some merchants probe a card with a

0.00 or

0.01 authorization before charging it. These appear as their own records and are reversed shortly after. If your reconciliation sums authorizations, test this case — it’s a common source of double-counting.

What to send us

The more of this you provide, the fewer round trips.

Field	Required	Notes
`virtual_card_id`	Yes	Returned by `createVirtualCard`. Card last four also works.
Amount	Yes	In USD.
Outcome	Yes	Approve or decline — and if decline, which reason you want to exercise.
Merchant name	No	Defaults to a generic test merchant. Set it if you match on descriptors.
MCC	No	Set it if you’re testing category-based logic.
Single-step clearing	No	On to capture immediately; off to leave the authorization pending.

Verifying the result

Once we confirm the simulation has run, everything is readable over the API. Nothing about reading a simulated transaction differs from reading a real one.

query {
  getVirtualCardTransactions(input: {
    virtualCardIds: ["<virtual_card_id>"]
    filters: { transactionTypes: [PURCHASE, REFUND, DECLINE] }
  }) {
    virtualCardId
    transactions {
      transactionId
      transactionDate
      transactionType
      transactionStatus
      transactionAmount
      transactionApproval
      transactionResponseCode
      merchantName
      merchantDescriptor
      mcc
    }
  }
}

query {
  getVirtualCardBalance(input: {
    virtualCardIds: ["<virtual_card_id>"]
  }) {
    virtualCardId
    spentAmount
    remainingBalance
    spendLimit
    spendLimitDuration
  }
}

A simulated purchase should show up as a PURCHASE row with a matching drop in remainingBalance. A decline shows up under the DECLINE type and leaves the balance untouched — declines are also queryable in isolation through Get Declined Transactions.

Card-level queries only cover card activity. To see the same event in the account’s unified ledger alongside deposits and transfers, use getTransactions — see Transactions Overview.

Webhooks

Simulated transactions fire the same events as real ones, which makes this the cleanest way to test your endpoint end to end:

Event	Fires when
`TRANSACTION_CREATE`	The authorization is approved. `status` is `PENDING`.
`TRANSACTION_UPDATE`	The transaction clears. `status` moves to `SETTLED`.
`TRANSACTION_DECLINE`	The authorization is rejected, with `declineReason` and `declineCategory`.

If you asked for an authorization without single-step clearing, you should see TRANSACTION_CREATE on its own and TRANSACTION_UPDATE only after the capture is run. See Webhooks for payloads and signature verification.

Troubleshooting

What you see	Likely cause
Declined when you expected an approval	Spend limit below the amount, card locked, insufficient Fluz balance, or a brand-locked card at the wrong merchant.
Nothing appears on the card	The simulation ran against a different card. Confirm the `virtual_card_id` you sent.
Transaction stays pending	Expected — the authorization hasn’t been captured. Request the clearing leg.
No webhook received	Check the subscription and required scopes; the transaction itself is still visible over the API.
Balance doesn’t move on a $0.01 charge	Expected for an AVS probe. It reverses on its own.

Next steps

Your First Virtual Card Purchase

The full happy path — pick a program, issue a card, reveal it, and track its spend.

Get Virtual Card Transactions

Filter card activity by type and date range, and read every field on a transaction.

Decline Codes

Every decline reason and category, and what your app should do with each.

Webhooks

Subscribe to transaction events, verify signatures, and handle retries.

Want to learn more? Contact us at partnerships@fluz.app. Speak with our experts for more info or to request a demo.

Get started

Fluz Dashboard

Quickstarts

Simulate Virtual Card Transactions

Before you request a simulation

What you can simulate

What to send us

Verifying the result

Webhooks

Troubleshooting

Next steps

Your First Virtual Card Purchase

Get Virtual Card Transactions

Decline Codes

Webhooks

​Before you request a simulation

​What you can simulate

​What to send us

​Verifying the result

​Webhooks

​Troubleshooting

​Next steps

Your First Virtual Card Purchase

Get Virtual Card Transactions

Decline Codes

Webhooks

Before you request a simulation

What you can simulate

What to send us

Verifying the result

Webhooks

Troubleshooting

Next steps