Virtual Card Integration Guide (End-to-End)

Introduction

This guide walks you through the entire lifecycle of a virtual card: from user registration to 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)

All cards must be tied to a registered card user.

Command Line

Response

➡️ Store card_user_id — you’ll need it to create cards and fetch transactions.

Create a Virtual Card

Now issue a card for the user.

API Endpoints

Request

Create Card Request

Response

Create Card Response

➡️ Store cardId — you’ll use it for top-ups and spend tracking.

Top Up the Card

Fund the card so it can be used.

API Endpoints

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.

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.

Webhook: virtualcard.transaction.refund

Webhook: virtualcard.transaction.reversed

Freeze, Unfreeze, or Terminate the Card

Freeze:

Freeze Endpoint

Unfreeze:

Unfreeze Endpoint

Terminate:

Terminate Endpoint

➡️ Card cannot be recovered after termination.

Webhook Summary

event	use
virtualcard.created.success	Card issued
virtualcard.topup.success	Top-up confirmed
virtualcard.transaction.debit	Spend confirmed
virtualcard.transaction.refund	Refund received
virtualcard.transaction.reversed	Pre-auth or silent transaction reversed
virtualcard.transaction.declined	Spend failed
virtualcard.transaction.declined.terminated	Card terminated after too many fails
virtualcard.transaction.terminated.refund	Refund to closed card, credited to float

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 maskedPan only after user authentication