Module 3: Registering card users

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

POST /api/customers

{
  "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.

{
  "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?

You don’t need to register users if you only issue one card per app.
A phone number should belong to one card user in your account.
You can issue a card directly without registering the user.
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

Learn

Courses

Playbooks

Module 3: Registering card users

Learning objectives

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

Why is this required?

What data is required?

Mapping your user to the card system

API example: Register a card user

Common mistakes

One-time vs. Reusable users

Best practice:

Knowledge check

Developer tip

Key takeaways

​Learning objectives

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

​Why is this required?

​What data is required?

​Mapping your user to the card system

​API example: Register a card user

​Common mistakes

​One-time vs. Reusable users

​Best practice:

​Knowledge check

​Developer tip

​Key takeaways

Learning objectives

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

Why is this required?

What data is required?

Mapping your user to the card system

API example: Register a card user

Common mistakes

One-time vs. Reusable users

Best practice:

Knowledge check

Developer tip

Key takeaways