Volver a la referencia

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).

Estados de la verificación
  • 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
GET

Estado de la verificación

/api/v1/verification

Estado, documentos pendientes y comentarios, sin datos personales ni el costo.

Parámetros

Authorization
header
stringObligatorio

Bearer $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 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
GET/verification
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"
    }
  ]
}

POST

Enviar la verificación

/api/v1/verification/submissions

Crea o actualiza el expediente. Requiere Idempotency-Key.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

Idempotency-Key
header
stringObligatorio

1–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.

person
body
objectOpcional

KYC. Obligatoria para persona física. Campos internos en camelCase, todos obligatorios: firstName, lastName, email, phone, nationality, dateOfBirth, taxId, idType, idNumber, address, primaryPurpose, mostRecentOccupation, sourceOfFunds.

business
body
objectOpcional

KYB. Obligatoria para persona moral. legalName y registrationNumber son obligatorios.

country
body
stringOpcional

Solo KYB: país ISO alpha-2 (por defecto mx).

ubos
body
arrayOpcional

Solo KYB: beneficiarios finales.

directors
body
arrayOpcional

Solo KYB.

signers
body
arrayOpcional

Solo KYB.

Respuestas

  • HTTP 201Expediente creado o actualizado (también puede responder 200).

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 400validation_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 422person_type_mismatchEnviaste person en un comercio KYB, o business en uno KYC.
POST/verification/submissions
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 201
Expediente creado o actualizado (también puede responder 200).

POST

Pedir URL de subida

/api/v1/verification/documents

Devuelve una URL prefirmada (15 min) para subir el archivo.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

Idempotency-Key
header
stringObligatorio

1–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.

category
body
stringObligatorio

Categoría del documento. KYC: identity o proofOfResidence. KYB: legalPresence, ownershipStructure, controlStructure o companyDetails.

identity · proofOfResidence · legalPresence · ownershipStructure · controlStructure · companyDetails

contentType
body
stringObligatorio

Tipo del archivo.

application/pdf · image/png · image/jpeg

sizeBytes
body
numberObligatorio

Tamaño exacto en bytes, entero mayor a 0 (máx. 15 MB).

sha256
body
stringObligatorio

SHA-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 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 400idempotency_key_requiredFalta el header Idempotency-Key.
  • HTTP 400invalid_categorycategory falta o no corresponde al tipo de verificación (KYC o KYB).
  • HTTP 400invalid_content_typecontentType falta o no es application/pdf, image/png o image/jpeg.
  • HTTP 400invalid_sizesizeBytes falta o no es un entero mayor a 0.
  • HTTP 400file_too_largesizeBytes supera 15 MB.
  • HTTP 400invalid_sha256sha256 falta o no son 64 caracteres hexadecimales.
  • HTTP 409no_open_submissionLa verificación debe estar abierta: envía primero POST /verification/submissions.
POST/verification/documents
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"
}

POST

Confirmar un documento

/api/v1/verification/documents/{documentId}/confirm

Confirma la subida y la envía a validación.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

Idempotency-Key
header
stringObligatorio

1–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.

documentId
path
uuidObligatorio

UUID del documento.

Respuestas

  • HTTP 200Documento confirmado.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 400idempotency_key_requiredFalta el header Idempotency-Key.
  • HTTP 404not_foundEl documento no existe o no es tuyo. También si documentId no es un UUID.
POST/verification/documents/{documentId}/confirm
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 200
Documento confirmado.

GET

Listar documentos

/api/v1/verification/documents

Resultado de la validación de cada documento.

Parámetros

Authorization
header
stringObligatorio

Bearer $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 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
GET/verification/documents
curl -X GET "$CLOBEPAY_API_BASE/verification/documents" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
Documentos en camelCase.

GET

Consultar un documento

/api/v1/verification/documents/{documentId}

Detalle por UUID.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

documentId
path
uuidObligatorio

UUID del documento.

Respuestas

  • HTTP 200Detalle.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundEl documento no existe o no es tuyo. También si documentId no es un UUID.
GET/verification/documents/{documentId}
curl -X GET "$CLOBEPAY_API_BASE/verification/documents/5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
Detalle.