Inicio rápido de integración

Estado documental: Propuesto. Este contrato está redactado para orientar el desarrollo y deberá confirmarse antes de considerarse definitivo.

Alcance disponible actualmente: Yape mediante QR, Plin mediante QR y, cuando la empresa lo habilite, transferencia bancaria mediante número de cuenta o CCI. La plataforma de la empresa integradora decide cómo presentar estas opciones a su comprador.

Objetivo

Este inicio rápido explica cómo una plataforma comercial crea una orden de cobro en YUPY, recibe una o más opciones de pago, las muestra en su propia experiencia y espera el resultado de la detección y conciliación bancaria.

La plataforma de origen puede ser un ecommerce, un sistema de reservas, un CRM, un ERP, un POS, una aplicación interna o una solución conversacional.

Principio financiero: el dinero llega directamente a las cuentas o billeteras de la empresa. YUPY coordina la orden, entrega la información necesaria y concilia el movimiento, pero no necesita recibir ni custodiar los fondos.

Modelo mínimo

Plataforma de la empresa
    → crea una orden de cobro
YUPY
    → resuelve el perfil de cobro
    → devuelve QR de Yape, QR de Plin y/o datos bancarios
Plataforma de la empresa
    → decide cómo presentarlos a su comprador
Comprador
    → realiza el pago
Banco o billetera receptora
    → registra el movimiento
YUPY
    → detecta y concilia
Plataforma de la empresa
    → actualiza la venta o proceso comercial

Cuatro conceptos que no deben mezclarse

1. Perfil de cobro

El perfil de cobro identifica las cuentas y recursos receptores configurados para una empresa.

Campo propuesto: collection_profile_id.

Un perfil puede contener:

uno o varios QR de Yape;
uno o varios QR de Plin;
una o varias cuentas bancarias para transferencias;
moneda y banco correspondiente;
reglas de selección y conciliación;
fuentes bancarias autorizadas para detectar movimientos.

La plataforma no debe enviar el número de cuenta ni la imagen QR en cada orden. Debe referenciar un perfil previamente configurado y YUPY resolverá las opciones habilitadas.

2. Experiencia de integración

Describe cómo se conecta el sistema comercial con YUPY.

Valores propuestos:

direct_api
web_checkout
chat_pos
integrated_pos

3. Estrategia de presentación

Describe quién muestra o entrega las opciones al comprador.

Valores propuestos:

client_managed
yupy_checkout
yupy_chat_delivery
integrated_pos

En client_managed, YUPY devuelve las opciones y la plataforma de la empresa decide cómo presentarlas. Puede mostrarlas en una web, aplicación, POS, tablet, tótem, conversación u otra interfaz propia.

4. Canal

Indica por dónde se entrega la experiencia cuando corresponde.

Ejemplos:

web
whatsapp
yupy_chat
other_chat
pos_system
mobile_app

WhatsApp es un canal. No es el nombre de la experiencia de integración.

Antes de comenzar

La empresa debe disponer de:

una organización configurada en YUPY;
al menos un perfil de cobro;
QR de Yape y/o Plin autorizados;
datos de cuenta bancaria cuando se habiliten transferencias;
credenciales separadas por ambiente;
un identificador estable para sus operaciones;
un endpoint o mecanismo para recibir cambios de estado;
casos de prueba aprobados.

Paso 1: seleccionar el perfil de cobro

La orden debe indicar el perfil que YUPY utilizará para resolver los medios disponibles.

"collection_profile_id": "COLLECTION-PERU-01"

Si la empresa tiene un único perfil, YUPY puede aplicar uno predeterminado. Esa decisión debe quedar configurada y no inferirse silenciosamente.

Paso 2: conservar la identidad transaccional

Identificador externo

Campo propuesto: external_transaction_id.

Debe ser único, estable y no reutilizable dentro del sistema de origen.

ORDER-10482
RESERVATION-88371
POS-LIMA-20260719-000184

Identificador YUPY

Campo propuesto: yupy_transaction_id.

YUPY lo genera cuando acepta la orden. La plataforma debe conservar la relación:

external_transaction_id
        ↔
yupy_transaction_id

Paso 3: crear la orden

La forma propuesta del endpoint es:

POST <YUPY_API_BASE_URL>/v1/payment-orders
Authorization: Bearer <credential>
Idempotency-Key: <unique-key>
Content-Type: application/json

Ejemplo propuesto para una plataforma que presentará por su cuenta las opciones:

{
  "external_transaction_id": "ORDER-10482",
  "created_at": "2026-07-19T14:30:00-05:00",
  "amount": "85.50",
  "currency": "PEN",
  "integration_experience": "direct_api",
  "presentation_strategy": "client_managed",
  "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",
    "phone": "+51999999999",
    "email": "maria@example.com"
  },
  "context": {
    "location_id": "STORE-01",
    "seller_id": "SELLER-08",
    "shift_id": "SHIFT-20260719-PM",
    "terminal_id": "POS-03",
    "destination_id": null,
    "conversation_id": null,
    "channel": "web",
    "custom_reference_1": "ROUTE-184",
    "custom_reference_2": "COUNTER-03"
  },
  "metadata": {
    "order_type": "sale"
  }
}

requested_payment_methods es opcional. Permite que la plataforma limite la respuesta a un subconjunto de las opciones habilitadas en el perfil. YUPY debe rechazar una opción no disponible o no autorizada.

Paso 4: recibir las opciones de pago

Ejemplo propuesto:

{
  "yupy_transaction_id": "ypt_01JXYZ...",
  "external_transaction_id": "ORDER-10482",
  "collection_profile_id": "COLLECTION-PERU-01",
  "created_at": "2026-07-19T14:30:02-05:00",
  "expires_at": "2026-07-19T14:45:02-05:00",
  "amount": "85.50",
  "currency": "PEN",
  "presentation_strategy": "client_managed",
  "payment_options": [
    {
      "payment_option_id": "OPTION-YAPE-01",
      "type": "yape_qr",
      "label": "Pagar con Yape",
      "qr_image_url": "<TEMPORARY_QR_IMAGE_URL>",
      "recipient_display_name": "<RECIPIENT_NAME>",
      "instructions": "Escanea el QR e ingresa el monto exacto."
    },
    {
      "payment_option_id": "OPTION-PLIN-01",
      "type": "plin_qr",
      "label": "Pagar con Plin",
      "qr_image_url": "<TEMPORARY_QR_IMAGE_URL>",
      "recipient_display_name": "<RECIPIENT_NAME>",
      "instructions": "Escanea el QR e ingresa el monto exacto."
    },
    {
      "payment_option_id": "OPTION-BANK-01",
      "type": "bank_transfer",
      "label": "Transferencia bancaria",
      "bank_name": "<BANK_NAME>",
      "account_type": "<ACCOUNT_TYPE>",
      "account_number_display": "<ACCOUNT_NUMBER>",
      "cci_display": "<CCI>",
      "recipient_display_name": "<RECIPIENT_NAME>"
    }
  ],
  "state": {
    "operational": "active",
    "financial": "awaiting_payment",
    "delivery": "not_applicable"
  }
}

Reglas actuales

Los tipos disponibles inicialmente son yape_qr, plin_qr y, cuando esté habilitado, bank_transfer.
Una respuesta puede incluir un QR, varios QR o una combinación de QR y cuenta bancaria.
La plataforma de la empresa decide qué opciones elegibles mostrar, en qué orden y con qué diseño.
La plataforma no debe modificar la imagen QR, el número de cuenta, el CCI, el nombre receptor ni el identificador de opción.
Los QR actuales pueden ser QR fijos y no necesariamente codifican el monto. La plataforma debe mostrar el monto de la orden de forma visible y separada.
expires_at representa la ventana operativa de la orden, no la vigencia intrínseca de un QR fijo.
Un pago realizado después del vencimiento puede detectarse posteriormente como pago tardío.

Paso 5: presentar las opciones

En la estrategia client_managed, la plataforma de la empresa puede:

mostrar todos los medios disponibles;
mostrar uno solo según sus reglas;
enviar una imagen QR en un chat;
presentar los datos bancarios en una pantalla propia;
integrar el resultado dentro de un POS;
abrir su propio flujo web o móvil.

El comprador no decide cómo se construye la experiencia. La empresa integradora controla la presentación y el comprador selecciona entre las opciones que se le ofrecen.

Paso 6: esperar la confirmación financiera

Existen señales diferentes:

El comprador informó que pagó

payment_reported

Es una señal auxiliar. No confirma dinero.

YUPY detectó un movimiento candidato

movement_detected

Todavía debe validarse que el movimiento corresponde a la orden correcta.

YUPY concilió el movimiento

reconciled

Este estado confirma que YUPY relacionó el movimiento bancario con la orden.

“Ya pagué”           ≠ pago confirmado
Captura               ≠ pago confirmado
Movimiento detectado  ≠ necesariamente conciliado
Movimiento conciliado = pago confirmado por YUPY

Paso 7: recibir cambios de estado

La plataforma debe admitir webhooks y procesamiento idempotente.

{
  "event_id": "evt_01JXYZ...",
  "event_type": "payment.reconciled",
  "occurred_at": "2026-07-19T14:34:20-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ...",
    "external_transaction_id": "ORDER-10482",
    "payment_option_id": "OPTION-YAPE-01",
    "amount": "85.50",
    "currency": "PEN",
    "state": {
      "operational": "closed",
      "financial": "reconciled",
      "delivery": "not_applicable"
    }
  }
}

El receptor debe tolerar eventos repetidos y consultar el estado actual cuando exista una duda.

Extensibilidad futura

El contrato está diseñado para admitir, mediante versiones posteriores, otros medios de pago como tarjetas de débito o crédito, otras billeteras virtuales, billeteras de checkout como Google Pay o Apple Pay, y eventualmente criptoactivos o criptomonedas cuando exista una definición técnica, comercial, bancaria, legal y operativa aprobada.

Esta nota describe una dirección de producto. Ninguno de esos medios adicionales debe considerarse disponible en la versión actual ni incluirse en una orden hasta que exista un contrato versionado y una implementación verificada.

Criterios mínimos de aceptación

Crear una orden válida.
Conservar ambos identificadores.
Reintentar con la misma clave sin crear duplicados.
Resolver correctamente el perfil de cobro.
Recibir uno o varios QR habilitados.
Recibir datos bancarios solo cuando la transferencia esté habilitada.
Presentar las opciones sin modificarlas.
Registrar “Ya pagué” sin confirmar indebidamente.
Conciliar un pago exacto.
Manejar un pago tardío.
Manejar un monto diferente.
Manejar dos órdenes simultáneas por el mismo monto.
Procesar un webhook repetido sin duplicar la acción comercial.

API Technical Docs