| Method & Path | Purpose |
|---|
| POST /identity-validation | Validates that a name and document number match official records for a supported country. |
| POST /bank-validation | Validates that a customer owns the bank account provided, for supported countries. |
Both endpoints require HTTP Basic Authentication and are synchronous — there are no webhooks or async job IDs. Every response is returned in the same request/response cycle.
Encode shopId:apiKey as HTTP Basic Auth:
Authorization: Basic <base64(shopId:apiKey)>
| Header | Required | Description |
|---|
| Authorization | Yes | HTTP Basic Auth — Base64(shopId:apiKey). |
| Content-Type | Yes | Must be application/json. |
| x-test-mode | No | Set to true to simulate OK without running a real validation. Not billable. |
| x-request-id | No | Recommended trace ID for support correlation; no fixed format. |
Both endpoints use two response shapes, keyed off HTTP status:
| HTTP Status | Response Shape | Used For |
|---|
| 200 | MerchantValidationResponse | Validation ran to completion — read validationStatusCode. |
| 400 | MerchantValidationResponse | Request or shop configuration invalid — validation did not run. |
| 401 | MerchantApiErrorResponse | Missing or invalid credentials. |
| 429 | MerchantApiErrorResponse | Rate limit exceeded. |
| 500 | MerchantApiErrorResponse | Unexpected server or auth-processing error. |
📘 HTTP 400 and HTTP 200 can both return validationStatusCode: NOK — only HTTP 200 means the validation actually executed.
Returned in validationStatusCode on every HTTP 200 response
| Status | Meaning |
|---|
| OK | Validation passed. Premium shops may receive a compliance indicator in validationResultReason. |
| NOK | Validation completed but the data did not pass (e.g. name or document mismatch, invalid account). |
| NOT_VALIDATED | Validation could not be completed (timeout, temporary unavailability, or no record found). Retryable after a delay. |
Reason codes on NOK depend on the shop's subscription plan.
| Outcome | validationResultReason |
|---|
| Invalid document | CUSTOMER_INVALID_ID |
| Underage | CUSTOMER_INVALID_AGE |
| Deceased | CUSTOMER_NOT_ALIVE |
| Invalid status | CUSTOMER_INVALID_STATUS |
| Suspended (Brazil CPF) | CUSTOMER_SUSPENDED |
On NOK:
| Outcome | validationResultReason |
|---|
| Sanctions / international lists | CUSTOMER_IS_IN_INTERNATIONAL_LISTS |
On OK (compliance indicators):
| Indicator | validationResultReason |
|---|
| PEP | CUSTOMER_IS_PEP |
| PEP related | CUSTOMER_IS_PEP_RELATED |
Not filtered by subscription plan. Returned on HTTP 200 only.
| validationResultReason | Meaning |
|---|
| ACCOUNT_INVALID_FORMAT | Account number format is invalid. |
| ACCOUNT_INVALID | Account not found. |
| ACCOUNT_PERSONAL_ID_MISMATCH | Document does not match the account holder. |
| ACCOUNT_NAME_MISMATCH | Name does not match the account holder. |
| BANK_NOT_SUPPORTED | Bank code is not supported. |
| COUNTRY_NOT_SUPPORTED | Country is not supported for bank validation. |
| MISSING_REQUIRED_FIELD | A required field is missing. |
| PROVIDER_AUTH_ERROR | Upstream service authentication error. |
| PROVIDER_METHOD_UNAVAILABLE | Validation method temporarily unavailable. |
| PROVIDER_CONNECTION_ERROR | Upstream service connection error. |
| Field | Type | Required | Description |
|---|
| correlationId | string | Yes | Unique, non-empty identifier echoed in the response. |
| customer | MerchantIdentityCustomer | Yes | Customer identity details. |
| Field | Type | Required | Description |
|---|
| correlationId | string | Yes | Unique, non-empty identifier echoed in the response. |
| customer | MerchantBankCustomer | Yes | Customer identity details. |
| bankAccount | MerchantBankAccount | Yes | Bank account details to validate. |
| Country | Code | documentType |
|---|
| Argentina | AR | DNI |
| Brazil | BR | CPF |
| Chile | CL | RUT |
| Colombia | CO | CC |
| Costa Rica | CR | CI |
| Ecuador | EC | CED |
| Mexico | MX | CURP |
| Peru | PE | DNI |
| Country | Code | documentType |
|---|
| Argentina | AR | DNI or CUIT |
| Chile | CL | RUT |
| Colombia | CO | CC or NIT |
| Ecuador | EC | CED or RUC |
| Mexico | MX | RFC |
| Peru | PE | DNI |
| Country | bankName | accountAgencyNumber | accountTypeCode |
|---|
| AR | Not used | Not used | Not used |
| MX | Not used | Not used | Not used |
| CL | Required | Required | Required — 0002 checking; other codes savings |
| CO | Required | Required | Required — 0002 checking; NEQUI_WALLET for Nequi |
| EC | Required — listed banks only | Required | Required except banks 0023, 0010, 0016, 0020 |
| PE | Required unless 20-digit CCI | Required when bankName used | Not used |
| Endpoint | Supported Country Codes |
|---|
| POST /identity-validation | AR, BR, CL, CO, CR, EC, MX, PE |
| POST /bank-validation | AR, CL, CO, EC, MX, PE |
🚧 BR and CR are enabled for identity-validation only — a bank-validation request for either returns COUNTRY_NOT_SUPPORTED.
• Both endpoints are rate limited; exceeding the limit returns 429 with errorCode: RATE_LIMIT_EXCEEDED.
• Use exponential backoff on 429 and 500. The API does not emit Retry-After or X-RateLimit-* headers.
• NOT_VALIDATED is retryable after a delay, independent of HTTP-level retries.
• x-test-mode: true is available in staging and production.
• A valid request always returns validationStatusCode: OK and validationResultReason: null.
• Not billable — usage records are stored with isBillable: false.
• Shop configuration is not checked, but field and country validation still runs (e.g. an unsupported country still returns COUNTRY_NOT_SUPPORTED).
• Rate limits still apply.
