> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Module 4: Issuing a card

> What triggers card creation, the dependencies it needs, and how to handle success and failure well.

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

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](https://www.bitnob.dev/learn/courses/card-issuing/module-3.md))
* 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

Full request and response schema: [Create Card](https://www.bitnob.dev/api-reference/cards/create-card.md).

```bash theme={null}
POST /api/cards
```

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

| Field | Required | Description |
| - | - | - |
| customer\_id | ✅ | The `id` of the customer you registered |
| card\_type | ✅ | `virtual` |
| card\_program | Optional | `prepaid` when you leave it out |
| card\_brand | Optional | `visa` or `mastercard` |
| currency | Optional | The card currency. `USD` when you leave it out |
| amount | ✅ for prepaid | Opening balance in micro-units, at least \$2. `10000000` is \$10 |
| reference | Optional | Your own ID for this card |

```json theme={null}
{
  "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******"
    }
  }
}
```

**Note:** the card starts as `pending`. Wait for the `virtualcard.created.completed` webhook before you show it to the user. You can then fetch the card number, CVV and expiry when the user needs them with [Get secure card details](https://www.bitnob.dev/api-reference/cards/get-secure-card-details.md).

```json theme={null}
{
  "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

| Field | Show in App? | Why |
| - | - | - |
| PAN (card number) | ✅ Securely, on request | Users need this to pay |
| Expiry | ✅ | Required for most merchants |
| CVV | ✅ On request | 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 tip:** Fetch card details only when the user asks to see them, and don’t store them. Reveal requests are rate limited.

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

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

## Quotas and limits to be aware of

| Limit | Typical Value |
| - | - |
| Max active cards per customer | 3 |
| 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 | The second request fails with `409` `ALREADY_EXISTS` |
| Not storing the card ID | You’ll lose the ability to top-up, track, or manage the card |
| Storing the card number or CVV in your own system | Breaks card scheme security rules |

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

Answers:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.