Manual de integración — Web Checkout

Estado: Implementado y verificado para Web Checkout QR / Yape-Plin.

Este manual reúne el flujo mínimo que necesita un desarrollador para integrar YUPY Web Checkout: el backend crea el checkout, el frontend lo abre con el SDK y el backend recibe los webhooks.

1. Flujo

Backend → token → POST /v1/checkouts → checkout_url
Frontend → YupyCheckout.open(checkout_url) → QR → resultado
Backend ← webhooks de YUPY

2. Autenticación

POST https://api.yupy.us/v1/auth/token
Content-Type: application/json

{
  "client_id": "<YUPY_CLIENT_ID>",
  "client_secret": "<YUPY_CLIENT_SECRET>"
}

El client_secret y el Bearer son server-to-server y no se exponen al navegador.

3. Crear el checkout

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

Body mínimo: solo 3 valores obligatorios.

{
  "amount": "100.00",
  "currency": "PEN",
  "external_transaction_id": "PEDIDO-123"
}

payment_method existe en el contrato y actualmente su valor por defecto es qr. El Web Checkout certificado hoy corresponde a QR Yape/Plin.

Nombre del comprador

Si el comercio ya conoce el nombre, recomendamos enviarlo. No es obligatorio para crear el checkout, pero ayuda en trazabilidad, soporte y conciliación.

"payer": {
  "first_name": "Juan",
  "last_name": "Perez"
}

4. Idempotencia

external_transaction_id identifica la venta del comercio. Idempotency-Key identifica técnicamente el intento de creación y evita duplicados.

external_transaction_id = PEDIDO-123
intento 1 = PEDIDO-123-1
nuevo checkout legítimo = PEDIDO-123-2

5. Qué devuelve YUPY

Guardar como mínimo external_transaction_id, checkout_uid y payment_order_uid. El frontend recibe checkout_url.

{
  "external_transaction_id": "PEDIDO-123",
  "checkout_uid": "chk_...",
  "checkout_url": "https://api.yupy.us/v1/checkouts/browser#token=...",
  "payment_order_uid": "po_...",
  "status": "pending"
}

No reconstruir checkout_url; se utiliza exactamente como YUPY la devuelve.

6. SDK

<script src="https://api.yupy.us/v1/checkouts/browser/sdk.js"></script>

<script>
YupyCheckout.open(checkoutUrl, {
  onResult(result) {
    console.log(result);
  }
});
</script>

El SDK administra modal, iframe, Browser Checkout y QR.

7. Declarar que el comprador ya pagó

En el Browser Checkout el comprador dispone del botón Ya pagué. Este botón representa una declaración de pago; no representa una confirmación financiera.

Al presionarlo, Web Checkout registra en el Payment Order Orchestrator la capability canónica PAYMENT_DECLARED y luego continúa consultando el estado real de la Payment Order.

La declaración es explícitamente no terminal:

• no cambia el estado a pagado;
• no cambia el lifecycle de la Payment Order;
• no escribe confirmed_at;
• no libera la ocupación/runtime slot;
• puede repetirse de forma idempotente.

La declaración conserva provenance del canal Web/SDK para que otros componentes de YUPY, como conciliación, puedan utilizar payment_declared_at como señal adicional. La confirmación terminal sigue dependiendo del estado canónico reportado por POO.

Importante: en entornos donde está habilitada la capability de simulación, el mismo control puede mostrarse como Simular pago. Esa ruta de prueba es distinta y no debe confundirse con la declaración real del comprador.

8. Estados y resultados

failed no es un resultado comercial terminal del contrato público actual. Cerrar el modal tampoco equivale por sí solo a cancelar la Payment Order.

9. Webhooks

payment_order.created
payment_order.presented
payment_order.terminal

payment_order.terminal comunica pagado, cancelado o timeout. El receptor valida HMAC y timestamp, deduplica por event_id, procesa y responde 2xx rápidamente. La tolerancia anti-replay es 300 segundos.

10. Consulta de respaldo

GET /v1/payment-orders/{payment_order_uid}

SDK = experiencia inmediata. Webhook = confirmación backend. GET Payment Order = respaldo/verificación puntual.

11. Checklist

1. Obtener Bearer desde backend.
2. Crear checkout con amount, currency y external_transaction_id.
3. Enviar Idempotency-Key.
4. Guardar los identificadores devueltos.
5. Abrir checkout_url con el SDK.
6. Tratar Ya pagué como declaración no terminal; esperar la confirmación canónica de YUPY.
7. Implementar el webhook.
8. Probar pagado, cancelado y timeout.