Crear cobro

Crea un Payment Intent que representa un cobro único por un monto determinado. Puedes indicar qué métodos de pago estarán disponibles para el pagador. KUTI devuelve los datos necesarios para cada método habilitado y un único checkout_url.

POSThttps://api.kuti.pe/v1/payment-intents

Solo PEN · amount como string · en banca: institución KUTI. Preferí customer.id; si no, type + datos. Idempotency-Key recomendada.

Parámetros del body

Campo

Descripción

amount

objectrequerido

Monto a cobrar.

amount

stringrequerido

Decimal como string.Ej: 50.00

currency

stringrequerido

Solo PEN por ahora.Ej: PEN

payment_method_types

arrayrequerido

INTEROPERABLE_QR (Yape/Plin/billeteras) y/o BANK_TRANSFER (pago de servicios → institución KUTI). YAPE (Yape afiliado) exige cliente; disponible en producción próximamente.Ej: ["INTEROPERABLE_QR", "BANK_TRANSFER"]

customer

objectopcional

Cliente del cobro — misma forma que POST /customers. Orden: id (existente) → external_id → documento → correo → teléfono → crea uno nuevo. Así el mismo pagador no se duplica aunque solo envíes su correo. Si envías id, se ignora el resto (salvo custom_fields).

id

stringopcional

Customer existente (cus_…). Si viene, se ignora el resto.Ej: cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3

type

stringopcional

INDIVIDUAL (persona) o COMPANY (empresa). Obligatorio al crear uno nuevo.Ej: INDIVIDUAL

first_name

stringopcional

Nombres. Requerido si type = INDIVIDUAL y el cliente no existe.Ej: María

last_name

stringopcional

Apellidos. Requerido si type = INDIVIDUAL y el cliente no existe.Ej: López

company_name

stringopcional

Razón social. Requerido si type = COMPANY y el cliente no existe.

email

stringopcional

Correo. Si ya tienes un cliente con ese correo, se reutiliza (no distingue mayúsculas).Ej: maria@example.com

phone

stringopcional

Teléfono. Un celular peruano se guarda siempre como +51 y sus 9 dígitos, lo envíes como lo envíes (999111222, 51999111222 o +51 999 111 222 quedan como +51999111222). Si no hubo coincidencia por correo, se reutiliza el cliente con ese teléfono.Ej: +51987654321

external_id

stringopcional

Id en tu sistema. Si ya existe un customer con ese external_id, se reutiliza.Ej: cust_erp_4821

document

objectopcional

Documento: { type, number, country }. Si ya tienes un cliente con ese documento, se reutiliza (basta el número).

type

stringopcional

DNI, RUC, CE, … Opcional: se deduce del número.Ej: DNI

number

stringrequerido

Número.Ej: 45678912

country

stringopcional

ISO 3166-1 alpha-2. Por defecto PE.Ej: PE

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). Se guardan en el cliente (nuevo o existente) y quedan congelados en el cobro. Una key desconocida o un valor inválido devuelve 422 con el detalle custom_fields.<key>.Ej: {"grade": "quinto", "student_code": "2026-00781"}

receivable_id

stringopcional

Cuenta por cobrar (rcv_…) a la que se imputa este cobro.Ej: rcv_01J8Z3K4M5N6P7Q8R9S0T1U2V3

category_id

stringopcional

Categoría de cobro opcional (collection-categories).

requires_customer_info

booleanopcional

Si true y no hay customer: el checkout pide nombre/correo al pagador antes de pagar. Default false.

send_via

arrayopcional

Por dónde se le envía el cobro al cliente al crearlo: "EMAIL", "WHATSAPP". Sin este campo = ["EMAIL"] (por correo si el cliente tiene email). [] = no enviar nada. WHATSAPP necesita teléfono del cliente (+51…), si no responde 422; consume 1 moneda de WhatsApp y, si el envío falla, el cobro igual se crea.Ej: ["EMAIL", "WHATSAPP"]

saved_payment_methods

stringopcional

enabled = durante 30 minutos el enlace le muestra a tu cliente su Yape guardado para pagar con un toque. Úsalo solo si le envías el enlace a un canal suyo. Requiere cliente y YAPE en payment_method_types. Por defecto disabled. Ver Medios de pago guardados.

payment_method

stringopcional

Medio guardado del cliente a debitar (pm_…, de GET /customers/{id}/payment-methods). Se usa junto con confirm: true.Ej: pm_01J8Z3K4M5N6P7Q8R9S0T1U2V3

confirm

booleanopcional

true = crea el cobro y debita de inmediato el payment_method, sin tu cliente presente. El resultado viene en last_saved_method_payment. Si se deniega, el cobro queda abierto y su enlace sigue sirviendo.

description

stringopcional

Texto del cobro.Ej: Pedido #1042

external_reference

stringopcional

Referencia en tu sistema.Ej: order-1042

expires_at

stringopcional

Vencimiento del cobro (UTC ISO-8601).Ej: 2026-09-05T23:59:59Z

merchant_id

stringopcional

Opcional. Debe coincidir con el merchant de la key.

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 intent = await kuti.paymentIntents.create(
  {
    amount: { amount: "50.00", currency: "PEN" },
    paymentMethodTypes: ["INTEROPERABLE_QR","BANK_TRANSFER"],
    customer: { id: "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3" },
    // customer: { type: §§SLOT_6§§, firstName: §§SLOT_7§§, lastName: §§SLOT_8§§, email: §§SLOT_9§§, phone: §§SLOT_10§§, document: { type: §§SLOT_11§§, number: §§SLOT_12§§ } },
    description: "Pedido #1042",
    externalReference: "order-1042",
  },
  { idempotencyKey: "550e8400-e29b-41d4-a716-446655440020" },
);

console.log(intent.checkoutUrl);

SDK oficial · guía en /sdks

Response

Elige un ejemplo de respuesta:

application/json

201Created

{
  "success": true,
  "message": "Payment intent created",
  "data": {
    "id": "pi_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "merchant_id": "mer_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "livemode": true,
    "customer": {
      "id": "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
      "type": "INDIVIDUAL",
      "first_name": "María",
      "last_name": "López",
      "name": "María López",
      "document": {
        "type": "DNI",
        "number": "45678912",
        "country": "PE"
      },
      "email": "maria@example.com"
    },
    "amount": {
      "amount": "50.00",
      "currency": "PEN"
    },
    "status": "PENDING",
    "payment_method_types": [
      "INTEROPERABLE_QR",
      "BANK_TRANSFER"
    ],
    "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"
      }
    },
    "checkout_url": "https://pay.kuti.pe/c/A3F9K2P7QM",
    "client_secret": "pi_01J8…_secret_ab12cd34ef56gh78ij90kl12",
    "description": "Pedido #1042",
    "external_reference": "order-1042",
    "fee_preview": {
      "gross": {
        "amount": "50.00",
        "currency": "PEN"
      },
      "fee": {
        "amount": "-1.77",
        "currency": "PEN"
      },
      "fee_tax": {
        "amount": "-0.27",
        "currency": "PEN"
      },
      "net": {
        "amount": "48.23",
        "currency": "PEN"
      },
      "available_in_days": 2
    },
    "created_at": "2026-09-04T10:48:59.556906Z"
  }
}