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

Rutas de verificación
RutaQué hace
GET /verificationEstado, documentos y observaciones.
POST /verification/submissionsCrea o actualiza la verificación con person (KYC) o business (KYB).
POST /verification/documentsPide una URL de subida (15 min).
POST /verification/documents/{documentId}/confirmConfirma la subida y la envía a validación.
GET /verification/documentsResultado de la validación de cada documento.
POST /verification/liveness-linkSolo KYC: URL de prueba de vida para el firmante.
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

Flujo

  1. Envía los datos con POST /verification/submissions e Idempotency-Key.
  2. Sube cada documento: pide la URL con category, contentType, sizeBytes y sha256, súbelo con el mismo Content-Type y confírmalo. Ambos POST exigen Idempotency-Key, igual que el de prueba de vida.
  3. 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).
  4. Sigue el estado por webhook (verification.*) o con GET /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.

  • approved habilita links de pago y transferencias.
  • more_info_required trae la lista pendingDocuments.
  • approved_partial no habilita operar.

Errores

  • 400 validation_failed (con fields[]; una llave que no es camelCase da unknown_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.