Notificaciones

La API de Kambia puede enviar notificaciones sobre el cambio de estado del payin (autorizado, rechazado o vencido) 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 (payin_webhook).

Estados posibles

status	Descripción
AUTHORIZED	El pago fue completado y confirmado por la entidad.
REJECTED	El pago fue rechazado o no completado.
EXPIRED	El pago no fue completado y la orden ha vencido.

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 crudo del request (string JSON tal como se recibió).

Construir el string a firmar: merchant_id + body crudo (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. Deben coincidir.

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 payin con un order_id que empiece por DEMO_AUTHORIZED, DEMO_REJECTED o DEMO_EXPIRED, la API enviará automáticamente la notificación correspondiente a tu payin_webhook ~500 ms después.

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

Ejemplos

1. Pago autorizado (AUTHORIZED)

Cuando el pagador haya completado el pago y la entidad lo haya confirmado, se enviará una notificación de estado AUTHORIZED.

{
    "status": "AUTHORIZED",
    "message": "Payin notification received",
    "timestamp": "2025-02-12T15:30:00.000Z",
    "payin": {
        "id": "MONTRX2167096626031770238",
        "order_id": "ORDER_123",
        "amount": "1.00",
        "currency": "PEN",
        "method": "bank_transfer"
    }
}

2. Pago rechazado (REJECTED)

Cuando el pago haya sido rechazado o no completado, se enviará una notificación de estado REJECTED para identificar el motivo.

{
    "status": "REJECTED",
    "message": "Invalid transaction",
    "timestamp": "2025-02-12T14:00:00.000Z",
    "payin": {
        "id": "MONTRX2167096626031770239",
        "order_id": "ORDER_124",
        "amount": "1.00",
        "currency": "PEN",
        "method": "cash"
    }
}

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

Configuración#

Estados posibles#

Verificación de la firma#

Pruebas automáticas#

Ejemplos#

1. Pago autorizado (AUTHORIZED)#

2. Pago rechazado (REJECTED)#