> ## 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 3: Registering card users

> Why cardholder registration is mandatory, what data it needs, and how to map card users to your own model.

## Learning objectives

* Understand why card user registration is mandatory in most systems
* Know what data you need to register a user
* Decide how to map Bitnob’s card users to your own internal user model
* Learn common mistakes that cause card creation failures
* Design a clean integration flow with proper error handling

## What does it mean to “register a card user”?

In every virtual card system (whether you're issuing through Visa, Verve, Mastercard, or another scheme), there's a concept of a “cardholder” or “card user”.

Even if your product never asks your customer to "register" for anything, the system behind the scenes must assign every card to a person, entity, or reference.

You are creating a legal + financial identity link between the card and the person spending.

## Why is this required?

Card schemes require that every card is traceable to:

* A verified person (in consumer apps), or
* A registered business (in B2B apps)

This is for:

| Reason | Description |
| - | - |
| KYC | Meet regulatory obligations for anti-money laundering (AML) |
| Fraud Prevention | Identify and block users abusing the system |
| Dispute Resolution | Know who made a payment if it’s contested |
| Card Limits | Limit spend, top-ups, and transactions per user |
| Compliance Audits | Prove you’re not issuing anonymous cards into the wild |

Even if you're building a fully abstracted experience. Your backend must create and manage this linkage.

## What data is required?

This depends on the issuing partner and the region. But generally, every registered card user requires:

| Field | Example |
| - | - |
| first\_name | Nia |
| last\_name | Okonkwo |
| email | [customer@example.com](mailto:customer@example.com) |
| dial\_code | +234 |
| phone\_number | 8000000003 |
| country | NGA |
| metadata | Your internal user ID, such as user\_123abc |

**Best practice:** Don’t reuse an email or phone across users. Bitnob matches customers on them, so a repeat returns the existing customer instead of creating a new one.

## Mapping your user to the card system

In your platform, you already have a User ID or customer object.

Keep that ID in the customer’s `metadata` when you register the user with the card system, and store the customer `id` we return against it.

YourUser(user\_id: "user\_001") ⇨ Bitnob customer(id: "d4c5a8a1-bb22-4a72-90a5-a9998123dfe3")

This gives you a 1:1 mapping. All cards, transactions, and events can now be linked back cleanly.

## API example: Register a card user

```json theme={null}
POST /api/customers
```

```json theme={null}
{
  "customer_type": "individual",
  "first_name": "Nia",
  "last_name": "Okonkwo",
  "email": "customer@example.com",
  "dial_code": "+234",
  "phone_number": "8000000003",
  "country": "NGA"
}
```

`customer_type` and `email` are required, and `country` is a three-letter ISO code.

```json theme={null}
{
  "success": true,
  "message": "Customer created successfully",
  "data": {
    "id": "d4c5a8a1-bb22-4a72-90a5-a9998123dfe3",
    "customer_type": "individual",
    "email": "customer@example.com"
  }
}
```

You **must** store the customer `id` in your database. This is what you’ll need to issue cards.

## Common mistakes

| Mistake | What Happens |
| - | - |
| Duplicate email, phone, or BVN across users | `POST /api/customers` returns `201` with the existing customer, and the other fields you sent are ignored |
| Missing required fields | Hard 400 errors |
| Trying to create a card before Card KYC is approved | Fails with `400` "KYC verification required before issuing this card" |
| Changing your internal user ID after registration | Results in broken mappings or mismatched user data |
| Using temporary test data in production | May get flagged during audits or sandbox promotion |

## One-time vs. Reusable users

| Pattern | When to Use |
| - | - |
| One-time user per card | Anonymous, burner cards, marketing campaigns |
| Reusable user per app customer | Wallets, payroll, consumer apps |

### Best practice:

Use one card user per real user in your system.

That way, all future cards and transactions link to one record.

## Knowledge check

Which of these statements is true?

1. You don’t need to register users if you only issue one card per app.
2. A phone number should belong to one card user in your account.
3. You can issue a card directly without registering the user.
4. Registered users are not visible to Bitnob or card issuers.

Answer :

A phone number should belong to one card user. Bitnob uses it to deduplicate customers in your account, so a repeat returns the existing customer.

## Developer tip

If you support multiple wallets, apps, or projects, add a project or environment tag to the customer’s `metadata`. This makes debugging, deletion, and auditing easier later.

## Key takeaways

* Registering card users is a legal and technical requirement in every card program
* You should map this to your own user model cleanly
* Always register the user **before issuing the card**
* Store the customer `id` permanently. This is what you use to issue cards
* Clean data = smooth lifecycle, fewer errors, and easier support


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