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

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.

Importante

Solo los subcomercios que pasen esta validación podrán seguir con el proceso. Si alguno tiene errores, deberás corregirlos y volver a enviarlo.

¿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:

VALID: El subcomercio fue validado exitosamente y puede continuar con el proceso.

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.

Importante

Una vez que un subcomercio ha sido aprobado y está listo para el onboarding, cada solicitud genera un identificador único llamado requestId, el cual podrás usar luego, en el segundo endpoint para consultar el estado del proceso de creación.

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).

La configuración de los webhooks no se realiza en Kushki sino como parte de las condiciones operativas, durante la afiliación del PSP en Kushki.

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.

Importante

Solo los subcomercios con estado READY_FOR_ONBOARDING continuarán con el proceso y podrán mostrar actualizaciones de estado posteriores.

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

Estado	Descripción
`REJECTED`	El subcomercio no fue aprobado. El proceso ha terminado.
`PSP_PENDING_INFORMATION`	El subcomercio tiene tareas pendientes en el portal del PSP que deben completarse para continuar. Importante: este estado incluirá el array `pendingDocuments` en la respuesta para detallar qué documentos específicos están pendientes de envío o revisión.
`KUSHKI_KYC: ONGOING`	Kushki está revisando la información. Si se requiere información adicional, el estado cambiará a `PSP_PENDING_INFORMATION`.
`KUSHKI_ACCOUNT_CREATION: ONGOING`	Se está creando la cuenta del subcomercio en los sistemas de Kushki.
`APPROVED_WITH_CONDITIONS`	Aprobado, pero requiere completar tareas post-producción listadas en el portal.
`APPROVED`	Aprobado completamente y listo para operar.

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.

Valor de Respuesta	Descripción
`true`	El documento pasó la validación inicial y ha sido enviado para su procesamiento.
`false`	El documento o la solicitud falló al cumplir con el formato o contexto operacional requerido (ej. país incorrecto, tamaño de archivo inválido).

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

Estado	Descripción
`Approved`	El documento fue validado y aceptado.
`Under Review`	El documento está en proceso de revisión.
`Rejected`	El documento fue rechazado (se deben corregir y cargar de nuevo).

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,

Importante

Este endpoint solo devolverá subcomercios que estén aprobados y asociados al PSP autenticado.

¿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",
    ]
}

Este endpoint es opcional, pero recomendado si el PSP necesita operar de forma masiva con los subcomercios, ya que agiliza el acceso a la información previa a la obtención de credenciales.

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.

Importante

Solo los subcomercios con estado APPROVED podrán obtener credenciales.

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.

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

Flujo General de Onboarding#

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

¿Qué respuestas puedes recibir?#

1.1 Notificación Webhook: Estado del Subcomercio#

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

Posibles Estados#

2.1 Carga de Documentos de Subcomercios (Submerchant Document Upload)#

Documentos Requeridos (MX):#

Respuestas#

Webhook de Resultado (Opcional):#

Posibles Estados del Webhook#

3. Consulta de Submerchant IDs (Get subermchantsIds)#

4. Obtener Credenciales de Subcomercios#

Autenticación#

Consideraciones importantes#

Flujo General de Onboarding

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

¿Qué respuestas puedes recibir?

1.1 Notificación Webhook: Estado del Subcomercio

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

Posibles Estados

2.1 Carga de Documentos de Subcomercios (Submerchant Document Upload)

Documentos Requeridos (MX):

Respuestas

Webhook de Resultado (Opcional):

Posibles Estados del Webhook

3. Consulta de Submerchant IDs (Get subermchantsIds)

4. Obtener Credenciales de Subcomercios

Autenticación

Consideraciones importantes