Back to the reference

Verification

KYC (individuals) and KYB (companies).

Every merchant must be verified before collecting or paying out. The type (KYC or KYB) comes from the merchant profile and cannot be changed once verification has started. Bodies and responses use camelCase, including nested objects (firstName, legalName, postalCode, providerStatus, livenessPending, createdAt).

Verification statuses
  • not_started → link_pending: Link created
  • link_pending → link_completed: Link completed
  • link_pending → expired: Expired
  • link_completed → pending_review: In review
  • pending_review → approved: Approved
  • pending_review → rejected: Rejected
  • pending_review → changes_requested: More info
  • changes_requested → pending_review: Info submitted
  • changes_requested → approved: Approved
  • changes_requested → rejected: Rejected
GET

Verification status

/api/v1/verification

Status, pending documents and comments, without personal data or the fee.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200Public view in camelCase. documents lists the verification documents (the same view as GET /verification/documents/{documentId}).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/verification
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"
    }
  ]
}

POST

Submit verification

/api/v1/verification/submissions

Creates or updates the file. Requires Idempotency-Key.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Idempotency-Key
header
stringRequired

1–255 characters. Required on this POST. The same key and body replay the original response (Idempotent-Replayed: true). A different body returns 422 idempotency_key_reuse.

person
body
objectOptional

KYC. Required for an individual. Nested fields in camelCase, all required: firstName, lastName, email, phone, nationality, dateOfBirth, taxId, idType, idNumber, address, primaryPurpose, mostRecentOccupation, sourceOfFunds.

business
body
objectOptional

KYB. Required for a company. legalName and registrationNumber are required.

country
body
stringOptional

KYB only: ISO alpha-2 country (defaults to mx).

ubos
body
arrayOptional

KYB only: ultimate beneficial owners.

directors
body
arrayOptional

KYB only.

signers
body
arrayOptional

KYB only.

Responses

  • HTTP 201File created or updated (may also return 200).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 400validation_failedData is missing or has an invalid format. fields[] lists each field with its code (required, invalid_format, invalid_value, or unknown_field when a key is not camelCase, e.g. first_name).
  • HTTP 422person_type_mismatchYou sent person for a KYB merchant, or business for a KYC merchant.
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"}}'

Response

HTTP 201
File created or updated (may also return 200).

POST

Request an upload URL

/api/v1/verification/documents

Returns a presigned URL (15 min) to upload the file.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Idempotency-Key
header
stringRequired

1–255 characters. Required on this POST. The same key and body replay the original response (Idempotent-Replayed: true). A different body returns 422 idempotency_key_reuse.

category
body
stringRequired

Document category. KYC: identity or proofOfResidence. KYB: legalPresence, ownershipStructure, controlStructure or companyDetails.

identity · proofOfResidence · legalPresence · ownershipStructure · controlStructure · companyDetails

contentType
body
stringRequired

File type.

application/pdf · image/png · image/jpeg

sizeBytes
body
numberRequired

Exact size in bytes, integer greater than 0 (max 15 MB).

sha256
body
stringRequired

SHA-256 of the file in hex (64 characters). Checked on confirm.

Responses

  • HTTP 201Document + upload URL, in camelCase (documentId, uploadUrl, uploadMethod, uploadHeaders, expiresAt).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 400idempotency_key_requiredThe Idempotency-Key header is missing.
  • HTTP 400invalid_categorycategory is missing or does not match the verification type (KYC or KYB).
  • HTTP 400invalid_content_typecontentType is missing or is not application/pdf, image/png or image/jpeg.
  • HTTP 400invalid_sizesizeBytes is missing or is not an integer greater than 0.
  • HTTP 400file_too_largesizeBytes exceeds 15 MB.
  • HTTP 400invalid_sha256sha256 is missing or is not 64 hex characters.
  • HTTP 409no_open_submissionThe verification must be open: send POST /verification/submissions first.
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"}'

Response

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

Confirm a document

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

Confirms the upload and sends it for validation.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Idempotency-Key
header
stringRequired

1–255 characters. Required on this POST. The same key and body replay the original response (Idempotent-Replayed: true). A different body returns 422 idempotency_key_reuse.

documentId
path
uuidRequired

Document UUID.

Responses

  • HTTP 200Document confirmed.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 400idempotency_key_requiredThe Idempotency-Key header is missing.
  • HTTP 404not_foundThe document does not exist or is not yours. Also if documentId is not a 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"

Response

HTTP 200
Document confirmed.

GET

List documents

/api/v1/verification/documents

Validation result for each document.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200Documents in camelCase.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/verification/documents
curl -X GET "$CLOBEPAY_API_BASE/verification/documents" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Documents in camelCase.

GET

Retrieve a document

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

Detail by UUID.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

documentId
path
uuidRequired

Document UUID.

Responses

  • HTTP 200Detail.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundThe document does not exist or is not yours. Also if documentId is not a UUID.
GET/verification/documents/{documentId}
curl -X GET "$CLOBEPAY_API_BASE/verification/documents/5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Detail.