Inicio rápido de integración

Estado documental: Propuesto. Este inicio rápido resume la integración pública de YUPY con Payment Order / API Engine v1.0. Los endpoints y credenciales exactos deben confirmarse para cada ambiente antes de producción.

Objetivo

Una integración mínima debe poder crear una intención de cobro, conservar las identidades correctas, presentar la instrucción al pagador, recibir eventos de conciliación y reintentar sin crear duplicados.

Integrador
    ↓
YUPY API Engine
    ↓
Adapter del origen
    ↓
Payment Order Orchestrator
    ↓
canal / presentación
    ↓
Reconciliation
    ↓
webhooks / consulta

1. Configura autenticación e idempotencia

Cada request autenticado utiliza la credencial privada asignada al cliente. Para una creación de Payment Order, envía además una Idempotency-Key única para esa operación técnica.

Authorization: Bearer <PRIVATE_CREDENTIAL>
Idempotency-Key: 8e2d7c1b-...

Idempotency-Key no es el ID comercial de la venta. El sistema origen conserva su propia identidad mediante external_transaction_id.

2. Crea un Web Checkout

POST <YUPY_API_BASE_URL>/v1/checkouts

Request mínimo:

{
  "external_transaction_id": "ORDER-10482",
  "amount": "85.50",
  "currency": "PEN",
  "payment_method": "qr"
}

Para el flujo QR productivo actual, el integrador solicita únicamente payment_method=qr. YUPY resuelve internamente el Counter virtual Web, la policy, el timeout y el instrumento QR concreto.

3. Envía contexto de negocio cuando aporte valor

Los datos específicos de la operación pueden viajar en business_context:

{
  "business_context": {
    "industry": "ground_transport",
    "destination": "Arequipa",
    "route": "Lima-Arequipa",
    "seat": "12A"
  }
}

Los datos del comprador son opcionales salvo que el medio o el contrato aplicable exijan lo contrario. Para QR se recomienda enviar nombre y apellido cuando estén disponibles.

4. No envíes infraestructura interna

El caller no debe seleccionar libremente identificadores internos de YUPY. El API Engine y el Adapter del origen resuelven el contexto necesario antes de invocar al Payment Order Orchestrator.

NO enviar como contrato público genérico:

counter_id
client_id interno
QR ID
WhatsApp Account ID
Agencia
Reconciliation Target

En Web Checkout, YUPY asigna un Counter virtual. En POS, chat u otros orígenes, el Adapter correspondiente aplica su regla de resolución.

5. Conserva las tres identidades

Identificador	Uso
`external_transaction_id`	Identidad comercial en el sistema origen.
`Idempotency-Key`	Identidad del intento técnico/retry.
`payment_order_uid`	Identidad canónica de la Payment Order generada por YUPY.

Respuesta conceptual:

{
  "payment_order_uid": "pay_01JXYZ",
  "external_transaction_id": "ORDER-10482",
  "status": "open",
  "payment_method": "qr",
  "payment_instrument_type": "qr_bbva",
  "payment_order": {
    "expires_at": "2026-08-09T20:20:00-05:00"
  }
}

6. Si el origen es Web Checkout

YUPY puede devolver además una sesión Web:

{
  "checkout_session": {
    "checkout_session_id": "ycs_01JXYZ",
    "checkout_url": "https://<YUPY_CHECKOUT_HOST>/checkout/<OPAQUE_TOKEN>",
    "expires_at": "2026-08-09T20:30:00-05:00"
  }
}

La expiración de la Payment Order y la de la sesión son distintas:

payment_order.expires_at
≠
checkout_session.expires_at

La vida de la Payment Order la determina una política de YUPY asociada al tipo/instrumento de pago. La orden conserva el snapshot de timeout_seconds, expires_at y timeout_policy_version.

7. Presenta la instrucción de pago

Crear la orden o recibir un QR/URL no significa que el pagador ya la haya visto. Cuando el canal muestra o entrega efectivamente la instrucción, se registra:

payment_instruction.presented
presented_at

Ese timestamp permite medir el tiempo real entre presentación y confirmación financiera.

8. Claims y evidencia no son confirmación financiera

El vendedor o comprador puede reportar que ya pagó y puede adjuntar una fotografía/captura. Esas acciones disparan verificación.

payment_reported / evidencia
        ↓
verificación
        ↓
Reconciliation
        ↓
payment.reconciled
        ↓
Payment Order = confirmed
confirmed_at

No marques una venta como financieramente confirmada solo porque recibiste payment.reported o evidencia visual.

9. Procesa webhooks de forma idempotente

YUPY publica eventos con identidad propia. Conserva al menos:

event_id
event_type
event_version
created_at
payment_order_uid
external_transaction_id

El consumidor debe deduplicar por event_id y tolerar entregas repetidas.

Eventos especialmente relevantes:

payment_instruction.presented
payment.reported
payment.evidence_received
payment.reconciled
payment.late_detected

10. Consulta la Payment Order

GET /v1/payment-orders/{payment_order_uid}

También puede existir consulta por referencia externa:

GET /v1/payment-orders/by-external-id/{external_transaction_id}

Utiliza payment_order_uid para operaciones sobre la entidad YUPY y external_transaction_id para correlación con tu sistema.

11. Cancela cuando corresponda

POST /v1/payment-orders/{payment_order_uid}/cancel

Los estados terminales v1 son:

confirmed
expired
cancelled
failed

Todo cierre terminal registra closed_at y libera el Counter. Un pago tardío detectado después de expiración/cancelación se registra históricamente y no reabre la orden original.

12. Maneja capacidad sin inventar infraestructura

La capacidad runtime de Web Checkout pertenece a YUPY. El integrador no selecciona un Counter alternativo ni administra pools.

Cuando no exista capacidad elegible, puede aparecer no_counter_available. Su HTTP status público final sigue por definir y no debe asumirse todavía.

Checklist mínimo

Autenticar el request.
Generar y persistir Idempotency-Key.
Enviar external_transaction_id.
Enviar monto, moneda y payment_method; YUPY resuelve instrumento, Counter, policy y timeout.
Persistir payment_order_uid de la respuesta.
Presentar la instrucción y registrar/recibir presented_at.
Procesar webhooks por event_id de forma idempotente.
No considerar claims/fotos como confirmación financiera.
Consultar la Payment Order ante timeout o pérdida de respuesta antes de crear otra.
Conservar correlación entre ID externo e ID YUPY.

Changelog

2026-08-09 — Payment Order / API Engine v1.0: se rehízo el inicio rápido alrededor de la frontera API Engine → Adapter → Payment Order Orchestrator; se retiraron del contrato activo collection_profile_id, requested_payment_methods[], payment_options[] y expires_in_seconds controlado por el caller; se reemplazó yupy_transaction_id por payment_order_uid; se incorporaron payment_method, payment_instrument_type, qr_bbva, requested_at, business_context, la asignación interna de Counter, la presentación efectiva y la distinción entre claims/evidencia y confirmación financiera.

API Technical Docs