Ir al contenido
KUTI

Changelog

Qué cambió en la API. Lo más nuevo arriba. Versión actual: 1.0.0.

Aquí ves qué puedes usar hoy y qué rompe contratos. Seguimos semver: si algo deja de ser compatible, sube la versión mayor. Mientras tanto, todo vive en https://api.kuti.pe/v1.

Auth: Authorization: Bearer kuti_live_… (o kuti_test_…). Webhooks: firma con whsec_… / whsec_test_…. Esas keys y la Base URL no cambian en 1.x.

13 oct 2026 — Clientes sin duplicados por correo o teléfono

  • Al crear un cobro, un link de pago, una sesión de checkout o una suscripción con los datos del cliente, ahora se reutiliza el cliente que ya tengas con ese correo y, si no hay, con ese teléfono. El orden completo es: id → external_id → documento → correo → teléfono.
  • POST /customers y PATCH /customers/{id} responden 409 CUSTOMER_ALREADY_EXISTS si el correo o el teléfono ya es de otro cliente. Antes solo lo hacían con el external_id y el documento.
  • Excepción: dos clientes con documento distinto sí pueden compartir correo o teléfono (por ejemplo, familiares).
  • Los celulares peruanos se guardan siempre como +51 y sus 9 dígitos, aunque los envíes sin prefijo o con espacios. La API te los devuelve en ese formato.
  • SDKs: no cambian; siguen en 1.1.2.

7 oct 2026 — Idempotency-Key en más endpoints

  • Ahora también aceptan Idempotency-Key: crear cliente, crear link de pago, enviar un cobro por WhatsApp o por correo, registrar un endpoint de webhook, reintentar una entrega, crear un campo de cliente y las importaciones.
  • Misma llave y mismo contenido: recibes la respuesta original y nada se hace dos veces. Misma llave con otro contenido: 409 IDEMPOTENCY_CONFLICT.
  • SDKs 1.1.2 (Node, PHP, Python): la llave en customers.create, paymentLinks.create, paymentIntents.sendWhatsApp y webhookDeliveries.retry.

6 oct 2026 — Docs: portal, referencia y Guías

  • Portal en docs.kuti.pe: entrada a Guías, Referencia, MCP, SDKs y Plugins.
  • Guías empiezan en /que-es-kuti. Referencia en /referencia (contrato HTTP, no el primer endpoint).
  • Plugin WooCommerce documentado en 1.0.2 (Blocks, DNI/RUC, campos personalizados). llms.txt y llms-full.txt al 2026-10-06.

6 oct 2026 — Plugin WooCommerce 1.0.2

  • KUTI Payments for WooCommerce 1.0.2: nombre y apellido por separado, DNI/RUC opcional, campos personalizados del cliente, checkout clásico y WooCommerce Blocks.
  • ZIP: kuti-payments-for-woocommerce-1.0.2.zip. WooCommerce 6.0+ (probado hasta 9.3).

6 oct 2026 — Agentes MCP

  • Dos agentes en mcp.kuti.pe: KUTI Integration Agent (https://mcp.kuti.pe/integration) y KUTI Troubleshooter Agent (https://mcp.kuti.pe/troubleshooter).
  • Guía en Documentación → Agentes MCP: registro en Claude Code, Cursor y Claude Desktop con tu API key en Authorization.

6 oct 2026 — Idempotencia en suscripciones

  • POST /subscriptions, /subscriptions/{id}/charges, /retry, /pause, /resume y /cancel aceptan Idempotency-Key (header opcional, UUID v4). Misma key + mismo payload = la respuesta original; otro payload = 409 IDEMPOTENCY_CONFLICT.
  • SDKs 1.1.1 publicados (Node, PHP, Python): create, charge, retry, pause, resume y cancel envían idempotencyKey / idempotency_key.

5 oct 2026 — Suscripciones

  • Suscripciones: POST /subscriptions y sus acciones (editar, pausar, reanudar, cancelar, reintentar, periodos). Monto fijo, o monto que envías cada periodo con POST /subscriptions/{id}/charges.
  • Medios de pago guardados del cliente: GET /customers/{id}/payment-methods y DELETE /customers/{id}/payment-methods/{payment_method_id}.
  • Cobro directo sobre un medio guardado: POST /payment-intents con payment_method y confirm: true. Pago con un toque desde el enlace: saved_payment_methods: "enabled".
  • Eventos nuevos: subscription.* y payment_method.*.
  • SDKs 1.1.0 (Node, PHP, Python): subscriptions, medios guardados y cobro directo.

29 sep 2026 — Diagnóstico de errores

  • GET /diagnostics/requests/{id}, GET /diagnostics/requests?correlation_id=, GET /diagnostics/payment-intents/{id}/trace (permiso diagnostics:read).
  • GET /webhook-deliveries/{id}: una entrega con todos sus intentos.
  • Los errores traen error.correlation_id además de error.request_id.
  • Eventos y webhooks traen request: { id, idempotency_key } (null si lo generó el sistema).
  • SDKs 1.0.6 (Node, PHP, Python): paymentExceptions, webhookDeliveries, diagnostics, code del cliente, correlationId y cómo distinguir INSUFFICIENT_SCOPE / API_KEY_NOT_ALLOWED en el error 403.

29 sep 2026 — Permisos de API keys

Ahora eliges qué puede hacer cada API key: Lectura y escritura (tu backend), Solo lectura (ideal para asistentes de IA y reportes) o Personalizado, recurso por recurso.

  • Permisos por recurso: payment_intents, payment_links, subscriptions, receivables, customers, checkout, payment_exceptions, webhooks, merchant (lectura y escritura) y payments, balance, events, diagnostics (lectura).
  • Una llamada sin el permiso responde 403 INSUFFICIENT_SCOPE. Tus keys actuales siguen con acceso completo, sin que tengas que cambiar nada.
  • Por seguridad, cambiar la cuenta bancaria de liquidación, crear negocios, marca, verificación, plan y automatizaciones se hacen solo desde el panel (403 API_KEY_NOT_ALLOWED con una key).
  • El checkout en el navegador usa el client_secret del cobro (KUTI.js), así que las claves publicables (kuti_pub_…) se retiraron: ya no hace falta ninguna key en el frontend.

28 sep 2026 — Códigos de pago y pagos dobles

Cada cliente tiene un código de pago fijo (el prefijo de 4 letras de tu negocio + número, p. ej. ZIZE00001): es el que tu cliente digita en su banca. Y si un cobro se paga dos veces, el dinero nunca se pierde.

  • Merchant.code (4 letras) y Customer.code (solo lectura). Los cobros por banca usan el código del cliente.
  • Si pagan por QR, el código de banca de ese cobro se anula en el proveedor (y al revés). Si una cuota se paga, sus otros cobros abiertos se anulan con cancellation_reason = SETTLED_BY_OTHER_PAYMENT.
  • Nuevo recurso /payment-exceptions (GET y POST /{id}/resolve): pagos que entraron pero no correspondían. Evento payment.exception_created.

25 sep 2026 — Links de pago en la API

Nuevo recurso /payment-links: un enlace permanente que pagan muchas personas (cursos, entradas, donaciones). Cada pago es un cobro normal con payment_link_id.

  • POST/GET/PUT /payment-links, activar/desactivar y disponibilidad de slug. Monto fijo o libre (mínimo, máximo y montos sugeridos).
  • customer_field_ids: qué campos personalizados pregunta cada link (se guarda una copia). button_label y el "después del pago" (success_message + botón con enlace).
  • Resultados por link: views_count, checkouts_count, payments_count y amount_collected.
  • GET /payment-intents: nuevos filtros source (single | link | subscription) y payment_link_id.
  • Eventos payment_link.created / updated / activated / deactivated.
  • SDKs 1.0.5 (Node, PHP, Python): recurso paymentLinks, sendVia al crear cobros y filtros source / paymentLinkId.

25 sep 2026 — Enviar el cobro por WhatsApp al crearlo (send_via)

POST /payment-intents acepta send_via para elegir por dónde le llega el cobro al cliente. Compatible: sin el campo todo sigue igual (correo).

  • send_via: ["EMAIL"] (por defecto), ["WHATSAPP"], los dos, o [] para no enviar nada.
  • WHATSAPP sin teléfono del cliente → 422 CUSTOMER_PHONE_REQUIRED. Cada envío usa 1 moneda de WhatsApp.
  • El cobro devuelve send_via con los canales usados. Luego se agrega SMS sin romper nada.

25 sep 2026 — Marca del negocio en el checkout

El checkout, los links de pago y el correo del cobro usan tu logo y tu estilo, configurados una vez en Ajustes → Marca.

  • Nuevo: logo, color, fondo, tipografía y forma de botones desde el panel (sin código).
  • KUTI.js 0.2.0: appearance acepta font y buttonShape además de primaryColor y logo. Cada campo reemplaza solo ese dato de la marca del panel.
  • El color de marca ahora pinta también el hover del botón y la animación de pago completado (antes quedaban en el verde de KUTI).

24 sep 2026 — Cliente unificado y campos personalizados

El cliente tiene una sola forma en todos los endpoints: first_name / last_name / company_name, document: { type, number, country } y custom_fields. Cambia el contrato en POST /payment-intents (antes given_name / family_name / legal_name), POST /checkout-sessions (antes name en un solo texto), POST /c/{code}/customer, el cliente congelado del cobro (antes document_type / document_value) y el documento de /customers (antes document.value).

  • Nuevo: campos personalizados de cliente (/customer-fields) y custom_fields en clientes, cobros, checkout sessions, imports y webhooks.
  • Nuevo: un cliente inline se reutiliza también por documento (antes repetir un DNI podía fallar).
  • Nuevo: document.type es opcional — se deduce del número (DNI / RUC).
  • PATCH /customers acepta metadata y custom_fields.
  • SDKs 1.0.4 (Node, PHP, Python): forma nueva + recurso customers. Plugin WooCommerce 1.0.2: nombre y apellido separados, DNI/RUC y mapeo de campos.

1.0.0 — 6 sep 2026

Primera versión pública. Puedes crear cobros, recibir el pago por webhook y liquidar a tu CCI.

Qué puedes llamar

  • POST/GET /payment-intents — crear cobro, listar, ver detalle, anular, enviar link por WhatsApp.
  • POST/GET /checkout/sessions — sesión de Checkout.js (modal o embebido) con tu marca.
  • CRUD /customers y /merchants — clientes y negocios.
  • GET /balance, /balance/transactions, /fee-preview — saldo, movimientos y comisión antes de cobrar.
  • GET/POST payouts y cuentas CCI — liquidaciones a tu banco y preferencias.
  • Webhooks: registrar URL, listar eventos/entregas, reintentar; verifica HMAC-SHA256 con el raw body.

Cómo paga el cliente

  • QR interoperable: Yape, Plin y billeteras bancarias.
  • Desde su banca: busca la institución KUTI (pago de servicios).

Clientes oficiales

  • SDKs Node, PHP y Python: auth, cobros, checkout y verifyWebhookSignature.
  • Plugin WooCommerce 1.0.0: abre Checkout.js y marca el pedido pagado al llegar payment.succeeded.

Para integrar más rápido

  • Guías + referencia en docs.kuti.pe.
  • Descarga collection.json (Postman / Insomnia / Bruno) o openapi.json.
  • llms.txt y llms-full.txt si usas un LLM en el IDE.