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

Verification routes
RouteWhat it does
GET /verificationStatus, documents and remarks.
POST /verification/submissionsCreates or updates the verification with person (KYC) or business (KYB).
POST /verification/documentsRequests an upload URL (15 min).
POST /verification/documents/{documentId}/confirmConfirms the upload and sends it to validation.
GET /verification/documentsValidation result for each document.
POST /verification/liveness-linkKYC only: liveness URL for the signer.

Flow

  1. Send the data with POST /verification/submissions and an Idempotency-Key.
  2. Upload each document: request the URL with category, contentType, sizeBytes and sha256, upload it with the same Content-Type and confirm it. Both POSTs require Idempotency-Key, as does the liveness one.
  3. 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).
  4. Track the status by webhook (verification.*) or with GET /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.

  • approved enables payment links and payouts.
  • more_info_required includes the pendingDocuments list.
  • approved_partial does not enable operations.

Errors

  • 400 validation_failed (with fields[]; a key that is not camelCase gives 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: the verification service is unavailable; retry later.