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).
- 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
Verification status
/api/v1/verification
Status, pending documents and comments, without personal data or the fee.
Parameters
AuthorizationstringRequiredBearer $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 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After.
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"
}
]
}Submit verification
/api/v1/verification/submissions
Creates or updates the file. Requires Idempotency-Key.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–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.
personobjectOptionalKYC. Required for an individual. Nested fields in camelCase, all required: firstName, lastName, email, phone, nationality, dateOfBirth, taxId, idType, idNumber, address, primaryPurpose, mostRecentOccupation, sourceOfFunds.
businessobjectOptionalKYB. Required for a company. legalName and registrationNumber are required.
countrystringOptionalKYB only: ISO alpha-2 country (defaults to mx).
ubosarrayOptionalKYB only: ultimate beneficial owners.
directorsarrayOptionalKYB only.
signersarrayOptionalKYB only.
Responses
- HTTP 201File created or updated (may also return 200).
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
validation_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 422
person_type_mismatchYou sent person for a KYB merchant, or business for a KYC merchant.
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 201File created or updated (may also return 200).Request an upload URL
/api/v1/verification/documents
Returns a presigned URL (15 min) to upload the file.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–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.
categorystringRequiredDocument category. KYC: identity or proofOfResidence. KYB: legalPresence, ownershipStructure, controlStructure or companyDetails.
identity · proofOfResidence · legalPresence · ownershipStructure · controlStructure · companyDetails
contentTypestringRequiredFile type.
application/pdf · image/png · image/jpeg
sizeBytesnumberRequiredExact size in bytes, integer greater than 0 (max 15 MB).
sha256stringRequiredSHA-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 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
idempotency_key_requiredThe Idempotency-Key header is missing. - HTTP 400
invalid_categorycategory is missing or does not match the verification type (KYC or KYB). - HTTP 400
invalid_content_typecontentType is missing or is not application/pdf, image/png or image/jpeg. - HTTP 400
invalid_sizesizeBytes is missing or is not an integer greater than 0. - HTTP 400
file_too_largesizeBytes exceeds 15 MB. - HTTP 400
invalid_sha256sha256 is missing or is not 64 hex characters. - HTTP 409
no_open_submissionThe verification must be open: send POST /verification/submissions first.
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"
}Confirm a document
/api/v1/verification/documents/{documentId}/confirm
Confirms the upload and sends it for validation.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–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.
documentIduuidRequiredDocument UUID.
Responses
- HTTP 200Document confirmed.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
idempotency_key_requiredThe Idempotency-Key header is missing. - HTTP 404
not_foundThe document does not exist or is not yours. Also if documentId is not a 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"Response
HTTP 200Document confirmed.List documents
/api/v1/verification/documents
Validation result for each document.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Responses
- HTTP 200Documents in camelCase.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/verification/documents" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200Documents in camelCase.Retrieve a document
/api/v1/verification/documents/{documentId}
Detail by UUID.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
documentIduuidRequiredDocument UUID.
Responses
- HTTP 200Detail.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundThe document does not exist or is not yours. Also if documentId is not a UUID.
curl -X GET "$CLOBEPAY_API_BASE/verification/documents/5b91d0e4-2c7a-4f18-9b36-8e0d4a1c6f22" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200Detail.Create a liveness link
/api/v1/verification/liveness-link
KYC only: URL for the signer.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Idempotency-KeystringRequired1–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.
Responses
- HTTP 201Liveness URL.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 400
idempotency_key_requiredThe Idempotency-Key header is missing. - HTTP 422
kyb_has_no_livenessKYB verification has no liveness check.
curl -X POST "$CLOBEPAY_API_BASE/verification/liveness-link" \ -H "Idempotency-Key: kyc-liveness-1" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 201{
"url": "https://{verification-host}/on/liveness/9c1e4a2b8f034c11",
"expiresAt": "2026-11-19T19:00:00.000Z"
}