Crear una sesión de Web Checkout

Contrato vigente de Web Checkout

POST /v1/checkouts requiere:

external_transaction_id: identificador de la transacción en el sistema del comercio.
amount: monto.
currency: moneda ISO de 3 letras, por ejemplo PEN.

Campos opcionales:

payment_method: por defecto qr.
payer.first_name y payer.last_name: si el comercio conoce el nombre del pagador/cliente.
timeout_seconds: vigencia solicitada por el comercio.

YUPY deriva internamente channel=web y resuelve client, counter, location, instrument y policy. Para correlación comercial del Web Checkout use external_transaction_id; source_reference no debe usarse como un segundo identificador comercial.

Hoy, cuando el comercio envía timeout_seconds, ese valor reemplaza el timeout fijo de policy para esa operación. Cuando exista el motor automático de cálculo de timeout, el valor calculado por YUPY tendrá precedencia.

{
  "external_transaction_id": "TX-12345",
  "amount": "125.50",
  "currency": "PEN",
  "payment_method": "qr",
  "payer": {
    "first_name": "Juan",
    "last_name": "Perez"
  },
  "timeout_seconds": 240
}

Respuesta inmediata HTTP 201

{
  "external_transaction_id": "TX-12345",
  "checkout_uid": "chk_...",
  "checkout_token": "cks_...",
  "checkout_url": "https://api.yupy.us/v1/checkouts/browser#token=...",
  "payment_order_uid": "po_...",
  "status": "pending",
  "amount": "125.50",
  "currency": "PEN",
  "payment_method": "qr",
  "channel": "web",
  "checkout_created_at": "2026-08-28T03:39:50Z",
  "timeout_seconds": 240,
  "delivery": {}
}

Esta respuesta confirma la creación del Checkout y de la Payment Order asociada. Las notificaciones posteriores de estado se documentan por separado.

Estado documental: Implementado y verificado en Producción.

Esta guía explica cómo crear una sesión de Web Checkout desde el backend del integrador y obtener la checkout_url que el frontend abrirá con el SDK de YUPY.

Flujo productivo

Backend
  → POST /v1/auth/token
  → POST /v1/checkouts + Idempotency-Key

YUPY
  → deriva client_id desde Auth
  → resuelve Counter virtual Web
  → resuelve policy, instrumento y timeout
  → crea Payment Order
  → crea checkout
  → devuelve checkout_url

Frontend
  → recibe checkout_url desde su backend
  → YupyCheckout.open(checkout_url)

Endpoint

POST https://api.yupy.us/v1/checkouts
Authorization: Bearer <ACCESS_TOKEN>
Idempotency-Key: <UNIQUE_KEY>
Content-Type: application/json

Request mínimo

{
  "amount": "85.50",
  "currency": "PEN",
  "payment_method": "qr"
}

Referencia comercial opcional:

{
  "source_reference": "ORDER-10482"
}

También puede incluir payer y business_context.

Datos internos que no envía el integrador como autoridad

client_id
counter_id
location_id
instrument_id
QR ID
pool
slot
policy_config
timeout_seconds

Counter virtual Web

client_id autenticado
    ↓
Counter virtual Web canónico
    ↓
master_data.resolve_checkout_context(...)
    ↓
instrumento + timeout + policy
    ↓
POO

La concurrencia runtime pertenece a POO; el integrador no administra slots.

Respuesta

{
  "checkout_uid": "chk_...",
  "payment_order_uid": "po_...",
  "checkout_token": "<OPAQUE_CHECKOUT_TOKEN>",
  "checkout_url": "https://api.yupy.us/v1/checkouts/browser#token=...",
  "status": "pending",
  "delivery": {
    "type": "qr",
    "image_url": "https://..."
  }
}

Los valores son opacos. No reconstruir URLs ni QR.

Uso del checkout_url

const result = await YupyCheckout.open(checkoutUrl);

El frontend no necesita conocer payment_order_uid para presentar el checkout.

Delivery

Para QR, el Browser utiliza exactamente delivery.image_url.

Timeout

YUPY resuelve el timeout; POO devuelve el expires_at real y Browser muestra el countdown a partir de ese timestamp.

Presentación

La sesión no se considera presentada al crearla. Browser registra presented cuando el QR carga efectivamente.

Seguridad

Crear checkout solo desde backend.
No exponer Client Secret ni Bearer al navegador.
Tratar checkout_url como credencial temporal.
Token en fragment, no query string.
No seleccionar Counter ni instrumento desde frontend.

API Technical Docs