Crear una sesión de Web Checkout

Estado documental: Propuesto. Los endpoints, campos y límites exactos deberán confirmarse antes de producción.

Objetivo

Crear una orden y obtener una sesión temporal de Web Checkout asociada con una transacción específica.

Quién crea la sesión

La sesión debe crearse desde el servidor de la empresa, nunca desde código frontend con credenciales privadas.

Navegador
    → solicita iniciar el pago al servidor de la empresa

Servidor de la empresa
    → se autentica frente a YUPY
    → envía los datos de la transacción

YUPY
    → valida
    → crea la orden
    → crea la sesión
    → devuelve checkout_url

Servidor de la empresa
    → entrega checkout_url al navegador

Operación lógica propuesta

POST <YUPY_API_BASE_URL>/v1/payment-orders
Authorization: Bearer <PRIVATE_CREDENTIAL>
Idempotency-Key: <UNIQUE_KEY>
Content-Type: application/json

La ruta exacta puede cambiar durante la implementación. La operación lógica es: crear una orden solicitando una experiencia de Web Checkout.

Campos mínimos

{
  "external_transaction_id": "ORDER-10482",
  "amount": "85.50",
  "currency": "PEN",
  "integration_experience": "web_checkout",
  "presentation_strategy": "yupy_checkout"
}

`external_transaction_id`

ID estable y único de la venta en la plataforma de la empresa.

`amount`

Monto decimal enviado como string.

`currency`

Moneda de la operación. La primera implementación está orientada a PEN.

Datos opcionales

La empresa puede enviar información adicional para personalizar y correlacionar la experiencia.

{
  "buyer": {
    "external_id": "CUSTOMER-883",
    "first_name": "María",
    "last_name": "Ramos",
    "phone": "+51999999999",
    "email": "maria@example.com"
  },
  "merchant_context": {
    "website_id": "WEBSITE-01",
    "brand_id": "BRAND-01",
    "customer_account_id": "CLIENT-448"
  },
  "presentation": {
    "branding_profile_id": "BRANDING-01",
    "locale": "es-PE",
    "return_url": "https://merchant.example/payment-return"
  },
  "context": {
    "location_id": "STORE-01",
    "seller_id": "SELLER-08",
    "shift_id": "SHIFT-PM",
    "terminal_id": "POS-03",
    "custom_reference_1": "ROUTE-184",
    "custom_reference_2": "SEAT-12A"
  }
}

Los nombres son propuestos. El contrato final puede reagruparlos.

Marca y logotipo

La opción preferida es enviar branding_profile_id, asociado con una marca previamente configurada y aprobada.

En el futuro el contrato puede admitir un logo_url validado. No debe permitirse cargar contenido remoto arbitrario sin controles de seguridad, tamaño, tipo y origen.

Perfil de cobro

La solicitud puede indicar:

"collection_profile_id": "COLLECTION-PERU-01"

El perfil resuelve los QR y cuentas habilitados. Cuando la empresa tenga un único perfil, YUPY puede aplicar uno predeterminado configurado expresamente.

Medios solicitados

La plataforma puede solicitar un subconjunto de los medios habilitados:

"requested_payment_methods": [
  "yape_qr",
  "plin_qr",
  "bank_transfer"
]

YUPY no debe habilitar un medio no autorizado en el perfil.

Vigencia solicitada

"expires_in_seconds": 900

YUPY puede aceptar, ajustar o rechazar este valor según configuración. La respuesta debe devolver una fecha absoluta expires_at.

Solicitud completa propuesta

{
  "external_transaction_id": "ORDER-10482",
  "created_at": "2026-07-20T14:30:00-05:00",
  "amount": "85.50",
  "currency": "PEN",
  "integration_experience": "web_checkout",
  "presentation_strategy": "yupy_checkout",
  "collection_profile_id": "COLLECTION-PERU-01",
  "requested_payment_methods": [
    "yape_qr",
    "plin_qr",
    "bank_transfer"
  ],
  "expires_in_seconds": 900,
  "buyer": {
    "external_id": "CUSTOMER-883",
    "first_name": "María",
    "last_name": "Ramos"
  },
  "merchant_context": {
    "website_id": "WEBSITE-01",
    "brand_id": "BRAND-01",
    "customer_account_id": "CLIENT-448"
  },
  "presentation": {
    "branding_profile_id": "BRANDING-01",
    "locale": "es-PE",
    "return_url": "https://merchant.example/payment-return"
  },
  "context": {
    "location_id": "STORE-01",
    "seller_id": "SELLER-08",
    "custom_reference_1": "ROUTE-184",
    "custom_reference_2": "SEAT-12A"
  }
}

Respuesta propuesta

{
  "yupy_transaction_id": "ypt_01JXYZ...",
  "external_transaction_id": "ORDER-10482",
  "checkout_session": {
    "checkout_session_id": "ycs_01JXYZ...",
    "checkout_url": "https://<YUPY_CHECKOUT_HOST>/checkout/<OPAQUE_TOKEN>",
    "expires_at": "2026-07-20T14:45:02-05:00"
  },
  "state": {
    "operational": "active",
    "financial": "awaiting_payment",
    "delivery": "not_applicable"
  }
}

La URL es el dato principal para el frontend

El servidor entrega checkout_url al navegador. El frontend puede:

redirigir;
abrir una nueva vista;
pasarla al SDK;
abrirla dentro de un webview autorizado.

El frontend no necesita conocer ni reconstruir la relación entre token, orden, perfil de cobro o comprador.

Token opaco

La URL contiene o referencia un token opaco generado por YUPY.

El token debe:

estar asociado con una sola sesión;
identificar indirectamente una sola transacción;
tener alcance limitado;
tener vigencia;
no revelar el ID externo;
no ser una credencial general de API;
no permitir consultar otras operaciones.

Idempotencia

Repetir la misma solicitud con la misma clave y el mismo payload no debe crear otra venta ni otra sesión independiente sin intención explícita.

Misma Idempotency-Key + mismo payload
→ misma operación o respuesta equivalente

Misma Idempotency-Key + payload diferente
→ conflicto

Validaciones

YUPY debe validar:

autenticación;
permisos;
ID externo;
monto y moneda;
perfil de cobro;
medios solicitados;
URLs de retorno;
perfil visual;
formatos de comprador;
referencias y metadata;
idempotencia.

Errores

La API debe devolver errores estructurados y un request_id. No debe devolver una URL de checkout si la orden o sesión no fue creada correctamente.

Persistencia recomendada

La empresa debe almacenar:

external_transaction_id
yupy_transaction_id
checkout_session_id
checkout_url o referencia segura
expires_at
estado conocido
event_id procesados

La URL contiene una credencial temporal y debe tratarse como dato sensible. No debe registrarse completa en logs públicos, analítica de terceros ni herramientas que puedan exponerla.

Criterios de aceptación

La creación ocurre desde backend.
Las credenciales privadas no llegan al navegador.
Monto, moneda e ID externo son obligatorios.
Los datos opcionales se validan.
El perfil de cobro se resuelve.
YUPY crea una sola orden idempotente.
YUPY devuelve una URL completa.
El token no revela información transaccional.
La URL abre la sesión correcta.
El frontend puede entregarla al SDK sin reconstruirla.
La empresa conserva correlación y eventos.

API Technical Docs