How to Onboard Submerchants via API

November 12, 2025

Validate, query , and enable submerchants using Onboarding API endpoints.

Kushki provides a structured onboarding flow for Payment Service Providers (PSPs) to create submerchants while complying with operational and regulatory requirements. We explain how to validate submerchants (in batch or individually), interpret webhook notifications, check their status, and obtain credentials to operate in production.

For this process, there are three key endpoints

General Onboarding Flow

1. Submerchant Validation in Batch

This first endpoint or service allows you to submit one or more submerchants to validate their information before starting the onboarding process. In this initial step, submerchants are not created yet; we only verify that the data is well-structured and valid to proceed.

What to include? The required data includes: country, legal representatives here

Possible Responses

• INITIALIZED: Kushki received your request and is processing it.
• VALIDATION_FAILED: One or more submerchants have errors and cannot continue.

Additionally, the response will also include:

• submerchantId: Unique identifier assigned to the submerchant.

• submerchantName: Name of the submerchant sent in the request.

• status: Indicates the result of the individual submerchant validation. You may receive these responses:

1. VALID: The submerchant was successfully validated and can continue with the process.
2. INVALID: The submerchant contains errors in the data submitted and requires correction before continuing.

Once submitted for validation, you can check if the submerchant is ready for onboarding via a webhook notification.

1.1 Webhook Notification: Submerchant Status

Once the request is processed, Kushki will send a webhook notification with the status of each submerchant. This message can arrive individually or in a batch.

• Webhooks are optional and apply specifically to this second validation phase to notify the merchant about the process status.
• Notifications can be individual (one for each record) or in batch (when a block of records is completed).

Statuses you will receive via webhook

• READY_FOR_ONBOARDING: The submerchant passed validation and is ready to start the onboarding process.
• ERROR: The creation failed due to validation or processing errors. You must correct and resend the request.

Example of a successful webhook notification

[
  {
    "requestId": "d7eb557c-8385-4282-b196-6fb1ccec6a06",
    "submerchantId": "e5c40357-7bed-4e43-bd6c-4815e9341eaf",
    "status": "READY_FOR_ONBOARDING",
    "message": "Success"
  }
]

Example of a webhook notification with errors

[
  {
    "requestId": "d7eb557c-8385-4282-b196-6fb1ccec6a06",
    "submerchantId": "804e0d11-f298-4015-8662-1c31af577164",
    "status": "ERROR",
    "message": "Submerchant Onboarding Request has failed",
    "errorDetails": {
      "fields": {
        "operationCountry": "Operation Country not registered",
        "legalRepresentative": {
          "firstName": "Value is required",
          "dateBirth": "Date of Birth was invalid"
        }
      }
    }
  }
]

Consult the webhook documentation here

2. Get submerchant by requestId/submerchantId

Once the submerchant is approved, you can use this service. It allows you to query the onboarding status of a submerchant, either by a batch request or a specific submerchant.

How to use this endpoint?

• To query a batch request: send the requestId.
• To query a specific submerchant: send the submerchantId.

Possible Statuses

With this endpoint, you can query the different statuses of a submerchant during the process.

1. To determine if the submerchant entered onboarding or not::

• READY_FOR_ONBOARDING: The submerchant passed validation and is ready to start the onboarding process.
• ERROR: The creation failed due to validation or processing issues. You must correct and resend the request.

2. To check the onboarding status (only for approved submerchants):

2.1 Submerchant Document Upload

This endpoint allows PSPs to complete the pending PSP_PENDING_INFORMATION tasks related to Know Your Customer (KYC), enabling document upload via API.

Required Documents (MX):

The required documents to advance in the Mexico flow are: Constancia de Situación Fiscal (Certificate of Tax Status). Acta constitutiva (Articles of Incorporation). Legal Representative ID. Proof of Address.

Responses

If the submission was successful, the system returns a simple success confirmation, indicating that the document has been accepted for processing.

Result Webhook (Optional):

The final result of the document processing (e.g., Approved or Rejected) will be communicated via the webhookUrl provided in the upload request.

To obtain continuous and on-demand visibility of the most current status, query the main status endpoint (Get submerchant by requestId/submerchantId), which includes the pendingDocuments status indicating which documents are pending upload when the submerchant is in the PSP_PENDING_INFORMATION status.

Possible Webhook Statuses

Example of Document Webhook Notification response

{
  "submerchantId": "520d8a1c-c849-494e-a479-4aa2a5342a80",
  "documents": [
    {
      "document": "Certificate of Tax Status (CSF)",
      "status": "Approved"
    },
    {
      "document": "Proof of Address",
      "status": "Under Review"
    }
  ]
}

3. Get subermchantsIds

This service allows PSPs to obtain all submerchantIds in bulk. It works as a preparatory step for obtaining credentials.

What is required?

• The PSP’s API Key, generated from the Appian portal, is required

• Access is limited to submerchants associated with the authenticated PSP.

Expected Response

• The response will include an array with all the submerchantIds corresponding to the PSP.

Example response:

{
    "idPsp": "122",
    "submerchatIds": [
        "20000000101933870000",
        "20000000106045330000",
        "20000000102324298000",
        "20000000100416365000",
        "20000000106241217000",
        "20000000100908143000",
        "20000000108017426000",
    ]
}

4. Obtain Submerchant Credentials

This service allows PSPs to obtain the public and private credentials for one or more submerchants that have been successfully created in Kushki.

Authentication

• This service uses the PSP’s API Key, generated through the Appian portal
• It is designed for PSPs managing multiple submerchants within their ecosystem, providing secure access to the credentials for each authorized submerchant.

Important Considerations

• It is possible to include multiple merchantIds in the same request to obtain credentials for several submerchants simultaneously.

• The response will provide, for each valid submerchant: publicCredential and privateCredential: keys needed to execute transactional operations such as charges, subscriptions, among others.

• Credentials will only be delivered for submerchants correctly associated with the authenticated PSP.

• If an error occurs while processing any of the requested IDs, the corresponding submerchantId will be included along with a message detailing the reason:

  • The submerchant does not belong to the authenticated PSP: The ID is valid but is linked to another PSP.
  • Submerchant not found: The ID does not exist or the onboarding process has not concluded yet.