Responsabilidades de cada sistema

Una integración YUPY conecta sistemas comerciales, canales de atención, cuentas bancarias y procesos internos. Para que el resultado sea confiable, cada participante debe conservar responsabilidades claras.

Regla general: el sistema de origen controla la operación comercial; YUPY controla la orden, el seguimiento y la conciliación; el banco controla el movimiento financiero; la empresa conserva directamente los fondos.

Participantes

• Sistema o canal de origen.
• YUPY.
• Empresa o comercio.
• Banco y aplicaciones de pago.
• Pagador.
• Proveedor del canal, cuando sea externo.

Responsabilidades del sistema de origen

El sistema de origen puede ser una web, una aplicación, un POS, un CRM, un ERP, WhatsApp, el chat propio de YUPY, otro chat, una plataforma de reservas o una herramienta interna.

Crear e identificar la operación comercial

Debe generar un identificador externo único y estable.

{
  "external_transaction_id": "ORDER-10482"
}

Ese identificador no debe reutilizarse para otra venta y debe acompañar toda consulta, evento o proceso de soporte.

Enviar información correcta

Como mínimo, la propuesta inicial requiere:

{
  "external_transaction_id": "ORDER-10482",
  "created_at": "2026-07-20T14:30:00-05:00",
  "amount": "85.50",
  "currency": "PEN",
  "channel": "web_checkout",
  "buyer": {
    "first_name": "María",
    "last_name": "Ramos"
  }
}

Según el canal, también puede enviar vendedor, turno, local, POS, conversación, destino operativo o configuración de cobro.

Utilizar idempotencia

Los reintentos no deben crear múltiples órdenes para la misma operación. El sistema de origen enviará una clave de idempotencia y conservará la respuesta obtenida.

Guardar la correlación

external_transaction_id
        ↔
yupy_transaction_id

Ambos identificadores son necesarios para webhooks, consultas, soporte, reportes y auditoría.

Esperar la confirmación correcta

El sistema no debe marcar una venta como pagada solo porque:

• se mostró el QR;
• se envió un mensaje;
• se abrió el checkout;
• el usuario presionó Ya pagué;
• se recibió una captura;
• se detectó un movimiento todavía ambiguo.

La confirmación comercial debe basarse en el estado de conciliación notificado por YUPY.

Implementar webhooks de forma segura

El sistema de origen debe:

• exponer una URL HTTPS;
• validar la firma;
• responder rápidamente;
• procesar eventos de forma idempotente;
• tolerar reintentos;
• no asumir un orden perfecto de llegada;
• consultar el estado cuando exista una duda.

Responsabilidades de YUPY

Validar la solicitud

YUPY debe comprobar autenticación, campos obligatorios, formatos, monto, moneda, canal, configuración, duplicidad e idempotencia.

Crear y mantener la orden

Debe asignar una identidad YUPY y conservar la relación completa con la operación externa.

Normalizar modalidades y canales

YUPY debe aceptar operaciones iniciadas mediante POS vía chat, Web Checkout, una pasarela, un POS integrado u otros sistemas internos sin perder el contrato común de la orden.

Dentro del POS vía chat, WhatsApp, el chat propio de YUPY y otros chats son canales posibles. No deben tratarse como productos o lógicas de POS diferentes.

Entregar la experiencia de pago

Según la modalidad, YUPY puede:

• operar un POS vía chat sobre WhatsApp;
• operar el mismo POS vía chat desde el chat propio de YUPY;
• integrarse con otros canales conversacionales;
• devolver una URL de Web Checkout;
• presentarse como medio de pago dentro de una web;
• responder a una orden creada desde un POS existente.

Registrar señales y evidencias

Debe conservar eventos, mensajes relevantes, reportes de pago y datos extraídos de constancias cuando estén disponibles. Estas evidencias son auxiliares y no reemplazan la conciliación bancaria.

Obtener información bancaria

YUPY debe utilizar BankBridge u otro conector autorizado para obtener los movimientos necesarios, respetando las credenciales y permisos de cada cuenta.

Conciliar con cautela

YUPY debe:

• buscar coincidencias suficientemente claras;
• evitar utilizar un movimiento en dos órdenes;
• detectar montos distintos;
• identificar ambigüedades;
• registrar pagos tardíos;
• priorizar operaciones reportadas por el usuario;
• no asignar arbitrariamente movimientos;
• conservar evidencia de cada decisión.

Notificar y automatizar

Cuando cambia el estado, YUPY debe informar al sistema de origen y permitir que continúe el proceso comercial.

Generar información útil

YUPY debe estructurar la información para reducir trabajo en:

• ventas;
• administración;
• operaciones;
• finanzas;
• contabilidad;
• atención al cliente.

Proteger datos y credenciales

YUPY no debe exponer secretos, tokens internos, firmas, credenciales bancarias ni información que no sea necesaria para la integración.

Responsabilidades de la empresa

La empresa es receptora directa del dinero y responsable de sus cuentas, reglas y operación.

Debe:

• ser titular o usuario autorizado de las cuentas receptoras;
• mantener activos sus QR y cuentas;
• autorizar los conectores bancarios correspondientes;
• informar cambios de cuenta, QR o configuración;
• mantener actualizados locales, vendedores, turnos, POS y destinos;
• definir responsables para revisión manual;
• resolver casos ambiguos cuando la evidencia no sea suficiente;
• definir políticas de tolerancia, diferencias y pagos tardíos;
• aprobar y ejecutar devoluciones;
• proteger sus accesos;
• revisar alertas y reportes.

Responsabilidades del banco y las aplicaciones de pago

El banco, Yape o Plin son responsables de:

• ejecutar el movimiento;
• reflejarlo en la cuenta receptora;
• proporcionar la información disponible;
• aplicar sus límites, reglas y tiempos;
• mantener sus propios mecanismos de seguridad.

YUPY no controla indisponibilidades bancarias, retrasos de actualización, límites de aplicaciones, reversos externos ni cambios en las interfaces del banco.

Responsabilidades del pagador

El pagador debe:

• verificar el receptor;
• utilizar el QR, cuenta o instrucciones mostradas;
• pagar el monto indicado;
• evitar pagos repetidos;
• informar cuando haya pagado, cuando el canal lo permita;
• conservar la constancia cuando sea necesaria.

Su declaración ayuda a localizar la operación, pero no sustituye el movimiento bancario conciliado.

Responsabilidades del proveedor del canal

Cuando WhatsApp, otro chat, una plataforma web o un POS pertenecen a un tercero, ese proveedor es responsable de la disponibilidad y entrega de su canal.

YUPY debe registrar fallos de entrega y reintentar cuando corresponda, pero no controla la infraestructura externa.

Flujo económico y custodia

El sistema de origen crea la operación.
YUPY coordina la experiencia y concilia.
El banco procesa el movimiento.
La empresa recibe y conserva directamente el dinero.

YUPY no necesita:

• recibir el pago en una cuenta propia;
• custodiar los fondos;
• consolidarlos antes de entregarlos;
• liquidarlos posteriormente al comercio.

El modelo comercial y las tarifas se documentarán por separado, pero la arquitectura busca ofrecer un costo total significativamente menor que alternativas con comisiones elevadas, custodia de fondos o conciliación manual.

Matriz de responsabilidades

Separación de cierres

Una operación puede tener varios cierres distintos:

Conversación cerrada
        ≠
Experiencia de pago cerrada
        ≠
Venta comercial cerrada
        ≠
Pago bancario conciliado

Los sistemas deben conservar esta separación para gestionar vencimientos, pagos tardíos, cancelaciones y revisiones sin perder la realidad financiera.

Regla final

El sistema de origen decide qué ocurre con la venta. YUPY determina y comunica el estado del cobro. La empresa recibe directamente el dinero. El banco conserva la evidencia financiera.