KYC y KYB por API
Verifica al comercio por API: persona física (KYC) o moral (KYB), documentos y prueba de vida.
Todo comercio debe verificarse antes de cobrar o transferir. Una persona física hace KYC y una persona moral hace KYB; el tipo sale del perfil del comercio y no se puede cambiar una vez iniciada la verificación.
Rutas
| Ruta | Qué hace |
|---|---|
GET /verification | Estado, documentos y observaciones. |
POST /verification/submissions | Crea o actualiza la verificación con person (KYC) o business (KYB). |
POST /verification/documents | Pide una URL de subida (15 min). |
POST /verification/documents/{documentId}/confirm | Confirma la subida y la envía a validación. |
GET /verification/documents | Resultado de la validación de cada documento. |
POST /verification/liveness-link | Solo KYC: URL de prueba de vida para el firmante. |
- not_started → link_pending: Link creado
- link_pending → link_completed: Link completado
- link_pending → expired: Vencido
- link_completed → pending_review: En revisión
- pending_review → approved: Aprobada
- pending_review → rejected: Rechazada
- pending_review → changes_requested: Más datos
- changes_requested → pending_review: Datos enviados
- changes_requested → approved: Aprobada
- changes_requested → rejected: Rechazada
Flujo
- Envía los datos con
POST /verification/submissionseIdempotency-Key. - Sube cada documento: pide la URL con
category,contentType,sizeBytesysha256, súbelo con el mismoContent-Typey confírmalo. Ambos POST exigenIdempotency-Key, igual que el de prueba de vida. - Solo KYC: pide la URL de prueba de vida y ábrela en el navegador del firmante (usa la cámara; no se puede hacer de servidor a servidor).
- Sigue el estado por webhook (
verification.*) o conGET /verification.
Valida los datos antes de enviarlos: países en ISO alpha-3, teléfonos en E.164 y fechas YYYY-MM-DD. Si la verificación sigue abierta, reenviar actualiza la misma solicitud (200) en lugar de crear otra (201).
En KYB el objeto business exige legalName y registrationNumber. Puedes enviar también country (ISO alpha-2, por defecto mx), ubos, directors y signers.
curl -X GET "$CLOBEPAY_API_BASE/verification" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
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"
}
]
}Documentos
- PDF, PNG o JPEG; máximo 15 MB.
- KYC:
identity,proofOfResidence. - KYB:
legalPresence,ownershipStructure,controlStructure,companyDetails.
Estados
pending_review, in_review, changes_requested, more_info_required, escalated, approved, approved_partial, rejected.
approvedhabilita links de pago y transferencias.more_info_requiredtrae la listapendingDocuments.approved_partialno habilita operar.
Errores
400 validation_failed(confields[]; una llave que no es camelCase daunknown_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: servicio de verificación no disponible; reintenta más tarde.