Documentación
API de KeePay
Cobra a tus clientes por domiciliación bancaria SEPA desde tu propio software: alta de clientes, firma del mandato, pagos únicos, suscripciones, devoluciones y reintentos. KeePay genera las remesas para tu banco, concilia los extractos y te avisa de cada cambio por webhook. El dinero va directo de la cuenta de tu cliente a la tuya: KeePay nunca lo toca.
URL base
https://keepay.es/v1
Formato
JSON en UTF-8, campos en camelCase
Importes
Enteros en céntimos de euro (12,50 € = 1250)
- Fechas de cargo como
AAAA-MM-DD; marcas de tiempo en ISO 8601 (UTC). - Cada objeto lleva
object(su tipo) eid(UUID). - Los estados son textos estables en inglés y snake_case (
pending_submission,past_due…); los mensajes de error, en español.
Inicio rápido: tu primer cobro de prueba
En modo prueba el banco está simulado: puedes recorrer todo el circuito en unos minutos, sin contrato bancario.
1 Crea una clave de prueba
En el panel: Primeros pasos → Claves de API → Prueba → + Nueva clave. Empieza por kp_test_. Guárdala en el servidor de tu aplicación.
2 Da de alta al cliente
curl https://keepay.es/v1/customers \
-H "Authorization: Bearer $KEEPAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Talleres Ruiz, SL",
"email": "admin@talleres-ruiz.es",
"taxId": "B12345674",
"externalId": "crm-42"
}'
externalId es tu identificador: único por cliente, sirve para buscarlo (GET /v1/customers?externalId=crm-42).
3 Pide la firma del mandato
El mandato es la autorización del cliente para cobrarle por domiciliación. La forma recomendada es la página alojada: KeePay muestra el texto legal con tu marca, recoge el IBAN y guarda la evidencia de la firma.
curl https://keepay.es/v1/mandate-requests \
-H "Authorization: Bearer $KEEPAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "0a08463c-6f0e-46c7-a044-70b3a78c3e01",
"returnUrl": "https://tuapp.com/sepa/listo",
"cancelUrl": "https://tuapp.com/sepa/cancelado"
}'
Redirige al cliente a la url de la respuesta. Al firmar vuelve a tu returnUrl con ?mandateRequestId=…&status=completed y recibes el webhook mandate.created. En modo prueba usa el IBAN ES91 2100 0418 4502 0005 1332.
4 Cobra
Un pago único (por ejemplo, una factura) se cobra con el mandato activo del cliente:
curl https://keepay.es/v1/payments \
-H "Authorization: Bearer $KEEPAY_KEY" \
-H "Idempotency-Key: factura-2026-0001" \
-H "Content-Type: application/json" \
-d '{ "customerId": "0a08463c-…", "amount": 12550, "reference": "F-2026-0001" }'
O una suscripción que se cobra sola cada mes o año.
5 Simula la respuesta del banco
curl https://keepay.es/v1/sandbox/charges/fe8acd04-…/simulate \
-H "Authorization: Bearer $KEEPAY_KEY" \
-H "Content-Type: application/json" \
-d '{ "outcome": "paid" }'
Recibirás charge.paid y payment.paid. Prueba también una devolución: {"outcome":"returned","reasonCode":"AM04"} genera un reintento automático.
6 Pasa a real
Cuando el panel marque «Listo para cobrar» (contrato SEPA, identificador de acreedor, canal con el banco y correo saliente), crea una clave kp_live_ y úsala en lugar de la de prueba. Los endpoints son exactamente los mismos.
Autenticación
Envía tu clave de API en cada petición:
Authorization: Bearer kp_live_3f1c…
También se aceptan X-Api-Key: kp_live_… y autenticación básica con la clave como usuario (curl -u kp_test_…:). Nunca por parámetro en la URL.
| Prefijo | Modo | Opera sobre |
|---|---|---|
kp_test_ | Prueba | Tu entorno de pruebas: banco simulado, no se envían correos. |
kp_live_ | Real | Tu empresa: las remesas salen a tu banco. |
Cada respuesta indica el modo en la cabecera KeePay-Mode: test|live y lleva un KeePay-Request-Id para soporte. Las claves se crean y revocan en el panel; la clave completa solo se muestra al crearla. Úsala únicamente desde tu servidor: nunca en el navegador ni en una app móvil.
Modo prueba
Cada empresa tiene un entorno de pruebas aislado con el mismo motor que el real. Diferencias:
- Ningún fichero sale a un banco y no se envía ningún correo (los clientes de prueba pueden llevar emails reales).
- Las referencias empiezan por
TEST-. - El resultado de cada cargo lo decides tú con
POST /v1/sandbox/charges/{id}/simulate: pasa por la misma conciliación, reintentos y suspensiones que en real. - IBAN de prueba:
ES91 2100 0418 4502 0005 1332(cualquier IBAN válido funciona).
En el panel, el interruptor Modo prueba muestra los datos de este entorno.
Ciclo de un cobro SEPA
- Mandato firmado (
mandate.created). Sin mandato activo no se puede cobrar. - Cargo programado (
charge.created, estadopending_submission). La fecha de cargo es como pronto 2 días hábiles después (plazo SEPA Core). - Preaviso: KeePay avisa al cliente por email del importe y la fecha. Desde ese momento el importe queda bloqueado (
amountLocked: true). - Remesa: cada día a las 18:00 (Madrid) se presentan al banco los cargos que tocan (
charge.submitted). - Cobrado cuando el extracto Norma 43 confirma el abono (
charge.paid,payment.paid). - Devuelto si el banco del cliente lo rechaza o el cliente lo reclama (hasta 8 semanas en SEPA Core):
charge.returnedcon el motivo enfailure.
Reintentos automáticos: una primera devolución por saldo insuficiente (AM04) se representa a los 5 días hábiles con aviso al cliente. Si vuelve a fallar, el pago queda failed y la suscripción past_due; a los 7 días sin regularizar pasa a suspended. Cualquier otro código falla directamente y requiere revisión (suscripción suspended).
| Estado del cargo | Significado |
|---|---|
pending_submission | Programado; aún se puede cambiar el importe (hasta el preaviso) o cancelar. |
submitted | Presentado al banco en una remesa. |
paid | Abonado en tu cuenta. |
returned | Devuelto; mira failure.code y failure.action. |
retrying · failed · cancelled | Reintento en curso · fallido definitivo · cancelado antes de presentarse. |
Lo que necesitas de tu banco
Para cobrar en real tu empresa necesita, de su propio banco:
- Contrato de adeudos directos SEPA Core (cuaderno 19-14), con su límite de emisión y comisiones.
- Identificador de acreedor SEPA:
ES+ 2 dígitos de control + sufijo + NIF. - Cuenta de abono: IBAN y BIC.
- Canal SFTP para dejar las remesas (pain.008.001.02) y recoger el extracto diario Norma 43. El banco te pedirá la clave pública SSH (se genera en el panel) y la IP
168.119.101.91. Sin SFTP se puede operar por banca online.
El panel (Primeros pasos) incluye una carta lista para llevar al banco y comprueba la conexión. Consulta el estado por API con GET /v1/account.
Cuenta
/v1/account¿Puede cobrar esta empresa? Devuelve readyToCollect y la lista de requirements (creditor_identifier, sepa_contract, bank_channel, outgoing_email) con estado done o pending, para mostrar tu propio aviso.
{
"object": "account",
"id": "8f6c…",
"name": "Talleres Ruiz, SL",
"livemode": true,
"readyToCollect": false,
"channelMode": "manual",
"requirements": [
{ "key": "sepa_contract", "status": "pending", "title": "Contrato de adeudos SEPA Core", "description": "…" }
]
}
Clientes
/v1/customers/v1/customers?email= · externalId= · taxId= · limit · offset/v1/customers/{id}/v1/customers/{id}/v1/customers/{id}/mandates| Campo | Tipo | Descripción |
|---|---|---|
name obligatorio | texto | Nombre o razón social. |
email obligatorio | texto | A este email van los preavisos de cada cargo. |
taxId | texto | NIF, NIE o CIF (se valida). |
phone | texto | Teléfono. |
address | objeto | line1, postalCode, city, country (ISO, por defecto ES). |
externalId | texto | Tu identificador; único por empresa (409 external_id_taken). |
En PATCH todos los campos son opcionales: solo se cambia lo que envíes.
Solicitudes de mandato (página alojada)
/v1/mandate-requests/v1/mandate-requests/{id}Crea un enlace de firma válido 7 días. Pasa customerId de un cliente existente, o los datos para precargar la página (name, email, taxId, externalId): el cliente se crea al firmar.
| Campo | Descripción |
|---|---|
customerId | Cliente al que pertenecerá el mandato. |
returnUrl | A dónde vuelve el cliente tras firmar (https; http solo para localhost). |
cancelUrl | Enlace «Cancelar y volver». |
Respuesta: url (página de firma), status (open, completed, expired) y, una vez firmada, mandateId. La firma queda registrada con el texto legal versionado, la IP y el navegador del firmante.
Mandatos
/v1/mandates?customerId= · status=/v1/mandates/{id}/v1/mandates/v1/mandates/{id}/cancelUsa POST /v1/mandates solo si ya tienes el mandato firmado (en papel o con tu propia firma electrónica): tu clave queda registrada como declarante y debes conservar el original.
| Campo | Descripción |
|---|---|
customerId obligatorio | Cliente. |
iban obligatorio | Cuenta de cargo (se valida y se guarda cifrada). |
signatureMethod obligatorio | paper o electronic. |
signedAt | Fecha de firma (no futura). |
evidence | ip, userAgent, documentUrl, notes. |
Objeto: reference (referencia única del mandato), status (active, cancelled, consumed, failed), type (recurring u one_off), bankAccount (enmascarada, p. ej. •••• 1332). Cancelar un mandato cancela sus suscripciones y los cargos aún no presentados.
Productos
/v1/products/v1/products?active=true/v1/products/{id}name, unitAmount (precio sin IVA, en céntimos), taxRate (21, 10, 4 o 0; por defecto 21), code y kind (service o product). La respuesta incluye unitTax y unitTotal.
Pagos
/v1/payments/v1/payments?customerId= · status=/v1/payments/{id}Un cobro puntual (una factura, una cuota suelta). Si el cliente tiene mandato activo se programa el cargo; si no, el pago queda requires_action con un checkoutUrl donde el cliente lo autoriza.
| Campo | Descripción |
|---|---|
customerId obligatorio | Cliente. |
amount obligatorio | Céntimos, IVA incluido (máx. 1.000.000,00 €). |
reference | Tu referencia (nº de factura). Única por cliente; si no la envías se genera. |
mandateId | Mandato a usar; por defecto el activo más reciente. |
chargeDate | Fecha de cargo: día hábil, como pronto en 2 días hábiles y como mucho a un año. |
Estados: requires_action, pending_submission, submitted, processing, paid, failed. Incluye sus charges (intentos).
Suscripciones
/v1/subscriptions/v1/subscriptions?customerId= · status=/v1/subscriptions/{id}/v1/subscriptions/{id}/v1/subscriptions/{id}/cancel{
"customerId": "0a08463c-…",
"items": [{ "productId": "0020bb1b-…", "quantity": 2 }],
"interval": "monthly"
}
| Campo | Descripción |
|---|---|
items obligatorio | Productos y cantidades; el importe del ciclo es la suma con IVA. |
interval | monthly (por defecto) o yearly. |
startDate | Día en que empieza (por defecto hoy); el primer cargo llega 2 días hábiles después. |
billingDay | Día fijo de cobro de cada mes (1–28, solo mensual) en lugar de startDate. |
trialDays | Días de prueba gratuita (1–730). |
El cliente necesita un mandato activo (409 mandate_required). Con PATCH envías el estado completo de items (cantidad 0 elimina la línea): el cambio se aplica al próximo cargo si aún no se ha preavisado. Al cancelar, el mandato sigue activo salvo que envíes {"cancelMandate": true}. Estados: active, past_due, suspended, cancelled.
Cargos
/v1/charges?customerId= · subscriptionId= · paymentId= · status=/v1/charges/{id}/v1/charges/{id}/v1/charges/{id}/cancel/v1/charges/{id}/retryCada adeudo concreto: la cuota de un ciclo, el cobro de un pago o un reintento. PATCH con {"amount": 4990} cambia el importe mientras no se haya preavisado (consumo variable). cancel solo antes de presentarse. retry crea un nuevo intento de un cargo devuelto ({"applyPenalty": true} añade el recargo configurado).
{
"object": "charge",
"id": "9e9d7065-…",
"status": "returned",
"amount": 11858,
"currency": "EUR",
"chargeDate": "2026-10-08",
"attempt": 1,
"sequence": "recurring",
"amountLocked": true,
"mandateId": "9c631f4e-…",
"customerId": "0a08463c-…",
"subscriptionId": "73b6dcb1-…",
"paymentId": null,
"endToEndId": "TAL-CHG-000002",
"failure": { "code": "AM04", "description": "Saldo insuficiente", "date": "2026-10-13", "action": "retry" }
}
Eventos
/v1/events?type=charge.paid · limit · offset/v1/events/{id}El historial de lo ocurrido, el mismo que llega por webhook. Útil para recuperar eventos si tu servidor estuvo caído. data.object es el recurso afectado.
Simular el banco (modo prueba)
/v1/sandbox/charges/{id}/simulateoutcome: paid o returned; reasonCode: código de devolución (por defecto AM04). Si el cargo aún no se había presentado, se presenta primero. Solo con claves kp_test_ (con una real: 403 livemode_not_allowed).
Webhooks
Registra una URL de tu aplicación en el panel (Primeros pasos → Webhooks) o por API, y KeePay te enviará un POST con cada evento.
/v1/webhook-endpoints{ url, events?, description? }/v1/webhook-endpoints/v1/webhook-endpoints/{id}{ url?, events?, active? }/v1/webhook-endpoints/{id}/v1/webhook-endpoints/{id}/test/v1/webhook-endpoints/{id}/deliveriesAl crear un endpoint la respuesta incluye su secret (whsec_…) una sola vez. La URL debe ser https y pública. events es una lista de tipos o ["*"] (todos, por defecto). Hasta 10 endpoints por modo.
Qué recibes
POST /webhooks/keepay HTTP/1.1
Content-Type: application/json
KeePay-Event-Id: 3f0d7af1-6ec6-408d-bb5f-a380925b86a7
KeePay-Event-Type: charge.paid
KeePay-Signature: t=1791279725,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{
"object": "event",
"id": "3f0d7af1-6ec6-408d-bb5f-a380925b86a7",
"type": "charge.paid",
"createdAt": "2026-10-08T07:02:11+00:00",
"livemode": true,
"data": { "object": { "object": "charge", "id": "fe8acd04-…", "status": "paid", "amount": 12550, … } }
}
Verifica la firma
v1 es el HMAC-SHA256 en hexadecimal, con tu secret como clave, del texto {t}.{cuerpo exacto recibido}. Compáralo en tiempo constante y rechaza marcas de tiempo de más de 5 minutos.
import crypto from "node:crypto";
// Usa el cuerpo crudo (p. ej. express.raw({ type: "application/json" })).
export function verifyKeePay(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`).digest("hex");
const received = Buffer.from(parts.v1 ?? "");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && received.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(expected), received);
}
function verifyKeePay(string $rawBody, string $header, string $secret): bool {
parse_str(str_replace(',', '&', $header), $parts);
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
$fresh = abs(time() - (int) $parts['t']) < 300;
return $fresh && hash_equals($expected, $parts['v1'] ?? '');
}
// $rawBody = file_get_contents('php://input');
// $header = $_SERVER['HTTP_KEEPAY_SIGNATURE'];
import hashlib, hmac, time
def verify_keepay(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body,
hashlib.sha256).hexdigest()
fresh = abs(time.time() - int(parts["t"])) < 300
return fresh and hmac.compare_digest(expected, parts.get("v1", ""))
using System.Security.Cryptography;
using System.Text;
static bool VerifyKeePay(string rawBody, string header, string secret)
{
var parts = header.Split(',').Select(p => p.Split('=', 2)).ToDictionary(p => p[0], p => p[1]);
var expected = Convert.ToHexStringLower(HMACSHA256.HashData(
Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{parts["t"]}.{rawBody}")));
var fresh = Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(parts["t"])) < 300;
return fresh && CryptographicOperations.FixedTimeEquals(
Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(parts.GetValueOrDefault("v1", "")));
}
Entregas y reintentos
- Responde con cualquier
2xxen menos de 10 segundos; procesa en segundo plano si tardas más. - Si no, reintentamos a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h y 24 h (8 intentos, ~2 días). Sin seguir redirecciones.
- Un mismo evento puede llegar más de una vez: usa
KeePay-Event-Idpara no procesarlo dos veces. - El orden no está garantizado.
data.objectes el recurso tal como estaba al enviarse; ante la duda, consulta su estado con unGET. - El historial de entregas, con el código de respuesta de tu servidor, está en el panel y en
/deliveries.
Tipos de evento
| Evento | Cuándo |
|---|---|
customer.created · customer.updated | Alta o cambio de datos de un cliente. |
mandate.created | Mandato firmado (página alojada, alta directa o checkout). |
mandate.cancelled · mandate.failed · mandate.consumed | Cancelado · fallido · mandato de un solo uso ya cobrado. |
payment.created · payment.paid · payment.failed | Ciclo de un pago único. |
charge.created | Cargo programado (incluye cada cuota y los reintentos). |
charge.submitted | Presentado al banco en la remesa del día. |
charge.paid · charge.returned | Abonado · devuelto (con failure). |
charge.updated · charge.cancelled | Importe o fecha cambiados · cancelado. |
subscription.created · subscription.updated | Alta · cambio de importe, cantidades o fecha. |
subscription.past_due · subscription.suspended | Impagada (7 días de gracia) · suspendida. |
subscription.reactivated · subscription.cancelled | Vuelve a estar al día · cancelada. |
Errores
Los errores usan códigos HTTP estándar y siempre el mismo formato:
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "chargeDate: como pronto 2026-10-08 (2 días hábiles, plazo SEPA Core).",
"param": "chargeDate"
}
}
| HTTP | type | Cuándo |
|---|---|---|
| 400 | invalid_request_error | Falta un parámetro o no es válido (param dice cuál). |
| 401 | authentication_error | Sin clave o clave revocada. |
| 403 | permission_error | Operación no permitida en este modo. |
| 404 | invalid_request_error | resource_missing: no existe (o es de otra empresa) · route_not_found. |
| 409 | invalid_request_error | Conflicto de estado: mandate_required, reference_taken, external_id_taken, mandate_not_active… |
| 400 / 409 | idempotency_error | Clave de idempotencia reutilizada con otro cuerpo, o petición en curso. |
| 429 | rate_limit_error | Demasiadas peticiones (mira Retry-After). |
| 500 / 502 | api_error | Error nuestro: reintenta con la misma Idempotency-Key. |
Idempotencia
Envía Idempotency-Key (hasta 255 caracteres, p. ej. un UUID o tu nº de factura) en cualquier POST. Si repites la petición en las siguientes 24 h recibes la misma respuesta, con la cabecera Idempotent-Replayed: true, sin crear nada nuevo: reintentar tras un corte de red nunca cobra dos veces. La misma clave con otro cuerpo devuelve idempotency_key_reused. Los errores no se guardan: corrige y reintenta con la misma clave.
Paginación
Los listados devuelven lo más reciente primero:
{ "object": "list", "data": [ … ], "hasMore": true }
limit entre 1 y 100 (20 por defecto) y offset para la página siguiente: ?limit=100&offset=100.
Límites
100 peticiones cada 10 segundos por clave. Al superarlo respondemos 429 con Retry-After; reintenta con espera creciente.
Códigos de devolución SEPA
Llegan en charge.failure.code. failure.action dice qué ha hecho KeePay: retry (reintento automático), suspend (segunda devolución por saldo: pago fallido y suscripción impagada) o manual_review (fallo definitivo: revisa con el cliente).
| Código | Motivo | Qué hacer |
|---|---|---|
AM04 | Saldo insuficiente | Reintento automático a los 5 días hábiles; si se repite, impago. |
MS02 | Orden rechazada por el cliente | Contacta con el cliente antes de volver a cobrar. |
MD06 | Reembolso solicitado por el cliente | El cliente reclamó el cargo (derecho de 8 semanas). |
MD01 | Sin mandato válido | Revisa la evidencia del mandato; pide uno nuevo. |
AC01 · AC04 · AC06 | IBAN incorrecto · cuenta cancelada · cuenta bloqueada | Pide al cliente una cuenta nueva (nuevo mandato). |
AG01 | La cuenta no admite adeudos directos | Otra cuenta u otro medio de pago. |
MD07 | Titular fallecido | Cancela el mandato. |
AM05 · MD02 · FF01 · RC01 | Duplicado · faltan datos del mandato · formato · BIC | Revisa los datos; escríbenos si persiste. |
MS03 · SL01 · RR01 | Motivo no especificado · servicio de la entidad · datos regulatorios | Consulta con el cliente o su banco. |