Cardholders
Cardholders are the individuals who receive and use virtual cards issued through your business account. Before issuing any card, you must first create a cardholder profile with valid identification.Cardholder Lifecycle
Cardholder Statuses
| Status | Description | Can Issue Cards? |
|---|---|---|
ACTIVE | Cardholder is verified and can receive cards | Yes |
INACTIVE | Pending verification or activation | No |
SUSPENDED | Temporarily disabled (can be reactivated) | No |
DELETED | Permanently removed | No |
Creating a Cardholder
Required Information
Every cardholder must provide:| Field | Type | Description |
|---|---|---|
firstName | string | Legal first name (min 2 chars) |
lastName | string | Legal last name (min 2 chars) |
email | string | Valid email address |
phone | string | Phone in E.164 format (e.g., +12025551234) |
dateOfBirth | date | YYYY-MM-DD format |
gender | enum | MALE or FEMALE |
address | string | Street address (min 6 chars) |
city | string | City name |
state | string | State or province |
country | string | ISO 3166-1 alpha-2 code (e.g., US) |
documentType | enum | PASSPORT, NATIONAL_ID, or DRIVERS_LICENSE |
documentNumber | string | ID document number |
KYC Documents (Optional but Recommended)
For enhanced verification, provide document images:| Field | Description |
|---|---|
idFrontUrl | URL to front of ID document |
idBackUrl | URL to back of ID document |
idSelfieUrl | URL to selfie holding ID |
Document URLs should be publicly accessible or from your secure file storage.
Verification Status
Cardholders have a verification status based on their provided documents:| Status | Meaning |
|---|---|
VERIFIED | All documents provided and validated |
UNVERIFIED | No documents provided |
PENDING | Documents under review |
Cardholder Response
Best Practices
Validate data before submission
Validate data before submission
Validate email format, phone number format (E.164), and country code before submitting to avoid validation errors.
Store cardholder IDs
Store cardholder IDs
Store the
cardholderId in your database to link cardholders with your internal user records.Handle duplicate emails
Handle duplicate emails
Each cardholder email must be unique within your business. Check for existing cardholders before creating new ones.
Update cardholder info promptly
Update cardholder info promptly
If a cardholder’s information changes (address, phone), update it via the API to ensure card delivery and compliance.