Submerchant Validation in Batch

Este endpoint permite a los Payment Service Providers (PSPs) enviar uno o más subcomercios para una validación inicial antes de que entren al proceso de onboarding. Este paso todavía no crea ni hace onboarding de los subcomercios; solo verifica que la estructura de datos y el contexto operativo sean válidos.

Esta validación ayuda a asegurar que los registros de subcomercios cumplan el formato requerido y que el PSP sea elegible para el proceso de onboarding.

Solo los subcomercios que pasan las validaciones avanzan al proceso de onboarding. Los que fallan deben corregirse y volver a enviarse.

Cuerpo de la petición (JSON)

La solicitud debe incluir un array de subcomercios, cada uno con los datos relevantes: país de operación, representantes legales, beneficiarios finales (UBOs), correos y más.

📌 Importante
Ten en cuenta que submerchantName tiene un límite dinámico de caracteres según el prefijo configurado para tu PSP: MIN(18, 21 - length(PSP Prefix) - 1). El sistema convierte el texto a mayúsculas automáticamente y construye el Soft Descriptor. Revisa el detalle del campo más abajo para conocer las restricciones de caracteres.

Manejo de la respuesta

Si la validación fue exitosa, la respuesta incluye un campo status, que puede tener uno de los siguientes valores:

INITIALIZED – La solicitud fue recibida y está en procesamiento.

VALIDATION_FAILED – Al menos un subcomercio de la solicitud tiene errores, lo que impide procesarla con éxito.

Una vez que un subcomercio es aprobado y queda listo para el onboarding, cada solicitud genera un requestId único, que puedes usar para dar seguimiento al estado del proceso de creación.

Además, la respuesta entrega un array de subcomercios, cada uno con:

submerchantId – Un identificador único asignado al subcomercio.

submerchantName – El nombre del subcomercio.

status – Indica si el subcomercio pasó la validación:

VALID – El subcomercio se validó correctamente.

INVALID – El subcomercio tiene errores y requiere corrección.

Revisa la webhook notification. Ahí confirmas si el proceso de validación fue exitoso o rechazado.

curl --location '/onboarding/v1/submerchants/batch' \ --header 'X-Api-Key;' \ --header 'Content-Type: application/json' \ --data-raw '[ { "pspCustomerId": "20000000105771766000", "operationType": "CNP", "operationCountry": "ECU", "submerchantCountryTaxResidency": "ECU", "submerchantTaxId": "1791234567001", "submerchantLegalName": "COMERCIAL ECUADOR S.A.", "submerchantLegalEntityType": "Private", "submerchantName": "ECU API DOC", "submerchantAddress": "Av. Amazonas N25-23 y Colón", "submerchantCity": "Quito", "submerchantPostalCode": "170505", "submerchantUrl": "https://www.ejemplo.ec", "submerchantMcc": "5732", "legalRepresentativeName": "Juan Carlos", "legalRepresentativeFirstLastName": "Esquer", "legalRepresentativeSecondLastName": "Ramos", "legalRepresentativeDateBirth": "12/07/1990", "legalRepresentativeIdNumber": "1712345678", "legalRepresentativeSameAsUbo": true, "uboName": "Juan Carlos", "uboFirstLastName": "Esquer", "uboSecondLastName": "Ramos", "uboDateBirth": "12/07/1990", "ubo2Name": "", "ubo2FirstLastName": "", "ubo2SecondLastName": "", "ubo2DateBirth": "", "secondConcurrenceNeeded": true, "pspNotificationEmail": "test@kushkipagos.com", "openField": "" } ]'

{ "status": "INITIALIZED", "requestId": "5c91b0ee-677f-448e-b2e8-eb13bf2efcab", "message": "The submerchants are ready to be processed. We will notify you once all have been processed", "results": [ { "submerchantId": "5e9a859c-2112-4e8e-b819-2d18bc0f4d29", "submerchantName": "Kushki", "status": "VALID", "message": "The format is valid", "errors": [] }, { "submerchantId": "c0d99b38-9590-49fc-b348-899affe20726", "submerchantName": "Empresa SAC", "status": "VALID", "message": "The format is valid", "errors": [] } ] }

Cuerpo de la petición (JSON)

Manejo de la respuesta

Request

Responses

Submerchant Validation in Batch

Cuerpo de la petición (JSON)#

Manejo de la respuesta#

Request

Responses

Cuerpo de la petición (JSON)

Manejo de la respuesta