Kambia te avisa en tu webhook cómo respondió el banco a tus afiliaciones y a tus cobros, en cuanto recibe la respuesta, y qué decidió cada persona en su autorización.Cómo se envía#
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), todos tus cobros (charges) o los cambios de cuenta (changes) de esa respuesta. El de autorizaciones llega uno por persona.
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",
"bank_code": "002",
"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",
"bank_code": "002",
"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. |
bank_code | Banco de la cuenta cobrada (código de 3 dígitos, como en affiliation). |
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", "bank_code": "002", "account_last4": "8901" },
{ "document_number": "87654321", "status": "REJECTED", "reason": "CTA.NO ES DE CLIENTE", "bank_code": "002", "account_last4": "4321" }
]
}
| 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.Cada afiliación trae bank_code y account_last4: el banco y los últimos 4 dígitos de la cuenta de la que habla el banco.Aviso de autorizaciones#
Llega con event: "autodebit.consent" cuando una persona decide en el enlace de autorización (ver Cómo funciona):{
"event": "autodebit.consent",
"merchant_id": "123",
"consent_id": "3f2c6d1a-8b4e-4f5a-9c7d-2e1f0a9b8c7d",
"document_number": "12345678",
"status": "ACCEPTED",
"decided_at": "2026-10-06T15:04:05.000Z"
}
| status | Descripción |
|---|
| ACCEPTED | La persona autorizó el débito automático. |
| DECLINED | La persona no lo autorizó. |
Aviso de cambio de cuenta#
Llega con event: "autodebit.account_change" cuando la cuenta de cobro de una persona termina su ventana sin saldo y la persona tiene otra cuenta guardada en el mismo banco: Kambia pide al banco cambiarla por esa otra para los siguientes cobros (ver Cómo funciona).{
"event": "autodebit.account_change",
"batch_id": "b6a1c2d3-4e5f-4a7b-8c9d-0e1f2a3b4c5d",
"merchant_id": "123",
"processed_at": "2026-10-09T14:31:05.000Z",
"changes": [
{
"document_number": "12345678",
"full_name": "JUAN PEREZ",
"from": { "bank_code": "002", "account_last4": "1001" },
"to": { "bank_code": "002", "account_last4": "2002" },
"reason": "la cuenta de cobro terminó su ventana sin saldo: Kambia pidió probar esta otra cuenta guardada",
"requested_at": "2026-10-09T14:31:04.000Z"
}
]
}
Mientras el banco no acepte el cambio, se le sigue cobrando en la cuenta anterior. Lo que envíes después con account_action (reemplazar, añadir o quitar) manda sobre este cambio.Verificación de la firma#
1.
Toma el body tal como llegó (el string JSON).
2.
Arma el texto a firmar: merchant_id + body, sin separador.
3.
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. Modified at 2026-10-06 14:59:26