Notificaciones

Kambia te avisa en tu webhook cómo respondió el banco a tus afiliaciones y a tus cobros, en cuanto recibe la respuesta.

Cómo se envía

Método: POST

Content-Type: application/json

Header de firma: x-kambia-signature (ver más abajo).

Llega un aviso por cada respuesta del banco, con todas tus afiliaciones (affiliations) o todos tus cobros (charges) de esa respuesta.

Configuración

Envía a Kambia la URL de tu webhook para registrarla. Es la misma para sandbox y producción.

Si tu webhook pide un header propio (por ejemplo, un token), indícalo y Kambia lo envía en cada aviso.

Responde con un estado 2xx en menos de 6 segundos. Si no responde o devuelve 5xx, 408 o 429, Kambia reintenta: son tres intentos en total y después no se reenvía. Otro 4xx no se reintenta.

Aviso de cobros

Llega con event: "autodebit.charge_results":

{
    "event": "autodebit.charge_results",
    "batch_id": "3c30bf81-509a-4c21-9c73-78f4f802ea9f",
    "merchant_id": "123",
    "processed_at": "2026-10-01T21:15:00.000Z",
    "charges": [
        {
            "document_number": "12345678",
            "full_name": "JUAN PEREZ",
            "amount": "150.50",
            "fecha_cobro": "20261001",
            "status": "SUCCESS",
            "codigo_operacion": "KAM-20261001-ABC_12345678",
            "voucher_url": "https://api.kambia.app/v1/autodebit/123/charge-voucher/20261001/ABC_12345678"
        },
        {
            "document_number": "87654321",
            "full_name": "MARIA LOPEZ",
            "amount": "250.00",
            "fecha_cobro": "20261001",
            "status": "NO_BALANCE",
            "codigo_operacion": "KAM-20261001-ABC_87654321"
        }
    ]
}

Campo	Descripción
`document_number`	Documento con el que afiliaste a la persona.
`full_name`	Nombre del titular.
`amount`	Monto en soles que procesó el banco. Incluye el cargo fijo de S/ 20 si lo trasladas al titular.
`fecha_cobro`	Fecha del intento de cobro, en formato `AAAAMMDD`.
`status`	Resultado del cobro (ver la tabla siguiente).
`codigo_operacion`	Código para ubicar el cobro si el titular reclama.
`voucher_url`	Solo en `SUCCESS`: dirección del voucher del cobro (ver más abajo).

Estados de un cobro

status	Descripción
SUCCESS	El banco cobró.
NO_BALANCE	La cuenta no tenía saldo. El banco vuelve a intentar en los días hábiles siguientes; si cobra, llega otro aviso con `SUCCESS` para la misma persona.
REJECTED	El banco rechazó el cobro.

Aviso de afiliaciones

Llega con event: "autodebit.affiliation_results" cuando el banco responde tus afiliaciones:

{
    "event": "autodebit.affiliation_results",
    "batch_id": "6f1d2c3a-8b4e-4f5a-9c7d-2e1f0a9b8c7d",
    "merchant_id": "123",
    "processed_at": "2026-10-01T21:15:00.000Z",
    "affiliations": [
        { "document_number": "12345678", "status": "ACCEPTED" },
        { "document_number": "87654321", "status": "REJECTED", "reason": "CTA.NO ES DE CLIENTE" }
    ]
}

status	Descripción
ACCEPTED	El banco aceptó la afiliación: ya se le puede cobrar.
REJECTED	El banco no la aceptó; `reason` dice por qué. Corrige la cuenta y envía affiliation de nuevo.
UNSUBSCRIBED	La persona quedó desafiliada: ya no se le puede cobrar.

Si account_change viene en true, la respuesta es a un cambio de cuenta: con REJECTED se sigue cobrando a la cuenta anterior.

Verificación de la firma

Toma el body tal como llegó (el string JSON).

Arma el texto a firmar: merchant_id + body, sin separador.

Calcula HMAC-SHA256 con tu merchant_secret y compara el resultado en hex con el header x-kambia-signature.

Si no coinciden, el aviso no es válido.

Voucher

voucher_url es una dirección del API de Kambia: pídela con GET y los headers de autenticación. En un GET se firma merchant_id + timestamp, sin body. La respuesta trae en data.url un enlace a la imagen del voucher, válido por 1 hora, y en data.codigo_operacion el código del cobro.

Sandbox

En sandbox los avisos llegan cuando simulas la respuesta del banco (ver Cómo funciona), con "test": true para que no los confundas con los reales.

Cómo se envía#

Configuración#

Aviso de cobros#

Estados de un cobro#

Aviso de afiliaciones#

Verificación de la firma#

Voucher#

Sandbox#