Órdenes de pago y Web Checkout

Estado documental: Contrato propuesto. Las rutas, campos, límites y tiempos pasan a estado confirmado solo después de su implementación y verificación.

Objetivo: Definir todos los endpoints cliente para órdenes, consultas, cancelación, sesiones y experiencia temporal de Web Checkout.

Órdenes de pago

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`POST`	`/v1/payment-orders`	Crear una orden.	Obligatoria	payment.* o checkout.*
Integración	`POST`	`/v1/payment-orders/batch`	Crear varias órdenes.	Obligatoria por lote	payment.*
Integración	`GET`	`/v1/payment-orders`	Listar y filtrar órdenes.	No	Ninguno
Integración	`GET`	`/v1/payment-orders/{id}`	Consultar por ID YUPY.	No	Ninguno
Integración	`GET`	`/v1/payment-orders/by-external-id/{external_id}`	Consultar por ID externo.	No	Ninguno
Integración	`POST`	`/v1/payment-orders/batch-lookup`	Consultar múltiples IDs.	Sí	Ninguno
Integración	`GET`	`/v1/payment-orders/{id}/history`	Consultar línea de tiempo.	No	Ninguno
Integración	`GET`	`/v1/payment-orders/{id}/events`	Consultar eventos.	No	Ninguno
Integración	`GET`	`/v1/payment-orders/{id}/reconciliation`	Consultar resultado financiero normalizado.	No	Ninguno
Integración	`GET`	`/v1/payment-orders/{id}/related-resources`	Consultar sesiones, casos y evidencias.	No	Ninguno
Integración	`POST`	`/v1/payment-orders/{id}/cancel`	Cancelar operativamente.	Obligatoria	payment.cancelled
Integración	`POST`	`/v1/payment-orders/{id}/payment-reported`	Registrar “Ya pagó” o “Ya pagué”.	Obligatoria	payment.reported
Integración	`GET`	`/v1/payment-orders/{id}/payment-instructions`	Obtener instrucciones autorizadas.	No	Ninguno
Integración	`POST`	`/v1/payment-orders/{id}/amendments`	Solicitar corrección permitida y auditada.	Obligatoria	payment.amendment_requested

Creación mínima: Web Checkout

POST /v1/payment-orders
Authorization: Bearer <ACCESS_TOKEN>
Idempotency-Key: 72984bf7-61d8-4504-b591-c37494e381ac
Content-Type: application/json

{
  "external_transaction_id": "ORDER-10482",
  "amount": "85.50",
  "buyer_name": "María Ramos",
  "integration_experience": "web_checkout"
}

{
  "result": "created",
  "yupy_transaction_id": "ypt_01JXYZ",
  "external_transaction_id": "ORDER-10482",
  "amount": "85.50",
  "currency": "PEN",
  "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"
  },
  "request_id": "req_01JXYZ"
}

Contexto opcional

{
  "context": {
    "custom_reference_1": "ROUTE-184",
    "custom_reference_2": "SEAT-12A"
  }
}

El contexto es opcional. Ruta, asiento, pedido u otras referencias mejoran trazabilidad y detección de duplicados.

Consultar estado

GET /v1/payment-orders/ypt_01JXYZ

{
  "yupy_transaction_id": "ypt_01JXYZ",
  "external_transaction_id": "ORDER-10482",
  "amount": "85.50",
  "currency": "PEN",
  "buyer_name": "María Ramos",
  "state": {
    "operational": "active",
    "financial": "reconciled"
  },
  "updated_at": "2026-07-20T14:40:00-05:00",
  "request_id": "req_01JXYZ"
}

Cancelar

POST /v1/payment-orders/ypt_01JXYZ/cancel
Idempotency-Key: e85afd30-fe75-456d-b97d-f575ba6bcb25

{
  "reason": "customer_cancelled",
  "external_reason": "El comprador canceló la compra."
}

{
  "result": "cancelled",
  "state": {
    "operational": "cancelled",
    "financial": "awaiting_payment"
  },
  "request_id": "req_01JXYZ"
}

Cancelar no elimina movimientos, no impide detectar pagos posteriores y no ejecuta devoluciones.

Idempotencia y duplicados

Situación	Respuesta
Misma clave y mismo payload	Devuelve la misma operación.
Misma clave y payload distinto	`409 idempotency_conflict`
Mismo ID externo y datos iguales	Devuelve la operación existente.
Mismo ID externo y datos críticos distintos	`409 external_transaction_conflict`
ID distinto con señales equivalentes	`409 possible_duplicate_transaction`

Sesiones de Web Checkout

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`POST`	`/v1/payment-orders/{id}/checkout-sessions`	Crear sesión temporal.	Obligatoria	checkout.created
Integración	`GET`	`/v1/payment-orders/{id}/checkout-sessions`	Listar sesiones.	No	Ninguno
Integración	`GET`	`/v1/checkout-sessions/{session_id}`	Consultar sesión.	No	Ninguno
Integración	`POST`	`/v1/checkout-sessions/{session_id}/revoke`	Revocar acceso.	Obligatoria	checkout.revoked
Integración	`GET`	`/v1/checkout-sessions/{session_id}/history`	Auditar sesión.	No	Ninguno
Checkout temporal	`GET`	`/checkout/{opaque_token}`	Abrir experiencia.	No	checkout.opened
Checkout temporal	`GET`	`/v1/public/checkout-sessions/{token}/state`	Consultar estado visual.	No	Ninguno
Checkout temporal	`POST`	`/v1/public/checkout-sessions/{token}/payment-reported`	Registrar “Ya pagué”.	Sí por sesión	payment.reported
Checkout temporal	`POST`	`/v1/public/checkout-sessions/{token}/evidence`	Enviar constancia.	Sí	payment.evidence_received
Checkout temporal	`GET`	`/v1/public/checkout-sessions/{token}/instructions`	Obtener instrucciones.	No	Ninguno

Nueva sesión después de vencimiento

Una nueva ventana se crea sobre la orden existente:

POST /v1/payment-orders/ypt_01JXYZ/checkout-sessions

{
  "expires_in_seconds": 900
}

{
  "checkout_session_id": "ycs_01JNEW",
  "checkout_url": "https://<YUPY_CHECKOUT_HOST>/checkout/<OPAQUE_TOKEN>",
  "expires_at": "2026-07-20T15:20:00-05:00",
  "request_id": "req_01JXYZ"
}

No se modifica la sesión vencida y no se crea automáticamente otra orden.

Errores principales

HTTP	Código	Descripción
422	`validation_error`	Campos obligatorios ausentes o inválidos.
409	`idempotency_conflict`	Clave reutilizada con otro contenido.
409	`external_transaction_conflict`	ID externo ya utilizado con datos distintos.
409	`possible_duplicate_transaction`	Existe una operación equivalente.
404	`payment_order_not_found`	Orden inexistente.
409	`invalid_state_transition`	La acción no corresponde al estado.
404	`checkout_session_not_found`	Sesión inexistente.
410	`checkout_session_expired`	Sesión vencida.
401	`checkout_token_invalid`	Token temporal inválido.

API Technical Docs