keepay API v1

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) e id (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.

PrefijoModoOpera sobre
kp_test_PruebaTu entorno de pruebas: banco simulado, no se envían correos.
kp_live_RealTu 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

  1. Mandato firmado (mandate.created). Sin mandato activo no se puede cobrar.
  2. Cargo programado (charge.created, estado pending_submission). La fecha de cargo es como pronto 2 días hábiles después (plazo SEPA Core).
  3. Preaviso: KeePay avisa al cliente por email del importe y la fecha. Desde ese momento el importe queda bloqueado (amountLocked: true).
  4. Remesa: cada día a las 18:00 (Madrid) se presentan al banco los cargos que tocan (charge.submitted).
  5. Cobrado cuando el extracto Norma 43 confirma el abono (charge.paid, payment.paid).
  6. Devuelto si el banco del cliente lo rechaza o el cliente lo reclama (hasta 8 semanas en SEPA Core): charge.returned con el motivo en failure.

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 cargoSignificado
pending_submissionProgramado; aún se puede cambiar el importe (hasta el preaviso) o cancelar.
submittedPresentado al banco en una remesa.
paidAbonado en tu cuenta.
returnedDevuelto; mira failure.code y failure.action.
retrying · failed · cancelledReintento 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:

  1. Contrato de adeudos directos SEPA Core (cuaderno 19-14), con su límite de emisión y comisiones.
  2. Identificador de acreedor SEPA: ES + 2 dígitos de control + sufijo + NIF.
  3. Cuenta de abono: IBAN y BIC.
  4. 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

GET/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

POST/v1/customers
GET/v1/customers?email= · externalId= · taxId= · limit · offset
GET/v1/customers/{id}
PATCH/v1/customers/{id}
GET/v1/customers/{id}/mandates
CampoTipoDescripción
name obligatoriotextoNombre o razón social.
email obligatoriotextoA este email van los preavisos de cada cargo.
taxIdtextoNIF, NIE o CIF (se valida).
phonetextoTeléfono.
addressobjetoline1, postalCode, city, country (ISO, por defecto ES).
externalIdtextoTu 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)

POST/v1/mandate-requests
GET/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.

CampoDescripción
customerIdCliente al que pertenecerá el mandato.
returnUrlA dónde vuelve el cliente tras firmar (https; http solo para localhost).
cancelUrlEnlace «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

GET/v1/mandates?customerId= · status=
GET/v1/mandates/{id}
POST/v1/mandates
POST/v1/mandates/{id}/cancel

Usa 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.

CampoDescripción
customerId obligatorioCliente.
iban obligatorioCuenta de cargo (se valida y se guarda cifrada).
signatureMethod obligatoriopaper o electronic.
signedAtFecha de firma (no futura).
evidenceip, 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

POST/v1/products
GET/v1/products?active=true
GET/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

POST/v1/payments
GET/v1/payments?customerId= · status=
GET/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.

CampoDescripción
customerId obligatorioCliente.
amount obligatorioCéntimos, IVA incluido (máx. 1.000.000,00 €).
referenceTu referencia (nº de factura). Única por cliente; si no la envías se genera.
mandateIdMandato a usar; por defecto el activo más reciente.
chargeDateFecha 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

POST/v1/subscriptions
GET/v1/subscriptions?customerId= · status=
GET/v1/subscriptions/{id}
PATCH/v1/subscriptions/{id}
POST/v1/subscriptions/{id}/cancel
{
  "customerId": "0a08463c-…",
  "items": [{ "productId": "0020bb1b-…", "quantity": 2 }],
  "interval": "monthly"
}
CampoDescripción
items obligatorioProductos y cantidades; el importe del ciclo es la suma con IVA.
intervalmonthly (por defecto) o yearly.
startDateDía en que empieza (por defecto hoy); el primer cargo llega 2 días hábiles después.
billingDayDía fijo de cobro de cada mes (1–28, solo mensual) en lugar de startDate.
trialDaysDí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

GET/v1/charges?customerId= · subscriptionId= · paymentId= · status=
GET/v1/charges/{id}
PATCH/v1/charges/{id}
POST/v1/charges/{id}/cancel
POST/v1/charges/{id}/retry

Cada 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

GET/v1/events?type=charge.paid · limit · offset
GET/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)

POST/v1/sandbox/charges/{id}/simulate

outcome: 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.

POST/v1/webhook-endpoints{ url, events?, description? }
GET/v1/webhook-endpoints
PATCH/v1/webhook-endpoints/{id}{ url?, events?, active? }
DELETE/v1/webhook-endpoints/{id}
POST/v1/webhook-endpoints/{id}/test
GET/v1/webhook-endpoints/{id}/deliveries

Al 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);
}

Entregas y reintentos

  • Responde con cualquier 2xx en 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-Id para no procesarlo dos veces.
  • El orden no está garantizado. data.object es el recurso tal como estaba al enviarse; ante la duda, consulta su estado con un GET.
  • El historial de entregas, con el código de respuesta de tu servidor, está en el panel y en /deliveries.

Tipos de evento

EventoCuándo
customer.created · customer.updatedAlta o cambio de datos de un cliente.
mandate.createdMandato firmado (página alojada, alta directa o checkout).
mandate.cancelled · mandate.failed · mandate.consumedCancelado · fallido · mandato de un solo uso ya cobrado.
payment.created · payment.paid · payment.failedCiclo de un pago único.
charge.createdCargo programado (incluye cada cuota y los reintentos).
charge.submittedPresentado al banco en la remesa del día.
charge.paid · charge.returnedAbonado · devuelto (con failure).
charge.updated · charge.cancelledImporte o fecha cambiados · cancelado.
subscription.created · subscription.updatedAlta · cambio de importe, cantidades o fecha.
subscription.past_due · subscription.suspendedImpagada (7 días de gracia) · suspendida.
subscription.reactivated · subscription.cancelledVuelve 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"
  }
}
HTTPtypeCuándo
400invalid_request_errorFalta un parámetro o no es válido (param dice cuál).
401authentication_errorSin clave o clave revocada.
403permission_errorOperación no permitida en este modo.
404invalid_request_errorresource_missing: no existe (o es de otra empresa) · route_not_found.
409invalid_request_errorConflicto de estado: mandate_required, reference_taken, external_id_taken, mandate_not_active…
400 / 409idempotency_errorClave de idempotencia reutilizada con otro cuerpo, o petición en curso.
429rate_limit_errorDemasiadas peticiones (mira Retry-After).
500 / 502api_errorError 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ódigoMotivoQué hacer
AM04Saldo insuficienteReintento automático a los 5 días hábiles; si se repite, impago.
MS02Orden rechazada por el clienteContacta con el cliente antes de volver a cobrar.
MD06Reembolso solicitado por el clienteEl cliente reclamó el cargo (derecho de 8 semanas).
MD01Sin mandato válidoRevisa la evidencia del mandato; pide uno nuevo.
AC01 · AC04 · AC06IBAN incorrecto · cuenta cancelada · cuenta bloqueadaPide al cliente una cuenta nueva (nuevo mandato).
AG01La cuenta no admite adeudos directosOtra cuenta u otro medio de pago.
MD07Titular fallecidoCancela el mandato.
AM05 · MD02 · FF01 · RC01Duplicado · faltan datos del mandato · formato · BICRevisa los datos; escríbenos si persiste.
MS03 · SL01 · RR01Motivo no especificado · servicio de la entidad · datos regulatoriosConsulta con el cliente o su banco.