Handle an inbound virtual card transaction callback

Receives a purchase/authorization callback from a card processor for a virtual card and decides whether to approve or decline it, then settles the outcome on the ledger.

This endpoint is intentionally unauthenticated (no Authorization header is required or checked) since it is called directly by the card processing provider rather than by an authenticated dashboard/API client. Provider-level trust (e.g. IP allow-listing, mutual TLS, or a shared-secret check) is expected to be enforced upstream of this handler.

Decision logic, evaluated in order once the card is found:

If no virtual card matches virtual_card_id, the transaction is declined with no side effects other than a log entry.

If the card's status is not active (frozen, pending-approval, or terminated), the transaction is declined and a failed payout intent action is recorded with a status_reason describing why (card_frozen, card_pending_approval, card_terminated).

If currency does not match the card's funding currency, the transaction is declined and a failed payout intent action is recorded with status_reason: "currency_mismatch".

If amount exceeds the card's cached available balance, the transaction is declined and a failed payout intent action is recorded with status_reason: "insufficient_funds".

Otherwise the transaction is approved: funds are moved from the enabled currency's CardFloat ledger account to the provider's Clearing ledger account, the card's cached_balance is debited by amount, a successful payout intent action is recorded, and a corresponding payout transaction is created against the funding account (when one is linked).

Every card purchase (approved or declined, except the "no card found" case) is grouped under a single payout intent for the card, created lazily on first use. This endpoint is idempotent only in the sense that each call always creates a new payout intent action record — replaying the same provider_reference will result in a duplicate ledger entry, so callers should not retry a callback that already received a response.

Responses

🟢200

application/json

The callback was processed successfully. The transaction may still have been declined at the business-logic level — check data.status to see the outcome. This endpoint returns 200 for both approvals and declines; it is not an error response when status is "declined".

Bodyapplication/json

🟠400

🔴500

curl --location '/virtual-card-transaction-callbacks' \ --header 'Content-Type: application/json' \ --data '{ "virtual_card_id": "01HX8XKXZPYSVAE8HHZXMTZFRR", "amount": 2500, "currency": "USD", "provider_reference": "txn_9f2a1c7d4e5b" }'

Handle an inbound virtual card transaction callback

Request

Responses