KYC and KYB via API
Verify the merchant via API: individual (KYC) or company (KYB), documents and liveness.
Every merchant must be verified before collecting or paying out. An individual goes through KYC and a company through KYB; the type comes from the merchant profile and cannot change once the verification has started.
Routes
| Route | What it does |
|---|---|
GET /verification | Status, documents and remarks. |
POST /verification/submissions | Creates or updates the verification with person (KYC) or business (KYB). |
POST /verification/documents | Requests an upload URL (15 min). |
POST /verification/documents/{documentId}/confirm | Confirms the upload and sends it to validation. |
GET /verification/documents | Validation result for each document. |
POST /verification/liveness-link | KYC only: liveness URL for the signer. |
Flow
- Send the data with
POST /verification/submissionsand anIdempotency-Key. - Upload each document: request the URL with
category,contentType,sizeBytesandsha256, upload it with the sameContent-Typeand confirm it. Both POSTs requireIdempotency-Key, as does the liveness one. - KYC only: request the liveness URL and open it in the signer’s browser (it uses the camera; it cannot be done server to server).
- Track the status by webhook (
verification.*) or withGET /verification.
Validate the data before sending it: ISO alpha-3 countries, E.164 phone numbers and YYYY-MM-DD dates. While the verification is open, resending updates the same request (200) instead of creating another one (201).
In KYB the business object requires legalName and registrationNumber. You may also send country (ISO alpha-2, defaults to mx), ubos, directors and signers.
curl -X GET "$CLOBEPAY_API_BASE/verification" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"id": "3a9e1c70-6b24-4d8f-a2e5-1c47b08d93f6",
"kind": "kyc",
"mode": "api",
"status": "pending_review",
"providerStatus": null,
"livenessPending": false,
"pendingDocuments": [],
"providerComment": null,
"createdAt": "2026-11-19T18:00:00.000Z",
"updatedAt": "2026-11-19T18:00:00.000Z",
"documents": [
{
"documentId": "5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22",
"category": "identity",
"status": "sent",
"contentType": "image/jpeg",
"sizeBytes": 204800,
"ocr": null,
"manualReview": false,
"createdAt": "2026-11-19T18:02:00.000Z",
"updatedAt": "2026-11-19T18:05:00.000Z"
}
]
}Documents
- PDF, PNG or JPEG; up to 15 MB.
- KYC:
identity,proofOfResidence. - KYB:
legalPresence,ownershipStructure,controlStructure,companyDetails.
Statuses
pending_review, in_review, changes_requested, more_info_required, escalated, approved, approved_partial, rejected.
approvedenables payment links and payouts.more_info_requiredincludes thependingDocumentslist.approved_partialdoes not enable operations.
Errors
400 validation_failed(withfields[]; a key that is not camelCase givesunknown_field),409 verification_already_approved,422 person_type_mismatch.400 invalid_category,400 invalid_content_type,400 invalid_size,400 file_too_large,400 invalid_sha256,409 no_open_submission,409 upload_missing.400 liveness_already_completed,422 kyb_has_no_liveness.503 verification_unavailable: the verification service is unavailable; retry later.