Ir al contenido

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. Idempotency-Key recomendada. El checkout_url ya incluye el client_secret para abrir el modal/embed.

Parámetros del body

amount
objectrequerido
Monto a cobrar.
amount
stringrequerido
Decimal como string.Ej: 249.90
currency
stringrequerido
ISO 4217.Ej: PEN
payment_method_types
arrayrequerido
INTEROPERABLE_QR y/o BANK_TRANSFER.Ej: ["INTEROPERABLE_QR", "BANK_TRANSFER"]
customer
objectopcional
Opcional. Orden: id (cus_…) → external_id → name/email/phone (crea cliente).
id
stringopcional
Customer existente.Ej: cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3
external_id
stringopcional
Id en tu sistema.Ej: cust_erp_4821
name
stringopcional
Nombre completo.Ej: María López
email
stringopcional
Correo.Ej: maria@example.com
phone
stringopcional
E.164.Ej: +51987654321
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 librerías estándar (aún sin SDK)

cURL Request
curl -s 'https://api.kuti.pe/v1/checkout-sessions' \
  -X POST \
  -H 'Authorization: Bearer kuti_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440030' \
  -d '{
  "amount": {
    "amount": "249.90",
    "currency": "PEN"
  },
  "payment_method_types": [
    "INTEROPERABLE_QR",
    "BANK_TRANSFER"
  ],
  "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,
  "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"
  }
}