1. Débito automático
API
Español
  • Español
  • English
  • Introducción
    • API Kambia
    • Credenciales
    • Autenticación
    • Verificación
      POST
  • Servicios
    • Catálogo de códigos
    • Payout
      • Notificaciones
      • Create payout
      • Get payout
    • Débito automático
      • Cómo funciona
      • Notificaciones
      • Affiliation
        POST
      • Charge
        POST
  1. Débito automático

Notificaciones

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#

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), 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"
        }
    ]
}
CampoDescripción
document_numberDocumento con el que afiliaste a la persona.
full_nameNombre del titular.
amountMonto en soles que procesó el banco. Incluye el cargo fijo de S/ 20 si lo trasladas al titular.
fecha_cobroFecha del intento de cobro, en formato AAAAMMDD.
bank_codeBanco de la cuenta cobrada (código de 3 dígitos, como en affiliation).
statusResultado del cobro (ver la tabla siguiente).
codigo_operacionCódigo para ubicar el cobro si el titular reclama.
voucher_urlSolo en SUCCESS: dirección del voucher del cobro (ver más abajo).

Estados de un cobro#

statusDescripción
SUCCESSEl banco cobró.
NO_BALANCELa 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.
REJECTEDEl 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" }
    ]
}
statusDescripción
ACCEPTEDEl banco aceptó la afiliación: ya se le puede cobrar.
REJECTEDEl banco no la aceptó; reason dice por qué. Corrige la cuenta y envía affiliation de nuevo.
UNSUBSCRIBEDLa 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"
}
statusDescripción
ACCEPTEDLa persona autorizó el débito automático.
DECLINEDLa 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
Previous
Cómo funciona
Next
Affiliation
Built with