Module 4: Issuing a card

​

Learning objectives

• 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?

• 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)

​

When should you issue a card?

​

Requirements before you issue

• Have already registered the card user (see Module 3)
• Have stored their customer id
• Have approved Card KYC for that customer
• Be under the limit of 3 active cards per customer
• Fund a prepaid card with at least $2 when you create it

​

Sample card issuance API request

POST /api/cards

{
  "customer_id": "d4c5a8a1-bb22-4a72-90a5-a9998123dfe3",
  "card_type": "virtual",
  "card_program": "prepaid",
  "card_brand": "visa",
  "currency": "USD",
  "amount": 10000000,
  "reference": "card_user_001"
}

{
  "success": true,
  "message": "Card created successfully",
  "data": {
    "card": {
      "id": "8e2a77a1-913a-4aa6-8f29-c4e4a26e36a1",
      "status": "pending",
      "created_status": "processing",
      "customer_id": "d4c5a8a1-bb22-4a72-90a5-a9998123dfe3",
      "masked_pan": "000000******"
    }
  }
}

{
  "event_id": "8e4b0d3c-5e2f-4a6b-9c0d-2e3f4a5b6c7d",
  "event": "virtualcard.created.failed",
  "data": {
    "id": "<card_id>",
    "companyId": "<company_uuid>",
    "reference": "card_user_001",
    "status": "failed",
    "createdStatus": "failed",
    "failureReason": "The card could not be created."
  }
}

​

UX tip: Displaying card details

​

What happens behind the scenes

• Your API call goes to your platform (or Bitnob if integrated)
• Your platform contacts the card processor
• A unique PAN, expiry, and CVV are allocated
• The card is linked to your registered user
• The card moves from pending to active, and you receive a webhook
• You receive card metadata (masked or full)

​

Quotas and limits to be aware of

​

Common mistakes to avoid

​

Recap quiz

1. Can a card be issued before a user is registered?
2. Can you fetch the PAN and CVV again later?
3. Is the card active immediately after it’s created?
4. What field links your system user to the virtual card record?

1. No
2. Yes, with Get secure card details
3. No, it starts as pending
4. customer_id

​

Key takeaways

• Virtual card issuance is fast, but must be done after user registration
• A new card starts as pending: wait for the webhook before you show it
• 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