Ir al contenido
KUTI

SDKs oficiales

Clientes oficiales para tu backend: crean cobros y checkout sessions, consultan payment intents y verifican webhooks sin rearmar auth ni HMAC a mano.

Los SDKs de KUTI son delgados sobre la API REST. Solo servidor: usan tu secret key (kuti_live_… / kuti_test_…). Nunca los importes en el navegador — para el frontend usa Checkout.js.

Node.jsv1

@kuti-pe/node — npm. Node 18+. v1.1.2

Ver paquete
PHPv1

kuti-pe/kuti-php — Composer. PHP 8.1+. v1.1.2

Ver paquete
Pythonv1

kuti-pe — PyPI. Python 3.9+. v1.1.2

Ver paquete

Qué cubren

Cobro (payment intent) ≠ checkout session. Usa paymentIntents.create para cobro directo (QR / código / link). Usa checkoutSessions.create solo si vas a abrir el modal con Checkout.js.

  • paymentIntents: create (con sendVia, savedPaymentMethods, paymentMethod + confirm), list (filtros source y paymentLinkId), retrieve, cancel, sendWhatsApp, enableSavedPaymentMethods
  • subscriptions: create, list, retrieve, update, pause, resume, cancel, retry, charge, listCycles — con Idempotency-Key en create, charge, retry, pause, resume y cancel (desde 1.1.1)
  • paymentLinks: create, list, retrieve, update, activate, deactivate, checkSlug (desde 1.0.5)
  • paymentExceptions (list, resolve), webhookDeliveries (retrieve, retry), diagnostics (getRequest, listByCorrelationId, tracePaymentIntent), code del cliente y correlationId en errores (desde 1.0.6)
  • customers: create, list, retrieve, update, delete, listPaymentMethods, detachPaymentMethod (desde 1.1.0)
  • checkoutSessions: create (Checkout.js)
  • Webhooks: verificar firma (X-Kuti-Signature)
  • Idempotency-Key también en customers.create, paymentLinks.create, paymentIntents.sendWhatsApp y webhookDeliveries.retry (desde 1.1.2)

Misma superficie en Node, PHP y Python: mismos recursos, mismos campos y mismos códigos de error.

npmbash
npm install @kuti-pe/node

Resuelve el monto en tu backend. Usa idempotencyKey (ej. id de orden) al crear.

Crear sesiónts
import { KutiClient } from "@kuti-pe/node";

const kuti = new KutiClient({ secretKey: process.env.KUTI_SECRET_KEY! });

const session = await kuti.checkoutSessions.create(
  {
    amount: { amount: "249.90", currency: "PEN" },
    paymentMethodTypes: ["INTEROPERABLE_QR", "BANK_TRANSFER"],
    description: "Zapatillas running talla 42",
    customer: { id: "cus_01ABC" },
    // customer: { name: §§SLOT_7§§, email: §§SLOT_8§§ },
  },
  { idempotencyKey: `order-${orderId}` },
);

// window.Kuti.open({ checkoutUrl: session.checkoutUrl, onSuccess, onFailure })
Confirmar pagots
const intent = await kuti.paymentIntents.retrieve(paymentIntentId);
if (intent.status === "SUCCEEDED") {
  // fulfill order
}
Webhook (Express)ts
import { verifyWebhookSignature, KutiSignatureVerificationError } from "@kuti-pe/node";
import express from "express";

const app = express();

app.post("/webhooks/kuti", express.text({ type: "*/*" }), (req, res) => {
  try {
    verifyWebhookSignature(
      req.body, // raw body
      req.header("X-Kuti-Signature")!,
      req.header("X-Kuti-Timestamp")!,
      process.env.KUTI_WEBHOOK_SECRET!,
    );
  } catch (err) {
    if (err instanceof KutiSignatureVerificationError) {
      return res.status(400).send("Invalid signature");
    }
    throw err;
  }

  const event = JSON.parse(req.body);
  // payment.succeeded | checkout.session.completed
  res.sendStatus(200);
});

Siguiente