Cardholders

A cardholder represents a person who will receive and use virtual cards issued through your Issuing app. After creation the cardholder is active but unverified — KYC verification is required before any card can be issued.

Create Cardholder → Verify Identity (KYC) → Issue Card(s)

What a Cardholder Has

Field	Description
`id`	Unique cardholder ID (e.g. `CH1a2b3c4d5e6f`)
`externalId`	Your own ID for this person — map to your user database
Personal info	First name, last name, email, phone, date of birth, gender
Address	Street, city, state, country, postal code
`status`	Account status: `ACTIVE`, `INACTIVE`, or `SUSPENDED`
`kycStatus`	Identity verification status — must be `ACCEPTED` to issue cards
`metadata`	Custom key-value data from your platform

Lifecycle

Statuses

Account Status

Status	Description
`ACTIVE`	Normal operating state
`INACTIVE`	Temporarily disabled
`SUSPENDED`	Blocked due to policy

Suspending a cardholder does not automatically freeze their cards. Manage card statuses separately if needed.

KYC Status

kycStatus	Description	Can Issue Cards
`UNSUBMITTED`	No verification started	No
`PENDING`	Verification in progress	No
`ACCEPTED`	Identity verified	Yes
`REJECTED`	Verification failed — retry allowed	No

Cards can only be issued when status: ACTIVE and kycStatus: ACCEPTED.

Quick Start

// 1. Create cardholder
const cardholder = await createCardholder({
  firstName: 'Alice',
  lastName: 'Example',
  email: 'john@example.com',
  phone: '+15550001234',
  dateOfBirth: '1990-01-01',
  gender: 'MALE',
  country: 'US'
});
// cardholder.kycStatus === 'UNSUBMITTED' — cannot issue cards yet

// 2. Initiate KYC and redirect cardholder
const kyc = await initiateKycSession(cardholder.id);
redirectTo(kyc.verificationUrl);

// 3. Listen for webhook, then issue card
// Webhook: cardholder.kyc_approved
const card = await createCard({ cardholderId: cardholder.id });

See KYC Verification for details on the verification paths.

Integration Patterns

External ID Mapping

Link cardholders to your existing user database using externalId:

await createCardholder({
  firstName: 'Alice',
  lastName: 'Doe',
  email: 'john@example.com',
  phone: '+15550001234',
  dateOfBirth: '1985-03-20',
  gender: 'MALE',
  country: 'US',
  externalId: 'user_12345'  // your database ID
});

Suspend / Reactivate

// Suspend a cardholder
PATCH /cardholders/{id}
{ "status": "SUSPENDED" }

// Reactivate
PATCH /cardholders/{id}
{ "status": "ACTIVE" }

Best Practices

Collect Complete Information Upfront

Gather all required fields at registration: firstName, lastName, email, phone, dateOfBirth, gender, country. Validate email format and use E.164 phone format (+country code + number).

Start KYC Right After Creation

Trigger the KYC flow immediately after cardholder creation so verification completes before the cardholder expects to use a card. Delaying KYC is the most common reason card issuance fails.

Use External IDs

Always set externalId to your internal user ID. It makes cardholder lookups and reconciliation straightforward without storing our cardholder IDs in your system.

Error Codes

Code	Cause	Resolution
`DUPLICATE_EMAIL`	Email already registered	Use existing cardholder or a different email
`DUPLICATE_EXTERNAL_ID`	External ID already used	Check existing cardholders first
`CARDHOLDER_NOT_VERIFIED`	KYC not accepted	Complete KYC verification before issuing cards
`CARDHOLDER_HAS_ACTIVE_CARDS`	Cannot delete with active cards	Terminate all cards before deleting

Webhook Events

Event	Description
`cardholder.created`	New cardholder registered
`cardholder.updated`	Cardholder info modified
`cardholder.suspended`	Cardholder suspended
`cardholder.activated`	Cardholder reactivated

Endpoints

GET /cardholders — List cardholders
POST /cardholders — Create cardholder
GET /cardholders/{id} — Get cardholder
PATCH /cardholders/{id} — Update cardholder
DELETE /cardholders/{id} — Delete cardholder

Getting Started

Payments

Cardholders

Cards

Cardholders

Cardholders

What a Cardholder Has

Lifecycle

Statuses

Account Status

KYC Status

Quick Start

Integration Patterns

External ID Mapping

Suspend / Reactivate

Best Practices

Error Codes

Webhook Events

Endpoints

​Cardholders

​What a Cardholder Has

​Lifecycle

​Statuses

​Account Status

​KYC Status

​Quick Start

​Integration Patterns

​External ID Mapping

​Suspend / Reactivate

​Best Practices

​Error Codes

​Webhook Events

​Endpoints

Cardholders

What a Cardholder Has

Lifecycle

Statuses

Account Status

KYC Status

Quick Start

Integration Patterns

External ID Mapping

Suspend / Reactivate

Best Practices

Error Codes

Webhook Events

Endpoints