Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

FieldDescription
idUnique cardholder ID (e.g. CH1a2b3c4d5e6f)
externalIdYour own ID for this person — map to your user database
Personal infoFirst name, last name, email, phone, date of birth, gender
AddressStreet, city, state, country, postal code
statusAccount status: ACTIVE, INACTIVE, or SUSPENDED
kycStatusIdentity verification status — must be ACCEPTED to issue cards
metadataCustom key-value data from your platform

​
Lifecycle

​
Statuses

​
Account Status

StatusDescription
ACTIVENormal operating state
INACTIVETemporarily disabled
SUSPENDEDBlocked due to policy
Suspending a cardholder does not automatically freeze their cards. Manage card statuses separately if needed.

​
KYC Status

kycStatusDescriptionCan Issue Cards
UNSUBMITTEDNo verification startedNo
PENDINGVerification in progressNo
ACCEPTEDIdentity verifiedYes
REJECTEDVerification failed — retry allowedNo
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

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

CodeCauseResolution
DUPLICATE_EMAILEmail already registeredUse existing cardholder or a different email
DUPLICATE_EXTERNAL_IDExternal ID already usedCheck existing cardholders first
CARDHOLDER_NOT_VERIFIEDKYC not acceptedComplete KYC verification before issuing cards
CARDHOLDER_HAS_ACTIVE_CARDSCannot delete with active cardsTerminate all cards before deleting

​
Webhook Events

EventDescription
cardholder.createdNew cardholder registered
cardholder.updatedCardholder info modified
cardholder.suspendedCardholder suspended
cardholder.activatedCardholder reactivated

​
Endpoints