Appian - Submerchant Register - Kushki Developer Portal

Kushki provides an API for Payment Service Providers (PSPs) to create multiple submerchants in a single operation. This API streamlines the onboarding process, allowing businesses to scale efficiently while maintaining compliance with legal and operational requirements.

API Base URL

Environment	URL
Production	`https://api.kushkipagos.com`
Test	`https://core-uat-us-east-1.kushkipagos.com`

Main Onboarding Endpoints

Submerchant Creation in Batch (POST /onboarding/v1/submerchants/batch) — Submit one or more submerchants for initial validation. This step checks structural and operational data but does not onboard the submerchants yet.

1.1. Webhook Notification: Submerchant Status — Once the request is processed, Kushki sends a webhook for each submerchant with their onboarding status. This notification can be individual or batched.

If the status is READY_FOR_ONBOARDING, proceed to the next step to track onboarding progress (step 2).

If the status is ERROR, review the details, correct the data, and resend the request using step 1.

Get Submerchant by requestId or submerchantId (GET /onboarding/v1/submerchants) — Use this endpoint to monitor the onboarding progress of a submerchant after receiving the READY_FOR_ONBOARDING status.

Get All Submerchant IDs (GET /onboarding/v1/psp/submerchantIds) — Retrieve all submerchantIds for one or more submerchants that have completed the onboarding process using the API Key from Appian.

Get Credentials for Submerchants (POST /onboarding/v1/submerchants/credentials) — Retrieve the transactional credentials (public and private keys) for submerchants that have completed onboarding.

Specialized Onboarding Endpoint

Important: This endpoint is only for submerchants with the Operation Country: Mexico (MX).

This endpoint supports conditional or specific tasks necessary to advance the onboarding process in certain contexts.

Submerchant Document Upload (POST /upload/v1/submerchant/files) — Submit required documents to complete specific KYC tasks. This endpoint is currently exclusive to Mexico (MX).

Submerchant Register Process

PSP sends a batch creation request with multiple submerchants. Kushki validates the request format.

The batch will only be processed if all submerchants pass validation.

If valid, submerchants move into onboarding.

If invalid, errors must be corrected and the request resubmitted.

Kushki processes the request and returns a requestId along with other details.

PSP queries the status using the requestId or submerchantId to check individual submerchant onboarding progress.

🔔 Webhook Notifications via Appian

Kushki can automatically notify PSPs of submerchant onboarding results via webhook, based on the configuration established in Appian, as part of the commercial agreement during affiliation.

📌 Configuration Highlights

Webhook setup is done in the PSP Portal in Appian.

Each PSP can enable or disable webhook notifications and configure:

Notification type: batch or individual

Event scope for individual mode:

Notify only errors

Notify only successes

Notify all results

The target URL where events should be sent

📬 Notification Logic

If batch is enabled → a summary is sent once the full batch is processed.

If individual is enabled → Kushki can notify:

✅ All submerchant results

❌ Only errors

✔️ Only successes

🔔 Webhook Payload Examples for Submerchant Creation

Depending on the configuration (individual or batch), Kushki will send webhook notifications to the PSP's configured URL with the status of the submerchant onboarding process.

Response Handling

When a batch creation request is submitted, Kushki validates the format of each submerchant in the payload. The response includes a status field with one of the following values:

Status	Description
`READY_FOR_ONBOARDING`	The submerchant has passed validation and is ready for the onboarding process.
`ERROR`	The submerchant creation failed due to validation or processing issues. The issue must be corrected and the creation request resubmitted.

Batch Webhook Notification — Successful Submerchants

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

📦 Batch Webhook Notification — With Errors

[
  {
    "requestId": "d7eb557c-8385-4282-b196-6fb1ccec6a06",
    "submerchantId": "e5c40357-7bed-4e43-bd6c-4815e9341eaf",
    "status": "ERROR",
    "message": "Submerchant Onboarding Request has failed",
    "errorDetails": {
      "message": "Submerchant Onboarding Request has failed",
      "fields": {
        "customerId": "Select a valid operation country",
        "operationType": "Select a valid operation country",
        "operationCountry": "Operation Country not registered",
        "legalRepresentative": {
          "firstName": "Value is required",
          "firstLastName": "Value is required",
          "secondLastName": "Second Last Name is required",
          "dateBirth": "Date of Birth was invalid, select a new date",
          "disabled": false
        },
        "ubo": {
          "disabled": true
        }
      }
    }
  },
  {
    "requestId": "d7eb557c-8385-4282-b196-6fb1ccec6a06",
    "submerchantId": "bf5cbdd3-625f-4734-9559-6cf208f9e2de",
    "status": "ERROR",
    "message": "Submerchant Onboarding Request has failed",
    "errorDetails": {
      "message": "Submerchant Onboarding Request has failed",
      "fields": {
        "customerId": "Select a valid operation country",
        "operationType": "Select a valid operation country",
        "operationCountry": "Operation Country not registered",
        "legalRepresentative": {
          "firstName": "Value is required",
          "firstLastName": "Value is required",
          "secondLastName": "Second Last Name is required",
          "dateBirth": "Date of Birth was invalid, select a new date",
          "disabled": false
        },
        "ubo": {
          "disabled": true
        }
      }
    }
  }
]

📦 Individual Webhook Notification — With Error

[
  {
    "requestId": "98d7e553-a1fd-43e5-ad7a-8e019e76745c",
    "submerchantId": "804e0d11-f298-4015-8662-1c31af577164",
    "status": "ERROR",
    "message": "Submerchant Onboarding Request has failed",
    "errorDetails": {
      "message": "Submerchant Onboarding Request has failed",
      "fields": {
        "customerId": "Select a valid operation country",
        "operationType": "Select a valid operation country",
        "operationCountry": "Operation Country not registered",
        "legalRepresentative": {
          "firstName": "Value is required",
          "firstLastName": "Value is required",
          "secondLastName": "Second Last Name is required",
          "dateBirth": "Date of Birth was invalid, select a new date",
          "disabled": false
        },
        "ubo": {
          "disabled": true
        }
      }
    }
  }
]

Payload for Document Upload (MX)

Important: This endpoint is only for submerchants with the Operation Country: Mexico (MX).

This webhook is sent to the webhookUrl specified in the document upload request (POST /upload/v1/submerchant/files) once the documents have been processed and reviewed.

The payload contains the submerchantId and the status of each uploaded document (Approved, Under Review, or Rejected). For continuous, on-demand visibility of the most current status, query the main status endpoint (GET /onboarding/v1/submerchants), which includes the pendingDocuments array when the submerchant is in the PSP Pending Information state.

Response Handling

Status	Description
`Approved`	The document was validated and accepted.
`Under Review`	The document is currently undergoing review.
`Rejected`	The document was rejected and must be corrected and re-uploaded.

Example: Document Webhook Notification

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

Appian - Submerchant Register

API Base URL#

Main Onboarding Endpoints#

Specialized Onboarding Endpoint#

Submerchant Register Process#

🔔 Webhook Notifications via Appian#

📌 Configuration Highlights#

📬 Notification Logic#

🔔 Webhook Payload Examples for Submerchant Creation#

Response Handling#

Batch Webhook Notification — Successful Submerchants#

📦 Batch Webhook Notification — With Errors#

📦 Individual Webhook Notification — With Error#

Payload for Document Upload (MX)#

Response Handling#

Example: Document Webhook Notification#

API Base URL

Main Onboarding Endpoints

Specialized Onboarding Endpoint

Submerchant Register Process

🔔 Webhook Notifications via Appian

📌 Configuration Highlights

📬 Notification Logic

🔔 Webhook Payload Examples for Submerchant Creation

Response Handling

Batch Webhook Notification — Successful Submerchants

📦 Batch Webhook Notification — With Errors

📦 Individual Webhook Notification — With Error

Payload for Document Upload (MX)

Response Handling

Example: Document Webhook Notification