Cómo funciona

El débito automático tiene tres pasos: afiliar a la persona con su cuenta, enviarle los cobros y recibir el resultado.

1. Afilia a la persona

Envía Affiliation con el documento de la persona o empresa y su cuenta.

Cada registro es una persona o empresa (DNI, CE o RUC) con una cuenta. En un mismo envío puedes mandar muchas.

A una persona le puedes sumar más cuentas: envía cada una con account_action: "add" (o add_account: true), en el mismo request o en otro. Su primera cuenta es la de cobro y las demás quedan guardadas. En details ves el resultado de cada registro.

Para ver las cuentas de una persona y en qué está cada una: GET /v1/autodebit/{merchant_id}/affiliations/{document_number} (cada cuenta con su bank_code, sus últimos 4 dígitos, si es la de cobro y su estado).

Kambia envía la afiliación al banco, y queda pendiente hasta que el banco la acepta.

Cuando el banco responde, te avisamos en tu webhook si la aceptó o la rechazó, y por qué (Notificaciones).

2. Envía los cobros

Envía Charge con el document_number y el monto.

Los cobros salen al banco en las fechas de corte: envíalos antes de las 4:00 p. m. de esa fecha. El banco intenta cobrar desde el día hábil siguiente, durante 3 días hábiles. Para tener las fechas en tu calendario (Google, Outlook o Apple), suscríbete a https://portal.kambia.app/api/debito-automatico/calendario.ics.

Usa el mismo document_number con el que afiliaste. Cada cobro va a una sola cuenta: la de cobro.

Si la cuenta de cobro termina sus 3 días 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 (primero la que nunca se probó) y te avisa con autodebit.account_change (ver Notificaciones). Nunca se debita de dos cuentas a la vez.

Si la afiliación no está lista en la fecha de corte, ese cobro no sale y tienes que volver a enviarlo. La respuesta te lo avisa en not_ready_to_send.

Si repites a una persona en el mismo envío, vuelve en duplicates. Si la reenvías con confirm: true e idempotency_key, los montos se suman en un solo cobro.

3. Recibe el resultado

Kambia te avisa en tu webhook el resultado de cada cobro: cobrado, sin saldo o rechazado. El detalle está en Notificaciones.

Cambiar la cuenta

Para cambiar la cuenta de cobro, envía Affiliation otra vez con la cuenta nueva y account_action: "replace" (o sin el campo). Hasta que el banco acepte el cambio, se sigue debitando la anterior. Para quitar una cuenta, envíala con account_action: "remove": si es la de cobro, no se le cobra hasta que elijas otra. Si la cuenta queda guardada sin cambiar la de cobro, details te dice por qué en reason.

Límites

Hasta 400 registros por request (un envío de más de 100 KB se rechaza con 413) y 30 requests por minuto.

Autorización del titular

Antes de afiliar a una persona necesitas su autorización previa, expresa y por escrito para el débito automático. Puedes pedirla por la API, o usar tus propios contratos.

Por la API

Envía POST /v1/autodebit/{merchant_id}/consents con los datos de la persona (los mismos de Affiliation; la cuenta es opcional):

{
    "document": { "type": "1", "number": "12345678", "full_name": "Juan Perez" },
    "bank_account": { "bank_code": "002", "account_type": "1", "account_number": "19112345678901" },
    "contract_number": "PR-2026-001",
    "return_url": "miapp://autorizacion"
}

Responde 201 con consent_id y url:

{
    "status_code": 201,
    "message": "Consent created",
    "data": {
        "consent_id": "3f2c6d1a-8b4e-4f5a-9c7d-2e1f0a9b8c7d",
        "url": "https://api.kambia.app/v1/autorizar/3f2c6d1a-8b4e-4f5a-9c7d-2e1f0a9b8c7d",
        "status": "PENDING",
        "document_type": "1",
        "document_number": "12345678",
        "full_name": "Juan Perez",
        "created_at": "2026-10-06T15:00:00.000Z",
        "expires_at": "2026-10-13T15:00:00.000Z"
    }
}

Abre url dentro de tu app (o mándasela por mensaje). La persona lee la autorización y toca «Autorizo» o «No autorizo», y Kambia la guarda con su fecha, hora, IP y dispositivo. El enlace vence a los 7 días; si vence, pide otro. return_url (opcional) es el botón para volver a tu app.

Te avisamos el resultado en tu webhook (autodebit.consent, ver Notificaciones). También lo consultas con GET /v1/autodebit/{merchant_id}/consents/{consent_id}: PENDING, ACCEPTED, DECLINED, EXPIRED o REVOKED.

Si después la persona se da de baja en tu app, envía POST /v1/autodebit/{merchant_id}/affiliations/{document_number}/unsubscribe con body {}: se le deja de cobrar, la baja va al banco y sus autorizaciones pasan a REVOKED.

Con tus contratos

Si prefieres tus propios contratos, la obtienes y la guardas tú, y la presentas cuando el banco, una autoridad o Kambia te la pidan.

Puedes incluir esta cláusula en tus contratos:

CLÁUSULA [NÚMERO]: Débito Automático.-
EL (LA) PRESTATARIO(A) autoriza de manera expresa a [NOMBRE DE LA ENTIDAD], directamente o a través de los proveedores tecnológicos, operadores de cobro y/o empresas especializadas que contrate para tal efecto —incluyendo a KAMBIA S.A.C.—, a efectuar, en caso de mora, el débito automático de los montos vencidos, intereses moratorios y demás cargos generados por la mora, conforme al presente contrato, con cargo a sus cuentas en el Banco de Crédito del Perú (BCP) y en cualesquiera otras entidades del sistema financiero, así como a billeteras digitales y demás medios legales de pago o almacenamiento de dinero de los cuales sea titular, respetando los límites de protección de remuneraciones y fondos inembargables previstos por ley. Por cada débito ejecutado asumirá un cargo fijo de S/ 20.00 (veinte con 00/100 soles) por concepto de gestión operativa. Esta autorización se mantiene vigente hasta el cumplimiento total de las obligaciones del presente contrato, salvo comunicación escrita en contrario. Los garantes que suscriban el presente contrato otorgan esta misma autorización respecto de sus cuentas y medios de pago, hasta la cancelación total de la obligación garantizada.

Si la persona ya firmó su contrato sin esta cláusula, usa el modelo de autorización.

Pruebas en sandbox

Usa tus mismas credenciales con https://sandbox.kambia.app/v1. En sandbox nada llega al banco.

Para simular la respuesta del banco, envía POST https://sandbox.kambia.app/v1/autodebit/{merchant_id}/sandbox/bank-response con body {}: acepta tus afiliaciones pendientes y responde tus cobros en cola. Mientras no lo hagas, tus cobros vuelven en not_ready_to_send.

El resultado lo eliges con los centavos del monto: .01 sin saldo (NO_BALANCE), .02 rechazado (REJECTED) y cualquier otro cobrado (SUCCESS). Un documento sin afiliación sale rechazado, como en el banco.

El aviso llega a tu webhook igual que en producción, con "test": true. Cada persona recibe una respuesta por día; lo que no se respondió vuelve en not_answered con el motivo.

La autorización también funciona en sandbox: el enlace abre la misma página y el aviso llega con "test": true.

1. Afilia a la persona#

2. Envía los cobros#

3. Recibe el resultado#

Cambiar la cuenta#

Límites#

Autorización del titular#

Por la API#

Con tus contratos#

Pruebas en sandbox#