Cardholders & KYC
A cardholder is the person a card belongs to, and it is the first object you create. Nothing — no account, no card — exists without one.
What matters here
Identity verification gates issuance. A cardholder whose kyc_status is not
approved cannot have a card activated, and no amount of retrying the card call
will change that. Design your onboarding flow around the verification state
machine rather than treating it as a step that usually succeeds.
You run verification; we record what you assert. The cardholder submits
documents to your own identity provider, and you report the outcome as an
attestation. Identity documents never pass through this API — see
identity documents. You read
kyc_status and react to cardholder.kyc_* webhooks.
The states and their meanings are in
core concepts. The practical rule is that
approved is the only state that unblocks issuance, and review_required needs
a human somewhere.
Verification is not the only gate. Issuance also needs the cardholder to
have an address and an identity_document on file — address_required and
identity_document_required respectively. Unlike kyc_status, both are your
data rather than a state machine, so the fix is a field, not a wait.
Two things worth getting right early
Do not poll for verification. It can take seconds or days depending on the
program and the individual. Subscribe to cardholder.kyc_approved and
cardholder.kyc_rejected.
Store your own identifier in reference. It is filterable and appears in
every webhook payload, which makes correlating an event back to your user
trivial. Retrofitting it later is painful.
In this section
- Creating a cardholder — the required fields, and why you can create before verifying
- KYC lifecycle and statuses — every state, what each gates, and how to report an outcome
- Identity documents — why documents never pass through this API, and what you retain
- Re-verification and remediation
— expiry,
review_required, and what happens to live cards