Ir al contenido
KUTI

Crear sesión de checkout

Crea una sesión de checkout (cargo único) y el payment intent asociado. Devuelve checkout_url para Checkout.js o pay.kuti.pe.

POSThttps://api.kuti.pe/v1/checkout-sessions
Autoriza con secret o publishable key. amount.currency: solo PEN por ahora. Idempotency-Key recomendada. El checkout_url ya incluye el client_secret para abrir el modal/embed.

Parámetros del body

Campo
Descripción
amount
objectrequerido
Monto a cobrar.
amount
stringrequerido
Decimal como string.Ej: 249.90
currency
stringrequerido
Solo PEN por ahora.Ej: PEN
payment_method_types
arrayrequerido
INTEROPERABLE_QR y/o BANK_TRANSFER.Ej: ["INTEROPERABLE_QR", "BANK_TRANSFER"]
customer
objectopcional
Opcional — misma forma que POST /customers, todo opcional (con solo correo o teléfono se crea un cliente sin nombre). Orden: id (cus_… existente) → external_id → documento → crea uno. Si envías id, se ignora el resto.
id
stringopcional
Customer existente (cus_…). Preferido si ya lo creaste con POST /customers.Ej: cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3
external_id
stringopcional
Id en tu sistema.Ej: cust_erp_4821
first_name
stringopcional
Nombres.Ej: María
last_name
stringopcional
Apellidos.Ej: López
document
objectopcional
Documento { type, number, country } — type opcional (se deduce del número). Reutiliza al cliente si ya existe.
email
stringopcional
Correo.Ej: maria@example.com
phone
stringopcional
E.164.Ej: +51987654321
custom_fields
objectopcional
Campos personalizados que definiste en Ajustes → Clientes → Campos (ver Campos de cliente). Objeto { key: valor }: texto, número como texto ("12.5"), fecha "YYYY-MM-DD", hora "HH:mm", true/false, key de opción (SELECT; también acepta la etiqueta) o lista de keys (MULTISELECT). Una key desconocida o un valor inválido devuelve 422 con el detalle custom_fields.<key>.Ej: {"grade": "quinto", "student_code": "2026-00781"}
description
stringopcional
Texto del cobro.Ej: Pedido #1042
external_reference
stringopcional
Referencia en tu sistema.Ej: order-1042
success_url
stringopcional
URL a la que redirigir tras pagar (opcional).Ej: https://tienda.pe/pago/ok
expires_at
stringopcional
Vencimiento (UTC ISO-8601).
metadata
objectopcional
Pares string→string libres.

Language

Credentials

Header

Authorization

Secret key de developer · ejemplos con SDK oficial

API Request
$ npm install @kuti-pe/node
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"],
    customer: { firstName: "María", lastName: "López", email: "maria@example.com", phone: "+51987654321" },
    description: "Pedido #1042",
    externalReference: "order-1042",
  },
  { idempotencyKey: "550e8400-e29b-41d4-a716-446655440030" },
);

console.log(session.checkoutUrl);
SDK oficial · guía en /sdks
Response

Elige un ejemplo de respuesta:

application/json
201Created
{
  "success": true,
  "data": {
    "id": "cs_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "merchant_id": "mer_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "payment_intent_id": "pi_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "amount": {
      "amount": "249.90",
      "currency": "PEN"
    },
    "status": "OPEN",
    "description": "Pedido #1042",
    "client_secret": "cs_secret_ab12cd34ef56",
    "checkout_url": "https://pay.kuti.pe/embed?cs=cs_secret_ab12cd34ef56",
    "payment_method": {
      "qr": {
        "type": "INTEROPERABLE_QR",
        "payload": "00020101021226...",
        "expires_at": "2026-09-05T23:59:59Z"
      },
      "payment_code": {
        "type": "BANK_TRANSFER",
        "code": "41041172",
        "expires_at": "2026-09-05T23:59:59Z"
      }
    },
    "created_at": "2026-09-04T10:48:59.556906Z"
  }
}