KYC Flow
Hosted, manual, and form-based cardholder verification.
KYC binds a real human identity to one or more virtual cards. Cards under BINs with requireKycCardholder: true cannot be issued until the cardholder is APPROVED.
Hosted (Didit)
Use this when you want Buvei to collect identity directly from the user.
Create the cardholder
POST /kyc/cardholders/auto. The request body is empty — identity is captured in the hosted flow.
The response includes id (kyc_…), kycStatus: "PENDING", and a verificationUrl.
Redirect the user
Send your end-user to verificationUrl. They'll complete document capture and a liveness check.
Wait for the webhook
Listen for CARDHOLDER_KYC_STATUS. When kycStatus is APPROVED, you can issue cards under this id.
For rejections, kycRejectReason carries the human-readable explanation. The cardholder must be re-submitted from scratch.
A KYC fee of 50¢ per attempt is debited from your wallet at creation time, regardless of the eventual outcome.
Form
Use this when you collect identity with your own form UI and want us to review the raw data — rather than submitting a finished third-party report (that's Manual).
Upload document images
POST /kyc/presignedUploads per image, then PUT each file to its uploadUrl (same two-step upload as Manual). Keep each returned fileToken.
Slots: idFrontToken (required, IDENTITY_PROOF), idBackToken (IDENTITY_PROOF, required when idType is ID_CARD), selfieToken (SELFIE_PROOF, optional), addressProofToken (ADDRESS_PROOF, optional). You must also upload 1–6 third-party verification reports and pass them in attachments.
Submit the full form
POST /kyc/cardholders/form with the complete cardholder identity — name, contact, personal details, identity document, address, source of funds — plus the image fileTokens and the required attachments.
The submission enters PENDING and is reviewed by our compliance team.
Wait for the webhook
Same as hosted — listen for CARDHOLDER_KYC_STATUS.
Limits
- One cardholder may back up to 2 cards by default (
maxCardCounton the cardholder record). - Cardholders connected to a restricted country or territory cannot be onboarded. The hosted flow rejects after the session completes (final state, fee still charged); the form flow rejects synchronously at submission (no fee). See Create KYC Cardholder (Form) › Restricted jurisdictions.
- The submitted attachment must be a PDF verification report generated by a third-party verification provider, such as Sumsub, Didit, or other KYC service providers.
- Each
fileTokenis single-use, consumed by the first manual submission that references it. - Each
uploadUrlis single-use and expires afterexpiresInseconds (default 600). - Maximum file size: 10 MB.
Cardholder lifecycle
| Status | Meaning | Cards issuable? |
|---|---|---|
PENDING | Submitted, awaiting verification. | ❌ |
APPROVED | Verification passed. | ✅ |
REJECTED | Verification failed (see kycRejectReason). Resubmit. | ❌ |