Submerchant Validation in Batch
https://api-uat.kushkipagos.com
https://api-uat.kushkipagos.com
https://api-uat.kushkipagos.com
https://api-uat.kushkipagos.com
POST
/onboarding/v1/submerchants/batch
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)
Campos de adquirencia para Card Present (CP) / Kushki POS
operationType es CP, se requieren campos adicionales para registrar el subcomercio en Kushki POS.CP, el campo usesKushkiPos es obligatorio.usesKushkiPos es true, también son obligatorios estos campos: operationMode, emails, paymentTypes, enableTipping, terminalCount, storeName y storeAddress.usesKushkiPos es false, o si operationType no es CP, esos campos no deben enviarse.📌 Importante
Ten en cuenta quesubmerchantNametiene 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
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.requestId único, que puedes usar para dar seguimiento al estado del proceso de creación.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.
Request
Header Params
Body Params application/json
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location 'https://api-uat.kushkipagos.com/onboarding/v1/submerchants/batch' \
--header 'X-Api-Key;' \
--header 'Content-Type: application/json' \
--data-raw '[
{
"pspCustomerId": "20000000105771766000",
"operationType": "CNP",
"operationCountry": "COL",
"submerchantCountryTaxResidency": "COL",
"submerchantTaxId": "9001234567",
"submerchantLegalName": "COMERCIAL COLOMBIA S.A.S.",
"submerchantLegalEntityType": "Private",
"submerchantName": "COL API DOC",
"submerchantAddress": "Calle 93 # 11A - 28",
"submerchantCity": "Bogotá",
"submerchantPostalCode": "110221",
"submerchantUrl": "https://www.ejemplo.co",
"submerchantMcc": "5732",
"legalRepresentativeName": "Juan Carlos",
"legalRepresentativeFirstLastName": "Esquer",
"legalRepresentativeSecondLastName": "Ramos",
"legalRepresentativeDateBirth": "12/07/1990",
"legalRepresentativeIdNumber": "1018456789",
"legalRepresentativeSameAsUbo": true,
"uboName": "Juan Carlos",
"uboFirstLastName": "Esquer",
"uboSecondLastName": "Ramos",
"uboDateBirth": "12/07/1990",
"ubo2Name": "",
"ubo2FirstLastName": "",
"ubo2SecondLastName": "",
"ubo2DateBirth": "",
"secondConcurrenceNeeded": true,
"pspNotificationEmail": "test@kushkipagos.com",
"openField": ""
}
]'Response Response Example
200 - INITIALIZED (successful response)
{
"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 Colombia",
"status": "VALID",
"message": "The format is valid",
"errors": []
},
{
"submerchantId": "c0d99b38-9590-49fc-b348-899affe20726",
"submerchantName": "Empresa Bogotá SAS",
"status": "VALID",
"message": "The format is valid",
"errors": []
}
]
}Modified at 2026-09-28 17:05:55