Verificación
KYC (persona física) y KYB (persona moral).
Todo comercio debe verificarse antes de cobrar o transferir. El tipo (KYC o KYB) sale del perfil del comercio y no se puede cambiar una vez iniciada la verificación. Los cuerpos y respuestas usan camelCase, incluidos los objetos anidados (firstName, legalName, postalCode, providerStatus, livenessPending, createdAt).
- 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
Estado de la verificación
/api/v1/verification
Estado, documentos pendientes y comentarios, sin datos personales ni el costo.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Respuestas
- HTTP 200Vista pública en camelCase. documents trae los documentos de la verificación (la misma vista que GET /verification/documents/{documentId}).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After.
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"
}
]
}Enviar la verificación
/api/v1/verification/submissions
Crea o actualiza el expediente. Requiere Idempotency-Key.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.
personobjectOpcionalKYC. Obligatoria para persona física. Campos internos en camelCase, todos obligatorios: firstName, lastName, email, phone, nationality, dateOfBirth, taxId, idType, idNumber, address, primaryPurpose, mostRecentOccupation, sourceOfFunds.
businessobjectOpcionalKYB. Obligatoria para persona moral. legalName y registrationNumber son obligatorios.
countrystringOpcionalSolo KYB: país ISO alpha-2 (por defecto mx).
ubosarrayOpcionalSolo KYB: beneficiarios finales.
directorsarrayOpcionalSolo KYB.
signersarrayOpcionalSolo KYB.
Respuestas
- HTTP 201Expediente creado o actualizado (también puede responder 200).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
validation_failedFaltan datos o tienen formato inválido. fields[] trae cada campo con su código (required, invalid_format, invalid_value o unknown_field si una llave no es camelCase, p. ej. first_name). - HTTP 422
person_type_mismatchEnviaste person en un comercio KYB, o business en uno KYC.
curl -X POST "$CLOBEPAY_API_BASE/verification/submissions" \ -H "Idempotency-Key: kyc-MID000847-1" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"person":{"firstName":"Ana","lastName":"Pérez","email":"ana.perez@comercioatlas.mx","phone":"+525512345678","nationality":"MEX","dateOfBirth":"1990-04-12","taxId":"PEXA900412XXX","idType":"id_card","idNumber":"XXXX0000","address":{"line1":"Av. Reforma 1","city":"CDMX","state":"CDMX","postalCode":"06600","country":"MEX"},"primaryPurpose":"business_payments","mostRecentOccupation":"Comerciante","sourceOfFunds":"business_income"}}'Respuesta
HTTP 201Expediente creado o actualizado (también puede responder 200).Pedir URL de subida
/api/v1/verification/documents
Devuelve una URL prefirmada (15 min) para subir el archivo.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.
categorystringObligatorioCategoría del documento. KYC: identity o proofOfResidence. KYB: legalPresence, ownershipStructure, controlStructure o companyDetails.
identity · proofOfResidence · legalPresence · ownershipStructure · controlStructure · companyDetails
contentTypestringObligatorioTipo del archivo.
application/pdf · image/png · image/jpeg
sizeBytesnumberObligatorioTamaño exacto en bytes, entero mayor a 0 (máx. 15 MB).
sha256stringObligatorioSHA-256 del archivo en hexadecimal (64 caracteres). Se comprueba al confirmar.
Respuestas
- HTTP 201Documento + URL de subida, en camelCase (documentId, uploadUrl, uploadMethod, uploadHeaders, expiresAt).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
idempotency_key_requiredFalta el header Idempotency-Key. - HTTP 400
invalid_categorycategory falta o no corresponde al tipo de verificación (KYC o KYB). - HTTP 400
invalid_content_typecontentType falta o no es application/pdf, image/png o image/jpeg. - HTTP 400
invalid_sizesizeBytes falta o no es un entero mayor a 0. - HTTP 400
file_too_largesizeBytes supera 15 MB. - HTTP 400
invalid_sha256sha256 falta o no son 64 caracteres hexadecimales. - HTTP 409
no_open_submissionLa verificación debe estar abierta: envía primero POST /verification/submissions.
curl -X POST "$CLOBEPAY_API_BASE/verification/documents" \ -H "Idempotency-Key: kyc-doc-identity-1" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"category":"identity","contentType":"image/jpeg","sizeBytes":204800,"sha256":"ad6323fe1567c889e17037c023a21b15a38fb59c4df20017e4ba4df2cb61e8db"}'Respuesta
HTTP 201{
"documentId": "5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22",
"category": "identity",
"status": "pending_upload",
"contentType": "image/jpeg",
"sizeBytes": 204800,
"uploadUrl": "https://clobepay-staging-documents.s3.us-east-1.amazonaws.com/verification/1e5ae273-6872-49f0-aeec-fe792fc40534/8b8ab918-0782-48a6-9fe1-210e3405d24f/5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost&X-Amz-Signature=f766d06d2dbd878d…",
"uploadMethod": "PUT",
"uploadHeaders": {
"Content-Type": "image/jpeg"
},
"expiresAt": "2026-11-19T18:15:00.000Z"
}Confirmar un documento
/api/v1/verification/documents/{documentId}/confirm
Confirma la subida y la envía a validación.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.
documentIduuidObligatorioUUID del documento.
Respuestas
- HTTP 200Documento confirmado.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
idempotency_key_requiredFalta el header Idempotency-Key. - HTTP 404
not_foundEl documento no existe o no es tuyo. También si documentId no es un UUID.
curl -X POST "$CLOBEPAY_API_BASE/verification/documents/5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22/confirm" \ -H "Idempotency-Key: kyc-doc-identity-1-confirm" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Documento confirmado.Listar documentos
/api/v1/verification/documents
Resultado de la validación de cada documento.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Respuestas
- HTTP 200Documentos en camelCase.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/verification/documents" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Documentos en camelCase.Consultar un documento
/api/v1/verification/documents/{documentId}
Detalle por UUID.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
documentIduuidObligatorioUUID del documento.
Respuestas
- HTTP 200Detalle.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundEl documento no existe o no es tuyo. También si documentId no es un UUID.
curl -X GET "$CLOBEPAY_API_BASE/verification/documents/5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Detalle.Crear prueba de vida
/api/v1/verification/liveness-link
Solo KYC: URL para el firmante.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Idempotency-KeystringObligatorio1–255 caracteres. Obligatoria en este POST. Si repites la misma llave y el mismo cuerpo, se devuelve la respuesta original (Idempotent-Replayed: true). Si el cuerpo cambia, 422 idempotency_key_reuse.
Respuestas
- HTTP 201URL de prueba de vida.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 400
idempotency_key_requiredFalta el header Idempotency-Key. - HTTP 422
kyb_has_no_livenessLa verificación KYB no lleva prueba de vida.
curl -X POST "$CLOBEPAY_API_BASE/verification/liveness-link" \ -H "Idempotency-Key: kyc-liveness-1" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 201{
"url": "https://{verification-host}/on/liveness/9c1e4a2b8f034c11",
"expiresAt": "2026-11-19T19:00:00.000Z"
}