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.

Card Present (CP) / Kushki POS acquiring fields

When operationType is CP, additional fields are required to register the submerchant in Kushki POS.

When operationType is CP, the usesKushkiPos field is required.

If usesKushkiPos is true, these fields are also required: operationMode emails, paymentOptions, paymentTypes, terminalCount, storeName and storeAddress.

If usesKushkiPos is false, or if operationType is not CP, those fields should not be sent.

📌 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 '/onboarding/v1/submerchants/batch' \ --header 'X-Api-Key;' \ --header 'Content-Type: application/json' \ --data-raw '[ { "pspCustomerId": "20000000105771766000", "operationType": "CNP", "operationCountry": "MEX", "submerchantCountryTaxResidency": "MEX", "submerchantTaxId": "ABC120315XX1", "submerchantLegalName": "COMERCIAL MEXICO S.A. DE C.V.", "submerchantLegalEntityType": "Private", "submerchantName": "MEX API DOC", "submerchantAddress": "Av. Insurgentes Sur 1602", "submerchantCity": "Ciudad de México", "submerchantPostalCode": "03940", "submerchantUrl": "https://www.ejemplo.mx", "submerchantMcc": "5732", "legalRepresentativeName": "Juan Carlos", "legalRepresentativeFirstLastName": "Esquer", "legalRepresentativeSecondLastName": "Ramos", "legalRepresentativeDateBirth": "12/07/1990", "legalRepresentativeIdNumber": "EQRJ900712HDFRR01", "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 México", "status": "VALID", "message": "The format is valid", "errors": [] }, { "submerchantId": "c0d99b38-9590-49fc-b348-899affe20726", "submerchantName": "Empresa México SA de CV", "status": "VALID", "message": "The format is valid", "errors": [] } ] }

Request Body (JSON)#

Card Present (CP) / Kushki POS acquiring fields#

Response Handling#

Request

Responses

Request Body (JSON)

Card Present (CP) / Kushki POS acquiring fields

Response Handling