Skip to main content

​
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
Your App → Create Cardholder → Issue Cards
                              → (Optional) Verify Identity via KYC

​
Cardholder Lifecycle

​
Why Cardholders Matter

  1. Card Association: Cards are linked to specific cardholders
  2. Transaction Tracking: Monitor spending per individual
  3. Optional KYC: Verify identity when needed for compliance
  4. 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: '[email protected]',
  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.

​
Automated Verification Flow

FYATU uses automated identity verification with document scanning and liveness detection. The cardholder completes verification directly — no manual document handling required.

​
KYC Status Flow

StatusDescriptionCan Initiate Verification
UNSUBMITTEDNo verification startedYes
PENDINGVerification in progressNo (returns existing session)
ACCEPTEDIdentity verifiedNo
REJECTEDVerification failedYes (retry allowed)

​
Verification Fee

  • $0.60 per successful verification
  • Fee is held when the session is initiated
  • Charged only on approval; released on failure/abandonment

​
Cardholder Statuses

StatusDescriptionCan Issue Cards
ACTIVENormal operating stateYes
INACTIVETemporarily disabledNo
SUSPENDEDBlocked due to policyNo

​
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

Create cardholder and issue card in one flow: 
// 1. Create cardholder
const cardholder = await createCardholder({
  firstName: 'John',
  lastName: 'Smith',
  email: '[email protected]',
  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: '[email protected]',
  phone: '+12025551234',
  dateOfBirth: '1985-03-20',
  gender: 'MALE',
  country: 'US',
  externalId: 'user_12345' // Your database ID
});

​
Best Practices

  • 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)
  • Map cardholders to your user database
  • Use consistent ID format (e.g., user_123)
  • Makes lookups and reconciliation easier
  • 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

ErrorCauseResolution
DUPLICATE_EMAILEmail already registeredUse existing cardholder or different email
DUPLICATE_EXTERNAL_IDExternal ID already usedCheck existing cardholders first
CARDHOLDER_HAS_ACTIVE_CARDSCannot delete with cardsTerminate all cards before deleting
INSUFFICIENT_BALANCENot enough for verification feeTop up business wallet (KYC only)

​
Webhooks

​
Cardholder Events

EventDescription
cardholder.createdNew cardholder registered
cardholder.updatedCardholder info modified
cardholder.kyc_approvedKYC verification approved (optional)
cardholder.kyc_rejectedKYC verification failed (optional)
cardholder.suspendedCardholder suspended
cardholder.activatedCardholder reactivated

​
Example Webhook Payload

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

​
Integration Checklist

​
Cardholder Management

​
KYC Verification (Optional)