Buvei
API ReferenceKYC

Create KYC Cardholder (Auto)

Hosted KYC verification — Buvei collects identity directly from the user.

POST/open-api/v1/kyc/cardholders/auto

Creates a cardholder using our hosted KYC verification flow (powered by Didit). The response contains a verificationUrl that the end user must complete in their browser. Final approval/rejection is delivered via the CARDHOLDER_KYC_STATUS webhook.

Body

No body — identity is collected during the hosted verification session.

Response

idstring

Cardholder ID (kyc_…). Use this when issuing cards or querying KYC status.

kycStatusstring

Always PENDING immediately after creation. Final status arrives via webhook.

verificationUrlstring

Hosted verification URL. Redirect the end user here to complete identity capture.

feeinteger

Fee in cents debited from your wallet for this verification attempt (default 50 = $0.50).

modestring

Always AUTO for this endpoint.

Response
{
  "code": 0,
  "message": "SUCCESS",
  "data": {
    "id": "kyc_8f3a9c2b1d4e5f6a",
    "kycStatus": "PENDING",
    "verificationUrl": "https://verify.didit.me/session/abc123...",
    "fee": 50,
    "mode": "AUTO"
  }
}

The KYC fee is debited when the verification reaches a final state (APPROVED or REJECTED), not at creation time. A fee is charged per attempt, regardless of outcome — see your contract for refund policy on rejected verifications.

Restricted jurisdictions. We do not onboard cardholders whose identity document is issued by a restricted country or territory. This is enforced after the hosted session completes: even when the verification provider returns a pass, the cardholder is set to REJECTED with

kycRejectReason: "The current country is not supported for KYC at this time"

Because this is a final state, the KYC fee is still charged. If your user base includes restricted jurisdictions, prefer POST /kyc/cardholders/form, which rejects synchronously at submission time and is not billed.

What to do next

  • Redirect the user to verificationUrl.
  • Listen for CARDHOLDER_KYC_STATUS to learn when the cardholder transitions to APPROVED or REJECTED.
  • Cards may only be issued against an APPROVED cardholder.

On this page

Body
Response
What to do next