Notificaciones

La API de Kambia puede enviar notificaciones sobre el cambio de estado del payout (éxito o rechazo) al webhook del cliente.

Cómo se envía la notificación

Método: POST

Content-Type: application/json

Header de firma: x-kambia-signature — firma HMAC-SHA256 para que el cliente verifique que la notificación es de Kambia (ver más abajo).

Configuración

El cliente debe habilitar un webhook que reciba la siguiente estructura de datos:

Una vez recibida la notificación, el webhook debe responder con un estado HTTP 200 OK. Caso contrario, recibirá reintentos de la misma notificación.

El cliente debe proporcionar a Kambia la URL válida para su registro (payout_webhook).

Estados posibles

status	Descripción
SUCCESS	El payout fue procesado por el banco, incluye `receipt_url` si el comprobante se generó correctamente.
REJECTED	El payout fue rechazado por el banco.

Verificación de la firma

Cada notificación incluye el header x-kambia-signature. El cliente debe verificar la autenticidad e integridad del cuerpo así:

Obtener el body del request (string JSON tal como se recibió).

Construir el string a firmar: merchant_id + body (concatenación, sin separador).

Calcular HMAC-SHA256 usando su merchant_secret como clave y el string del paso 2 como mensaje.

Comparar el resultado en hex con el valor del header x-kambia-signature.

Si no coinciden, la notificación no debe considerarse válida.

Pruebas automáticas

Para probar la integración del webhook sin necesidad de completar un pago real, puedes usar el modo demo: al crear un payout con un order_id que empiece por DEMO_SUCCESS o DEMO_REJECTED, la API enviará automáticamente la notificación correspondiente a tu payout_webhook ~500 ms después.

Ver detalles en la sección "Modo demo" de Create payout

Ejemplos

1. Payout procesado

Cuando un payout haya sido procesado por el banco, se enviará una notificación de estado SUCCESS. Si el comprobante se generó correctamente, se incluye receipt_url dentro de payout: un enlace para abrir o descargar la imagen del comprobante. La URL es temporal y tiene una validez de 1 hora. En caso de fallo interno al generar el comprobante, la notificación se envía igual pero sin receipt_url.

{
    "status": "SUCCESS",
    "message": "Payout successful",
    "timestamp": "2025-02-12T15:30:00.000Z",
    "payout": {
        "id": "634",
        "country": "PE",
        "amount": "50000",
        "currency": "PEN",
        "order_id": "1768526334152-70042575",
        "bank_code": "002",
        "account_number": "19006234576522",
        "name": "Cristian Zavaleta",
        "receipt_url": "https://api-kambia.s3.amazonaws.com/..."
    }
}

2. Payout rechazado

Cuando un payout haya sido rechazado por el banco, se enviará una notificación de estado REJECTED.

{
    "status": "REJECTED",
    "message": "Payout error: [orderId] Duplicated",
    "timestamp": "2025-02-12T14:00:00.000Z",
    "payout": {
        "id": "613",
        "country": "PER",
        "amount": "25000",
        "currency": "PEN",
        "order_id": "CU_1767031321",
        "bank_code": "002",
        "account_number": "19206434476528",
        "name": "Jose Jeri"
    }
}

Cómo se envía la notificación#

Configuración#

Estados posibles#

Verificación de la firma#

Pruebas automáticas#

Ejemplos#

1. Payout procesado#

2. Payout rechazado#