Virtual Card Integration Guide (End-to-End)

Introduction

This guide walks you through the entire lifecycle of a virtual card: from card issuance, funding, spending, and handling webhook events.

It’s designed to help developers build a working card implementation quickly, using only essential endpoints and best practices.

What You’ll Build

A complete card experience:

Create a virtual card

Top up the card

Handle a transaction

Process a refund or reversal

Freeze, unfreeze, or terminate the card

Listen for real-time webhooks

Prerequisites

Your API key

Webhook endpoint set up and reachable

Understanding of your wallet or funding flow (e.g., float, stablecoin)

Create a Virtual Card

Issue a card for a customer. For full details, see Create Card in the API reference.

API Endpoints

Request

Create Card Request

Response

Create Card Response

Store the card id — you’ll use it for funding and spend tracking.

Top Up the Card

Fund the card so it can be used. For full details, see Fund or Withdraw in the API reference.

API Endpoints

Request

Top Up Card Request

Response

Top Up Card Response

At this point, the card is ready for use.

Handle Card Spend

Once the user uses the card (e.g., Netflix, Spotify), you’ll get a webhook. You can also pull the same activity with Card Transactions.

Webhook: virtualcard.transaction.debit

Use this to update user transaction history and deduct from UI balance.

Handle Refunds and Reversals

Sometimes merchants reverse or refund charges. Both arrive on the Virtual Cards Transaction webhook, and a single record can be fetched with Get Card Transaction.

Webhook: virtualcard.transaction.refund

Webhook: virtualcard.transaction.reversed

Freeze, Unfreeze, or Terminate the Card

Freeze:

Freeze Endpoint

Unfreeze:

Unfreeze Endpoint

Terminate:

Terminate Endpoint

Freezing and unfreezing both go through Update Card Status; termination is Terminate Card. A card cannot be recovered after termination, and cannot be terminated within 24 hours of being created.

Webhook Summary

Every event below is documented in the Virtual Cards webhooks reference; verify the signature before acting on one.

Card Lifecycle

event	description
virtualcard.created.completed	Card issued successfully
virtualcard.created.failed	Card creation failed
virtualcard.terminated.refund	Remaining balance refunded after card termination
virtualcard.regularized	Card regularized after compliance or balance adjustment
virtualcard.expiration	Card has expired

Top-Up

event	description
virtualcard.topup.completed	Top-up confirmed
virtualcard.topup.failed	Top-up failed

Withdrawal

event	description
virtualcard.withdrawal.completed	Withdrawal from card completed
virtualcard.withdrawal.failed	Withdrawal from card failed

Transactions

event	description
virtualcard.transaction.debit	Spend confirmed (merchant charge settled)
virtualcard.transaction.credit	Credit applied to the card
virtualcard.transaction.authorization	Authorization hold placed by merchant
virtualcard.transaction.settlement	Merchant settled a previously authorized transaction
virtualcard.transaction.verification	Zero-amount authorization to verify card is active
virtualcard.transaction.pre-auth.approved	Pre-authorization approved by the card network
virtualcard.transaction.reversed	Merchant canceled a pending transaction
virtualcard.transaction.refund	Refund received from merchant
virtualcard.transaction.crossborder	Cross-border charge during international use
virtualcard.transaction.contactless	Contactless (NFC/tap) payment processed
virtualcard.transaction.terminated.refund	Refund to a terminated card, credited to float

Declines

event	description
virtualcard.transaction.declined	Transaction declined
virtualcard.transaction.declined.charge	Decline rule violation fee charged
virtualcard.transaction.declined.frozen	Transaction declined because card is frozen
virtualcard.transaction.declined.terminated	Transaction declined because card is terminated
virtualcard.transaction.authorization.failed	Authorization attempt failed
virtualcard.transaction.issuerexpiration	Transaction declined due to issuer expiration

Developer Notes

Use idempotency keys for top-ups and card creation

Always verify webhook signatures (see webhook doc)

Track card status in your database (active, frozen, terminated)

Do not store CVV post-creation

Display masked_pan only after user authentication