Skip to main content

​
Cardholders Overview

Cardholders are individuals who can hold virtual cards issued through your FYATU Issuing application. Before issuing cards, you must create cardholder profiles with identity information for compliance and fraud prevention.

​
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
  • Address Details: Street, city, state, country, postal code
  • Identity Documents: Document type, number, and verification images
  • KYC Status: Verification status for regulatory compliance
Your App → Create Cardholder → Submit KYC → Issue Cards → Card Usage

​
Cardholder Lifecycle

​
Why Cardholders Matter

  1. Regulatory Compliance: KYC requirements mandate identity verification
  2. Fraud Prevention: Verified cardholders reduce fraud risk
  3. Card Association: Cards are linked to specific cardholders
  4. Transaction Tracking: Monitor spending per individual

​
KYC (Know Your Customer)

​
KYC Status Flow

StatusDescriptionNext Steps
UNSUBMITTEDNo documents uploadedSubmit KYC via /cardholders/{id}/kyc
PENDINGDocuments under reviewWait for verification (usually 24-48 hours)
VERIFIEDIdentity confirmedReady to issue cards
REJECTEDVerification failedResubmit with valid documents

​
Document Requirements

FYATU supports three document types for identity verification:
Document TypeDescriptionBack Image Required
PASSPORTInternational passportNo
NATIONAL_IDGovernment-issued ID cardYes
DRIVER_LICENSEValid driver’s licenseYes

​
Image Guidelines

For successful KYC verification, ensure uploaded images meet these requirements:
  • Format: JPEG, PNG, or PDF
  • Resolution: Minimum 640x480 pixels
  • File Size: Maximum 10MB per image
  • Quality: Clear, readable, no blur or glare
  • Lighting: Well-lit, no shadows on document
  • Framing: Full document visible, no cropping
Rejected KYC submissions are often due to poor image quality. Ensure documents are clearly photographed before submission.

​
Cardholder Statuses

​
Status Definitions

StatusDescriptionCan Issue Cards
ACTIVENormal operating stateYes (if KYC verified)
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

​
Pattern 1: KYC Before Card Issuance

Collect and verify identity before allowing card creation:

​
Pattern 2: Immediate Card with Deferred KYC

Issue cards immediately, require KYC for higher limits: 
// 1. Create cardholder with basic info
const cardholder = await createCardholder({
  firstName: "James",
  lastName: "Wilson",
  email: "[email protected]",
  phone: "+12025551234",
  dateOfBirth: "1990-05-15",
  country: "US"
});

// 2. Issue limited card immediately
const card = await createCard({
  cardholderId: cardholder.id,
  type: "VIRTUAL",
  spendingLimit: 100 // Limited until KYC verified
});

// 3. Request KYC for full access
// User can upgrade later by completing KYC

​
Pattern 3: External ID Mapping

Link cardholders to your existing user database: 
// Create cardholder with your user ID
const cardholder = await createCardholder({
  firstName: "John",
  lastName: "Doe",
  email: "[email protected]",
  phone: "+12025551234",
  dateOfBirth: "1985-03-20",
  country: "US",
  externalId: "user_12345" // Your database ID
});

// Later, find cardholder by your ID
const cardholders = await listCardholders({
  search: "user_12345"
});

​
Best Practices

​
Data Collection

  • Gather all required fields upfront
  • Validate email format before submission
  • Use international phone format (+country code)
  • Verify date of birth for age requirements
  • Map cardholders to your user database
  • Use consistent ID format (e.g., user_123)
  • Makes lookups and reconciliation easier
  • Helps with customer support queries
  • Submit KYC documents early
  • Notify users of rejection reasons
  • Provide clear re-submission instructions
  • Track verification status via webhooks

​
Security Considerations

  1. Data Protection: Store cardholder data securely
  2. Access Control: Limit who can view sensitive info
  3. Audit Logging: Track all cardholder modifications
  4. PCI Compliance: Never store full card numbers

​
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
KYC_ALREADY_VERIFIEDCannot resubmit KYCContact support if update needed
INVALID_DOCUMENT_TYPEUnsupported documentUse PASSPORT, NATIONAL_ID, or DRIVER_LICENSE

​
Webhooks

​
Cardholder Events

Configure webhooks to receive real-time notifications:
EventDescription
cardholder.createdNew cardholder registered
cardholder.updatedCardholder info modified
cardholder.kyc.submittedKYC documents submitted
cardholder.kyc.verifiedKYC verification approved
cardholder.kyc.rejectedKYC verification failed

​
Example Webhook Payload

{
  "event": "cardholder.kyc.verified",
  "data": {
    "cardholderId": "ch_1a2b3c4d5e6f7890abcdef1234567890",
    "externalId": "user_12345",
    "firstName": "James",
    "lastName": "Wilson",
    "email": "[email protected]",
    "kycStatus": "VERIFIED",
    "verifiedAt": "2026-01-15T21:00:00+00:00"
  },
  "timestamp": "2026-01-15T21:00:01+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

  • POST /cardholders/{id}/kyc - Submit KYC documents

​
Cards (Coming Soon)

  • POST /cards - Issue card to cardholder
  • GET /cards - List cards by cardholder