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 |
🔐 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
| 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) |
Note: PAN, CVV, and expiry are only shown once. Display securely or store encrypted if required.
💡 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:
No
No
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
