Submerchant Validation in Batch

This endpoint allows Payment Service Providers (PSPs) to submit one or more submerchants for initial validation before they can enter to the onboarding process. This step does not create or onboard submerchants yet; It only checks that the data structure and operational context are valid.

This validation helps ensure that submerchant records meet the required format and that the PSP is eligible to the onboarding process.

Only submerchants that pass the validations will proceed to the actual onboarding process. Those that fail must be corrected and resubmitted.

Request Body (JSON)

The request must include an array of submerchants, each containing relevant details such as country of operation, legal representatives, ultimate beneficial owners (UBOs), emails, and more.

📌 Important
Please note that submerchantName has a dynamic character limit based on your PSP's configured prefix: MIN(18, 21 - length(PSP Prefix) - 1). The system automatically normalizes the text to uppercase and builds the Soft Descriptor. See the field details below for character restrictions.

Response Handling

If the validation was successful the response includes a status field, which can have one of the following values:

INITIALIZED – The request has been received and is being processed.

VALIDATION_FAILED – At least one submerchant in the request contains errors, preventing successful processing.

Once a submerchant is approved and ready for onboarding, each request generates a unique requestId, which can be used to track the status of the creation process.

Additionally, the response provides an array of submerchants, each with:

submerchantId – A unique identifier assigned to the submerchant.

submerchantName – The name of the submerchant.

status – Indicates if the submerchant passed validation:

VALID – The submerchant was successfully validated.

INVALID – The submerchant contains errors and requires correction.

Make sure to check the webhook notification. This will confirm whether the validation process was successful or rejected.

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": "ECU", "submerchantCountryTaxResidency": "ECU", "submerchantTaxId": "1791234567001", "submerchantLegalName": "COMERCIAL ECUADOR S.A.", "submerchantLegalEntityType": "Private", "submerchantName": "ECU API DOC", "submerchantAddress": "Av. Amazonas N25-23 y Colon", "submerchantCity": "Quito", "submerchantPostalCode": "170505", "submerchantUrl": "https://www.ejemplo.ec", "submerchantMcc": "5732", "legalRepresentativeName": "Juan Carlos", "legalRepresentativeFirstLastName": "Esquer", "legalRepresentativeSecondLastName": "Ramos", "legalRepresentativeDateBirth": "12/07/1990", "legalRepresentativeNationality": "ECU", "legalRepresentativeIdNumber": "1712345678", "legalRepresentativeSameAsUbo": true, "uboName": "Juan Carlos", "uboFirstLastName": "Esquer", "uboSecondLastName": "Ramos", "uboDateBirth": "12/07/1990", "uboNationality": "ECU", "ubo2Name": "", "ubo2FirstLastName": "", "ubo2SecondLastName": "", "ubo2DateBirth": "", "ubo2Nationality": null, "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": [] } ] }

Request Body (JSON)#

Response Handling#

Request

Responses

Request Body (JSON)

Response Handling