Web Checkout SDK en Sandbox

Estado documental: Implementado y verificado en YUPY Sandbox.

Esta guía explica cómo crear una orden de Web Checkout en el ambiente Sandbox, obtener la checkout_url generada por YUPY y mostrarla dentro de una aplicación web mediante el SDK oficial.

Qué está disponible

• Autenticación Sandbox mediante client_id y client_secret.
• Creación de órdenes con integration_experience: "web_checkout".
• Generación de una sesión temporal con token opaco.
• Respuesta con una checkout_url completa.
• SDK JavaScript versionado para montar el checkout dentro de un contenedor.
• Instancia retornada por el SDK con método unmount().

El Sandbox no mueve dinero real. Las credenciales Sandbox no deben utilizarse contra producción.

URLs del ambiente Sandbox

Flujo seguro de integración

Backend del cliente
  → intercambia Client ID + Client Secret Sandbox
  → recibe un Bearer temporal
  → crea una orden Web Checkout
  → recibe checkout_url

Frontend del cliente
  → carga yupy-checkout.js
  → entrega checkout_url a YupyCheckout.mount()
  → YUPY muestra el checkout dentro de un iframe seguro

El client_secret y el Bearer pertenecen al backend. No deben enviarse al navegador, almacenarse en JavaScript ni incorporarse en la URL del checkout.

1. Obtener un Bearer temporal

La autenticación se ejecuta desde el backend del integrador.

curl -X POST "https://sandbox-api.yupy.us/v1/auth/token"   -H "Content-Type: application/json"   -d '{
    "client_id": "cli_sbx_REEMPLAZAR",
    "client_secret": "REEMPLAZAR_CON_SECRET_SANDBOX",
    "grant_type": "client_credentials"
  }'

La respuesta contiene un access_token temporal. Ese valor se utiliza como Bearer al crear la orden.

2. Crear una orden de Web Checkout

La solicitud debe incluir un Idempotency-Key único para la operación.

curl -X POST "https://sandbox-api.yupy.us/v1/payment-orders"   -H "Authorization: Bearer ACCESS_TOKEN_TEMPORAL"   -H "Idempotency-Key: orden-demo-20260805-001"   -H "Content-Type: application/json"   -d '{
    "external_transaction_id": "VENTA-DEMO-001",
    "amount": "85.50",
    "currency": "PEN",
    "buyer_name": "Cliente Demo",
    "integration_experience": "web_checkout",
    "expires_in_seconds": 900
  }'

Campos principales

3. Usar la checkout_url devuelta

La respuesta de creación incluye la sesión de checkout y una URL completa. La forma relevante es:

{
  "yupy_transaction_id": "ypt_sbx_...",
  "checkout_session": {
    "checkout_session_id": "cks_sbx_...",
    "checkout_url": "https://sandbox-api.yupy.us/sandbox/checkout?token=TOKEN_OPACO",
    "expires_at": "..."
  },
  "request_id": "req_sbx_..."
}

El integrador debe utilizar exactamente la checkout_url recibida. No debe extraer el token, reconstruir la URL ni asumir su formato interno.

4. Cargar el SDK

<script src="https://sandbox-api.yupy.us/sdk/v1/yupy-checkout.js"></script>

5. Montar el checkout

<div id="yupy-checkout"></div>

<script>
  const checkout = YupyCheckout.mount({
    container: "#yupy-checkout",
    checkoutUrl: checkoutUrlDevueltaPorElBackend,
    height: 720
  });
</script>

Parámetros de mount()

6. Desmontar el checkout

mount() devuelve una instancia que permite retirar el iframe:

checkout.unmount();

Desmontar el iframe no cancela la orden ni modifica su estado financiero. Solo retira la presentación visual de la página actual.

API pública de esta versión

YupyCheckout.mount({
  container,
  checkoutUrl,
  height
})

checkout.unmount()

La versión Sandbox actualmente implementada expone mount() y unmount(). Un método open() o un modal administrado por el SDK no forman parte de esta versión.

Seguridad

• El client_secret se usa únicamente en el backend.
• El Bearer temporal no debe llegar al navegador.
• La checkout_url contiene un token público limitado a una sola sesión.
• El token debe tratarse como información sensible y no registrarse completo en logs.
• La URL debe cargarse mediante HTTPS.
• Una sesión vencida muestra un estado de checkout expirado y no permite reutilizar la operación.
• La confirmación definitiva del resultado debe depender de la API y los webhooks, no de la presencia del iframe.

Errores frecuentes

Prueba mínima recomendada

1. Usar una credencial Sandbox activa.
2. Obtener un Bearer temporal desde el backend.
3. Crear una orden con integration_experience: "web_checkout".
4. Confirmar que la respuesta contenga checkout_session.checkout_url.
5. Cargar el SDK versionado.
6. Montar la URL dentro de un contenedor.
7. Verificar que el checkout muestre la orden correcta.
8. Desmontar y volver a montar la misma URL sin crear otra orden.
9. Confirmar que una URL vencida muestre el estado expirado.

Documentos relacionados

• Autenticación y credenciales de integración
• Crear, consultar y cancelar transacciones
• SDK, URL y token de Web Checkout
• Casos mínimos de prueba