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.
Solo cuenta lo que envías ese mismo día de corte. Otro día, Charge responde 422 con code: "OUTSIDE_CUTOFF_DATE" y la próxima fecha en data.next_cutoff_date, y no guarda nada: envía la lista ese día. Lo que no salió en un corte no se envía solo en el siguiente: vuelve a enviarlo. En sandbox se acepta cualquier día. 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#
1.
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"
}
}
2.
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.
3.
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. 4.
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ú, con la cláusula de débito automático de tu contrato con Kambia, y la presentas cuando el banco, una autoridad o Kambia te la pidan.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.
Modified at 2026-11-06 20:03:13