Ir al contenido

Crear cobro

Crea un payment intent (cobro). Devuelve QR interoperable, código de pago de servicios (institución KUTI) y link de checkout.

POSThttps://api.kuti.pe/v1/payment-intents
amount.amount es decimal como string (nunca float). payment_method_types: INTEROPERABLE_QR y/o BANK_TRANSFER. En banca el cliente busca la institución KUTI. Cliente: usa customer (objeto) — con id de uno existente, o datos nuevos (persona = INDIVIDUAL con given_name/family_name; empresa = COMPANY con legal_name). customer_id es un atajo equivalente a customer.id. Idempotency-Key (UUID v4) recomendada.

Parámetros del body

amount
objectrequerido
Monto a cobrar.
amount
stringrequerido
Decimal como string.Ej: 50.00
currency
stringrequerido
ISO 4217.Ej: PEN
payment_method_types
arrayrequerido
INTEROPERABLE_QR (Yape/Plin/billeteras) y/o BANK_TRANSFER (pago de servicios → institución KUTI).Ej: ["INTEROPERABLE_QR", "BANK_TRANSFER"]
customer
objectopcional
Cliente del cobro. Orden: id (existente) → external_id → documento → crea uno nuevo. Si envías id, se ignora el resto.
id
stringopcional
Customer existente (cus_…). Si viene, se ignora el resto.Ej: cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3
type
stringopcional
INDIVIDUAL (persona) o COMPANY (empresa).Ej: INDIVIDUAL
given_name
stringopcional
Nombres. Requerido si type = INDIVIDUAL (persona).Ej: María
family_name
stringopcional
Apellidos. Requerido si type = INDIVIDUAL (persona).Ej: López
legal_name
stringopcional
Razón social. Requerido si type = COMPANY (empresa).
email
stringopcional
Correo.Ej: maria@example.com
phone
stringopcional
Teléfono E.164.Ej: +51987654321
external_id
stringopcional
Id en tu sistema.Ej: cust_erp_4821
document
objectopcional
Documento.
type
stringopcional
DNI, RUC, CE, …Ej: DNI
number
stringopcional
Número.Ej: 45678912
customer_id
stringopcional
Atajo: mismo efecto que customer.id. Si lo envías, se ignora customer.Ej: cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3
category_id
stringopcional
Categoría de cobro opcional (collection-categories).
requires_customer_info
booleanopcional
Si true y no hay cliente: el checkout pide nombre/correo al pagador antes de pagar. Default false.
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 librerías estándar (aún sin SDK)

cURL Request
curl -s 'https://api.kuti.pe/v1/payment-intents' \
  -X POST \
  -H 'Authorization: Bearer kuti_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440020' \
  -d '{
  "amount": {
    "amount": "50.00",
    "currency": "PEN"
  },
  "payment_method_types": [
    "INTEROPERABLE_QR",
    "BANK_TRANSFER"
  ],
  "customer": {
    "type": "INDIVIDUAL",
    "given_name": "María",
    "family_name": "López",
    "email": "maria@example.com",
    "phone": "+51987654321",
    "document": {
      "type": "DNI",
      "number": "45678912"
    }
  },
  "description": "Pedido #1042",
  "external_reference": "order-1042"
}'
Librería estándar · sin SDK propio
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",
      "document_value": "45678912",
      "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"
  }
}