Appian - Submerchant Register - Kushki Developer Portal

Kushki ofrece una API para que los Payment Service Providers (PSPs) creen varios subcomercios en una sola operación. Esta API agiliza el proceso de onboarding y permite a los negocios escalar de forma eficiente cumpliendo con los requisitos legales y operativos.

URL base de la API

Ambiente	URL
Producción	`https://api.kushkipagos.com`
Pruebas	`https://core-uat-us-east-1.kushkipagos.com`

Endpoints principales de onboarding

Submerchant Validation in Batch (POST /onboarding/v1/submerchants/batch) — Envía uno o más subcomercios para la validación inicial. Este paso revisa los datos estructurales y operativos, pero todavía no hace el onboarding de los subcomercios.

1.1. Notificación por webhook: estado del subcomercio — Una vez procesada la solicitud, Kushki envía un webhook por cada subcomercio con su estado de onboarding. Esta notificación puede ser individual o por lote.

Si el estado es READY_FOR_ONBOARDING, continúa al siguiente paso para dar seguimiento al avance del onboarding (paso 2).

Si el estado es ERROR, revisa los detalles, corrige los datos y vuelve a enviar la solicitud usando el paso 1.

Query submerchant status by requestId/submerchantId (GET /onboarding/v1/submerchants) — Usa este endpoint para monitorear el avance del onboarding de un subcomercio después de recibir el estado READY_FOR_ONBOARDING.

Get submerchantIds (GET /onboarding/v1/psp/submerchantIds) — Obtén todos los submerchantId de uno o más subcomercios que completaron el proceso de onboarding, usando la API Key de Appian.

Get credentials for submerchants (POST /onboarding/v1/psp/credentials) — Obtén las credenciales transaccionales (llaves pública y privada) de los subcomercios que completaron el onboarding.

Proceso de registro de subcomercios

El PSP envía una solicitud de creación por lote con varios subcomercios. Kushki valida el formato de la solicitud.

Solo los subcomercios que pasan la validación avanzan al proceso de onboarding.

Si son válidos, los subcomercios pasan al onboarding.

Si son inválidos, debes corregir los errores y volver a enviar la solicitud.

Kushki procesa la solicitud y devuelve un requestId junto con otros detalles.

El PSP consulta el estado con el requestId o el submerchantId para revisar el avance del onboarding de cada subcomercio.

🔔 Notificaciones por webhook vía Appian

Kushki puede notificar automáticamente a los PSPs los resultados del onboarding de subcomercios por webhook, según la configuración establecida en Appian como parte del acuerdo comercial durante la afiliación.

📌 Puntos clave de la configuración

La configuración del webhook se hace en el Portal del PSP en Appian.

Cada PSP puede activar o desactivar las notificaciones por webhook y configurar:

Tipo de notificación: batch o individual

Alcance de los eventos en modo individual:

Notificar solo errors

Notificar solo successes

Notificar all los resultados

La URL de destino a donde se envían los eventos

📬 Lógica de notificación

Si batch está activo → se envía un resumen cuando termina de procesarse todo el lote.

Si individual está activo → Kushki puede notificar:

✅ Todos los resultados de los subcomercios

❌ Solo los errores

✔️ Solo los exitosos

🔔 Ejemplos de payload de webhook para la creación de subcomercios

Según la configuración (individual o por lote), Kushki envía notificaciones por webhook a la URL configurada por el PSP con el estado del proceso de onboarding del subcomercio.

Manejo de la respuesta

Cuando se envía una solicitud de creación por lote, Kushki valida el formato de cada subcomercio del payload. La respuesta incluye un campo status con uno de los siguientes valores:

Estado	Descripción
`READY_FOR_ONBOARDING`	El subcomercio pasó la validación y está listo para el proceso de onboarding.
`ERROR`	La creación del subcomercio falló por problemas de validación o de procesamiento. Debes corregir el problema y volver a enviar la solicitud de creación.

Notificación por webhook por lote — Subcomercios exitosos

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

📦 Notificación por webhook por lote — Con errores

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

📦 Notificación por webhook individual — Con 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 para carga de documentos (MX)

Importante: este endpoint es solo para subcomercios con país de operación México (MX).

Este webhook se envía a la webhookUrl indicada en la solicitud de carga de documentos (POST /upload/v1/submerchant/files) una vez que los documentos han sido procesados y revisados.

El payload contiene el submerchantId y el estado de cada documento cargado (Approved, Under Review o Rejected). Para tener visibilidad continua y bajo demanda del estado más actual, consulta el endpoint principal de estado (GET /onboarding/v1/submerchants), que incluye el array pendingDocuments cuando el subcomercio está en el estado PSP Pending Information.

Manejo de la respuesta de documentos

Estado	Descripción
`Approved`	El documento fue validado y aceptado.
`Under Review`	El documento está en revisión.
`Rejected`	El documento fue rechazado y debes corregirlo y volver a cargarlo.

Ejemplo: notificación por webhook de documentos

{
  "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

URL base de la API#

Endpoints principales de onboarding#

Proceso de registro de subcomercios#

🔔 Notificaciones por webhook vía Appian#

📌 Puntos clave de la configuración#

📬 Lógica de notificación#

🔔 Ejemplos de payload de webhook para la creación de subcomercios#

Manejo de la respuesta#

Notificación por webhook por lote — Subcomercios exitosos#

📦 Notificación por webhook por lote — Con errores#

📦 Notificación por webhook individual — Con error#

Payload para carga de documentos (MX)#

Manejo de la respuesta de documentos#

Ejemplo: notificación por webhook de documentos#