Crear Web Checkout y consultar Payment Orders

Estado documental: Implementado y verificado en Producción.

Esta página describe el contrato público productivo para iniciar un cobro Web en YUPY y la relación del checkout con su Payment Order.

Superficie pública

El integrador no crea directamente la Payment Order mediante el contrato interno del Orchestrator. Para Web Checkout, la entrada pública productiva es:

POST /v1/checkouts

Backend del comercio
    ↓
POST /v1/checkouts
    ↓
YUPY autentica y deriva client_id
    ↓
resuelve Counter virtual Web
    ↓
resuelve policy + instrumento + timeout
    ↓
Payment Order Orchestrator
    ↓
checkout_url + delivery

Crear Web Checkout

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

Ejemplo:

{
  "amount": "85.50",
  "currency": "PEN",
  "payment_method": "qr",
  "source_reference": "ORDER-10482",
  "business_context": {
    "order_id": "ORDER-10482",
    "route": "Lima-Arequipa",
    "seat": "12A"
  }
}

Campos principales

amount: monto esperado.
currency: moneda.
payment_method: para el flujo QR actual, qr.
source_reference: referencia externa opcional/recomendada.
payer: datos auxiliares del pagador cuando estén disponibles.
business_context: contexto propio del negocio.

source_reference no sustituye Idempotency-Key.

Datos que el caller no selecciona

client_id
counter_id
location_id
instrument_id
QR ID
slot
pool
policy_config
timeout_seconds

client_id deriva de la credencial autenticada. Counter, instrumento, policy y timeout son resueltos internamente por YUPY.

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://..."
  }
}

Para frontend, el dato principal es checkout_url. No reconstruir URL, token ni QR. Para QR, utilizar exactamente delivery.image_url.

Idempotencia

Misma Idempotency-Key + mismo payload lógico
→ misma operación lógica
→ mismo checkout_uid
→ mismo payment_order_uid
→ no crear otra Payment Order

YUPY puede reemitir o rotar el token del checkout durante un replay idempotente. Si ocurre, el token anterior deja de ser válido.

Presentación

Crear el checkout no equivale a presentarlo. En Browser Checkout, presented se registra cuando el QR carga realmente.

Timeout

POO gobierna el timeout. El Browser usa el expires_at canónico para el countdown y al llegar a cero vuelve a consultar status en lugar de declarar timeout localmente.

“Ya pagué”

En modo normal, Ya pagué registra en POO la declaración canónica PAYMENT_DECLARED y luego continúa consultando el estado real de la Payment Order. La declaración es no terminal: no marca pagado, no establece confirmed_at y no sustituye la confirmación financiera.

El botón no confirma el pago y no fuerza pagado. Solo ejecuta una consulta inmediata del estado canónico.

Consultar Payment Order

Cuando un backend autorizado necesite confirmar el estado financiero, debe utilizar la superficie autenticada de Payment Orders con el payment_order_uid devuelto por YUPY. El resultado visual del SDK no sustituye esa confirmación backend cuando el proceso comercial la requiera.

Estados terminales del checkout

pagado
cancelado
timeout
failed

El cierre manual del modal es distinto: cancelled_by_user, terminal=false. Cerrar la ventana no cancela la Payment Order.

Seguridad

Crear checkout desde backend.
No exponer Client Secret ni Bearer al navegador.
El token queda en el fragment de la URL.
No exponer al parent SDK checkout_token, counter_id, client_id, payment_order_uid ni instrument_id.
No fabricar mensajes yupy.checkout.result.

API Technical Docs