¿Cómo realizar el onboarding de subcomercios vía API?

12 noviembre 2025

Valida, consulta y habilita subcomercios de forma automatizada utilizando los endpoints de onboarding vía API.

Kushki proporciona un flujo de onboarding estructurado para que los Proveedores de Servicios de Pago (PSP) puedan crear subcomercios cumpliendo con los requisitos operativos y regulatorios. Te contamos cómo validar subcomercios (en lote o individual), interpretar notificaciones por webhook, consultar su estado y obtener credenciales para operar en producción.

Para esto existen 3 endpoints clave para el proceso:

Flujo General de Onboarding

1. Validación de Subcomercios en lote (Submerchant Validation in Batch)

Este primer endpoint o servicio permite enviar uno o varios subcomercios para validar su información antes de iniciar el proceso de onboarding. En este primer paso no se crean subcomercios todavía, solo se revisa que los datos estén bien estructurados y sean válidos para continuar.

¿Qué debes incluir? Los datos requeridos, como: país, representantes legales, beneficiarios finales (UBOs), entre otros. Para revisar los campos y datos requeridos haz clic aquí

¿Qué respuestas puedes recibir?

• INITIALIZED: Kushki recibió tu solicitud y está procesándola.
• VALIDATION_FAILED: Uno o más subcomercios tienen errores y no pueden continuar.

Adicionalmente, en la respuesta recibirás también:

• submerchantId: Identificador único asignado al subcomercio.

• submerchantName: Nombre del subcomercio enviado en la solicitud.

• status: Indica el resultado de la validación individual del subcomercio, podrás tener estas respuestas:

1. VALID: El subcomercio fue validado exitosamente y puede continuar con el proceso.
2. INVALID: El subcomercio contiene errores en los datos enviados y requiere corrección antes de continuar.

Una vez enviado para validación, podrás verificar si el subcomercio esta listo para onboarding o no mediante una notificación recibida por webhook.

1.1 Notificación Webhook: Estado del Subcomercio

Una vez que se procesa la solicitud, Kushki enviará una notificación por webhook con el estado de cada subcomercio. Este mensaje puede llegar de forma individual o en grupo.

• Los webhooks son opcionales y se aplican específicamente a esta segunda fase de validación para notificar al comercio sobre el estado del proceso.
• Las notificaciones pueden ser individuales (una por cada registro) o en batch (cuando se completa un bloque de registros).

Estados que recibirás por webhook

• READY_FOR_ONBOARDING: El subcomercio pasó la validación y está listo para iniciar el proceso de onboarding.
• ERROR: La creación falló debido a errores de validación o procesamiento. Debes corregir y reenviar.

Ejemplo de notificación webhook exitosa

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

Ejemplo de notificación webhook con errores

[
  {
    "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"
        }
      }
    }
  }
]

Consulta aquí la documentación del webhook

2. Consultar Estado del Onboarding (Get submerchant by requestId/submerchantId)

Una vez aprobado el subcomercio podrás consultar este servicio. El cual permite consultar el estado de onboarding de un subcomercio, ya sea por una solicitud en lote o por un subcomercio en específico.

¿Cómo usar este endpoint?

• Para consultar una solicitud en lote: enviar el requestId.
• Para consultar un subcomercio específico: enviar el submerchantId.

Posibles Estados

Con este endpoint podrás consultar los diferentes estados de un subcomercio durante el proceso

1. Para determinar si el subcomercio ingresó o no al onboarding:

• READY_FOR_ONBOARDING: El subcomercio pasó la validación y está listo para iniciar el proceso de onboarding.
• ERROR: La creación falló por problemas de validación o procesamiento. Debes corregir y reenviar el pedido.

2. Para saber el status de onboarding (solo para subcomercios aprobados):

2.1 Carga de Documentos de Subcomercios (Submerchant Document Upload)

Este endpoint permite a los PSPs completar las tareas pendientes de PSP_PENDING_INFORMATION relacionadas con el Know Your Customer (KYC), permitiendo la carga de documentos vía API.

Documentos Requeridos (MX):

Los documentos requeridos para avanzar en el flujo de México son:

• Constancia de Situación Fiscal.
• Acta constitutiva.
• ID del Representante Legal.
• Comprobante de Domicilio.

Respuestas

Si el envío fue exitoso, el sistema devuelve una simple confirmación de éxito, indicando que el documento ha sido aceptado para su procesamiento.

Webhook de Resultado (Opcional):

El resultado final del procesamiento de los documentos (ej. Aprobado o Rechazado) se comunicará a través del webhookUrl provisto en la solicitud de carga.

Para obtener visibilidad continua y bajo demanda del estado más actual, consulte el endpoint principal de estatus (Get submerchant by requestId/submerchantId), el cual incluye el estado de pendingDocuments el cual indica cuales son los documentos pendientes por cargar, cuando el subcomercio se encuentra en el estado PSP Pending Information.

Posibles Estados del Webhook

Ejemplo de respuesta 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"
    }
  ]
}

3. Consulta de Submerchant IDs (Get subermchantsIds)

Este servicio permite a los PSP obtener, de forma masiva, todos los submerchantIds. Funciona como un paso previo a la obtención de las credenciales,

¿Qué se requiere?

• Se requiere la API Key del PSP generada desde el portal de Appian.

• El acceso está limitado a subcomercios asociados al PSP autenticado.

Respuesta esperada

• La respuesta incluirá un arreglo con todos los submerchantIds correspondientes al PSP.

Ejemplo de respuesta:

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

4. Obtener Credenciales de Subcomercios

Este servicio permite a los PSP obtener las credenciales públicas y privadas de uno o más subcomercios que ya fueron creados exitosamente en Kushki.

Autenticación

• Este servicio utiliza la API Key del PSP, generada a través del portal de Appian.
• Está diseñado para PSPs que gestionan múltiples subcomercios dentro de su ecosistema, y permite acceder de forma segura a las credenciales por cada subcomercio autorizado.

Consideraciones importantes

• Es posible incluir múltiples merchantIds en una misma solicitud para obtener las credenciales de varios subcomercios de forma simultánea.
• La respuesta proporcionará, por cada subcomercio válido:
  • publicCredential y privateCredential: claves necesarias para ejecutar operaciones transaccionales como cobros, suscripciones, entre otras.
• Solo se entregarán credenciales de subcomercios que estén correctamente asociados al PSP autenticado.
• Si ocurre un error al procesar alguno de los IDs solicitados, se incluirá el submerchantId correspondiente junto con un mensaje detallando el motivo:
  • El subcomercio no pertenece al PSP autenticado: El ID es válido, pero está vinculado a otro PSP.
  • Submerchant not found: El ID no existe o el proceso de onboarding aún no ha concluido.