Cardholders Overview

Cardholders are individuals who can hold virtual cards issued through your FYATU Issuing application. Create cardholder profiles with basic information and start issuing cards immediately.

Core Concepts

What is a Cardholder?

A cardholder represents a person who will receive and use virtual cards. Each cardholder has:

Personal Information: Name, email, phone, date of birth, gender
Address Details: Street, city, state, country, postal code
KYC Status: Optional identity verification status
Metadata: Custom key-value data from your platform (e.g. department, employee ID, tier)

Your App → Create Cardholder → Issue Cards
                              → (Optional) Verify Identity via KYC

Cardholder Lifecycle

Why Cardholders Matter

Card Association: Cards are linked to specific cardholders
Transaction Tracking: Monitor spending per individual
Optional KYC: Verify identity when needed for compliance
Organization: Map cardholders to your platform’s users via externalId

Card Issuance

Cards can be issued to a cardholder immediately after creation — no KYC verification required.

// 1. Create cardholder
const cardholder = await createCardholder({
  firstName: 'John',
  lastName: 'Smith',
  email: 'john@example.com',
  phone: '+12025551234',
  dateOfBirth: '1990-05-15',
  gender: 'MALE',
  country: 'US'
});

// 2. Issue card immediately
const card = await createCard({ cardholderId: cardholder.id });

KYC (Know Your Customer) — Optional

KYC verification is available when you need to verify a cardholder’s identity for compliance or enhanced trust. It is not required for card issuance.

Two Verification Paths

FYATU offers two ways to verify a cardholder’s identity:

Path	Endpoint	Use When
Self-Service	`POST /cardholders/{id}/kyc/session`	The cardholder completes verification themselves via a secure link
Submit on Behalf	`POST /cardholders/{id}/kyc`	You already have the cardholder’s ID documents and submit them via their URLs

Both paths use automated identity verification (document scanning, face match, liveness detection) and deliver results via webhook.

Path 1: Self-Service (Cardholder Verifies Themselves)

Path 2: Submit on Behalf (You Have the Documents)

KYC Status Flow

Status	Description	Can Initiate Verification
`UNSUBMITTED`	No verification started	Yes
`PENDING`	Verification in progress	No (returns existing session)
`ACCEPTED`	Identity verified	No
`REJECTED`	Verification failed	Yes (retry allowed)

Verification Fee

Fee per plan (added to invoice only on successful verification):

Plan	Fee
Startup	$1.20
Enterprise	$0.80
Premium	$0.40

No upfront charge — fee is not deducted from your wallet when initiating verification
Added to your next monthly invoice only when verification is approved
Not charged on failure, abandonment, or expiry

Cardholder Statuses

Status	Description	Can Issue Cards
`ACTIVE`	Normal operating state	Yes
`INACTIVE`	Temporarily disabled	No
`SUSPENDED`	Blocked due to policy	No

Status Transitions

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

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

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

Integration Patterns

Pattern 1: Immediate Card Issuance (Recommended)

Create cardholder and issue card in one flow:

// 1. Create cardholder
const cardholder = await createCardholder({
  firstName: 'John',
  lastName: 'Smith',
  email: 'john@example.com',
  phone: '+12025551234',
  dateOfBirth: '1990-05-15',
  gender: 'MALE',
  country: 'US'
});

// 2. Issue card immediately
const card = await createCard({
  cardholderId: cardholder.id
});

// Card is ready to use
console.log('Card created:', card.id);

Pattern 2: With Optional KYC

Issue card first, verify identity later if needed:

// 1. Create cardholder + issue card
const cardholder = await createCardholder({ ... });
const card = await createCard({ cardholderId: cardholder.id });

// 2. Later, if KYC is needed
const kyc = await initiateKycSession(cardholder.id);
redirectTo(kyc.verificationUrl);

// 3. Listen for webhook: cardholder.kyc_approved

Pattern 3: External ID Mapping

Link cardholders to your existing user database:

const cardholder = await createCardholder({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  phone: '+12025551234',
  dateOfBirth: '1985-03-20',
  gender: 'MALE',
  country: 'US',
  externalId: 'user_12345' // Your database ID
});

Best Practices

Collect Complete Information

Gather all required fields upfront (firstName, lastName, email, phone, dateOfBirth, gender, country)
Validate email format before submission
Use E.164 phone format (+country code + number)

Use External IDs

Map cardholders to your user database
Use consistent ID format (e.g., user_123)
Makes lookups and reconciliation easier

Issue Cards Quickly

Cards can be issued immediately after cardholder creation
No need to wait for KYC verification
Use KYC only when your compliance requirements demand it

Error Handling

Error	Cause	Resolution
`DUPLICATE_EMAIL`	Email already registered	Use existing cardholder or different email
`DUPLICATE_EXTERNAL_ID`	External ID already used	Check existing cardholders first
`CARDHOLDER_HAS_ACTIVE_CARDS`	Cannot delete with cards	Terminate all cards before deleting
`INSUFFICIENT_BALANCE`	Not enough for verification fee	Top up business wallet (KYC only)

Webhooks

Cardholder Events

Event	Description
`cardholder.created`	New cardholder registered
`cardholder.updated`	Cardholder info modified
`cardholder.kyc_approved`	KYC verification approved (optional)
`cardholder.kyc_rejected`	KYC verification failed (optional)
`cardholder.suspended`	Cardholder suspended
`cardholder.activated`	Cardholder reactivated

Example Webhook Payload

{
  "event": "cardholder.created",
  "data": {
    "cardholderId": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john@example.com",
    "status": "ACTIVE"
  },
  "timestamp": "2026-04-07T10:45:00+00:00"
}

Integration Checklist

Cardholder Management

GET /cardholders - List all cardholders
POST /cardholders - Create new cardholder
GET /cardholders/{id} - Get cardholder details
PATCH /cardholders/{id} - Update cardholder
DELETE /cardholders/{id} - Delete cardholder

KYC Verification (Optional)

POST /cardholders/{id}/kyc/session - Initiate KYC Verification

Getting Started

Core Concepts

Documentation Index

​Cardholders Overview

​Core Concepts

​What is a Cardholder?

​Cardholder Lifecycle

​Why Cardholders Matter

​Card Issuance

​KYC (Know Your Customer) — Optional

​Two Verification Paths

​Path 1: Self-Service (Cardholder Verifies Themselves)

​Path 2: Submit on Behalf (You Have the Documents)

​KYC Status Flow

​Verification Fee

​Cardholder Statuses

​Status Transitions

​Integration Patterns

​Pattern 1: Immediate Card Issuance (Recommended)

​Pattern 2: With Optional KYC

​Pattern 3: External ID Mapping

​Best Practices

​Error Handling

​Webhooks

​Cardholder Events

​Example Webhook Payload

​Integration Checklist

​Related Endpoints

​Cardholder Management

​KYC Verification (Optional)

Cardholders Overview

Core Concepts

What is a Cardholder?

Cardholder Lifecycle

Why Cardholders Matter

Card Issuance

KYC (Know Your Customer) — Optional

Two Verification Paths

Path 1: Self-Service (Cardholder Verifies Themselves)

Path 2: Submit on Behalf (You Have the Documents)

KYC Status Flow

Verification Fee

Cardholder Statuses

Status Transitions

Integration Patterns

Pattern 1: Immediate Card Issuance (Recommended)

Pattern 2: With Optional KYC

Pattern 3: External ID Mapping

Best Practices

Error Handling

Webhooks

Cardholder Events

Example Webhook Payload

Integration Checklist

Related Endpoints

Cardholder Management

KYC Verification (Optional)