Module 4: Issuing a Card

🧠 Learning Objectives

By the end of this module, you’ll be able to:

Understand how virtual cards are issued technically and operationally

Know what triggers card creation — and what dependencies must be in place

Write or spec the API request to issue a card

Design the right experience around card creation success or failure

Prevent the most common integration mistakes

What Does “Issuing a Card” Actually Mean?

To “issue” a virtual card means to:

Allocate a new, unique card number (PAN), expiry, and CVV

Link that card to a registered user (from Module 3)

Create a backend record with spend, funding, and transaction limits

Activate the card and return it to your app via API

Enable the card for use online under a payment scheme (e.g., Visa, Verve)

This process happens within seconds — but it relies on years of network and issuer infrastructure behind the scenes.

When Should You Issue a Card?

Virtual card issuance can be triggered by:

scenario	example
On user signup	Issue a card by default to every verified user
After first deposit	Wait until they fund their wallet or complete KYC
On request	Let users tap "Create Card" manually
Programmatic logic	Auto-create cards based on payout, spend, or budget triggers
Event-based systems	e.g. Issue a card for each influencer campaign

Best practice

Issue only after the user has real value to transact — either identity, money, or intent.

🔐 Requirements Before You Issue

To successfully issue a card, you must:

Have already registered the card user (see Module 3)

Have stored their card_user_id

Be under your card issuance quota (e.g., 2 active cards per user)

Pass a valid reference and other metadata with the request

🧾 Sample Card Issuance API Request

Base URL

Request Body

field	required	description
reference	✅	The user’s registered reference (must match registered user)
label	Optional	Name to show in the app (e.g., “Marketing Card”)
currency	Optional	Defaults to USD (or required if multi-currency is supported)

Response (Success)

Note: PAN, CVV, and expiry are only shown once. Display securely or store encrypted if required.

Response (Failure)

💡 UX Tip: Displaying Card Details

field	show in app?	why
PAN (card number)	✅ Securely, once	Users need this to pay
Expiry	✅	Required for most merchants
CVV	✅ Once	Often needed to verify online
Cardholder name	Optional	Can be “Virtual Card” or user’s name
Card status	✅	Show "Active", "Frozen", or "Terminated" clearly

Display warning: Let users know they can’t recover card details later. If lost, they must terminate and create a new one.

🧃 What Happens Behind the Scenes

Your API call goes to your platform (or Bitnob if integrated)

Your platform contacts the card processor (e.g. Interswitch, Marqeta)

A unique PAN, expiry, and CVV are allocated

The card is linked to your registered user

The card is marked active and can be used immediately

You receive card metadata (masked or full)

This flow is usually invisible to the user — it just feels instant.

🧱 Quotas and Limits to Be Aware Of

limit	typical value
Max cards per user	2 (some platforms may allow more)
Card creation rate	Throttled to prevent abuse (e.g. 5 per minute)
Label character limit	Usually 32 or fewer

Exceeding these may result in silent errors or failed API responses.

🧪 Common Mistakes to Avoid

mistake	outcome
Issuing a card before registering the user	Fails with vague error
Using the same reference twice without cleanup	Conflicts in card-user mapping
Not storing the card ID	You’ll lose the ability to top-up, track, or manage the card
Showing CVV after initial API call	Violates scheme and processor compliance rules

🧪 Recap Quiz

Can a card be issued before a user is registered?

Are PAN and CVV reusable after the API response?

Is the card active immediately after it’s created?

What field links your system user to the virtual card record?

Answers:

Yes

reference

✅ Key Takeaways

Virtual card issuance is fast, but must be done after user registration

You’ll receive the card details only once — design your UI accordingly

Displaying card status and limits clearly builds trust

Store the card ID securely for future operations (top-up, freeze, etc.)

Always catch errors and webhook events for lifecycle changes