Selección de experiencia de integración, presentación y canal

Estado documental: Propuesto. Este documento define cómo seleccionar el perfil receptor, la experiencia de integración, la estrategia de presentación y el canal.

Cuatro decisiones separadas

Perfil de cobro

Define dónde puede recibirse el dinero.

Actualmente puede incluir:

uno o varios QR de Yape;
uno o varios QR de Plin;
una cuenta bancaria o CCI para transferencias, cuando se habilite.

Experiencia de integración

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

direct_api
web_checkout
chat_pos
integrated_pos

Estrategia de presentación

Define quién muestra o entrega las opciones.

client_managed
yupy_checkout
yupy_chat_delivery
integrated_pos

Canal

Define por dónde se presenta o envía la experiencia.

web
whatsapp
yupy_chat
other_chat
pos_system
mobile_app

La configuración actual más flexible

Experiencia: direct_api
Presentación: client_managed
Perfil: COLLECTION-PERU-01
Medios: yape_qr, plin_qr, bank_transfer opcional
Canal: elegido por la plataforma de la empresa

YUPY devuelve las opciones habilitadas y espera la detección y conciliación, independientemente de que la empresa las muestre en una web, aplicación, POS, tablet, tótem o conversación.

API directa con presentación del cliente

Debe utilizarse cuando la empresa quiere controlar completamente la interfaz.

La plataforma:

crea la orden;
recibe las opciones;
selecciona cuáles mostrar;
muestra el monto;
conserva los identificadores;
espera eventos o consulta estado;
actualiza la venta después de la conciliación.

Esta estrategia desacopla la conciliación del diseño visual.

Web Checkout administrado por YUPY

Debe utilizarse cuando la empresa prefiere abrir una experiencia web administrada por YUPY.

YUPY puede presentar monto, QR, datos bancarios, instrucciones, espera, vencimiento y resultado.

El perfil de cobro sigue definiendo las opciones receptoras.

POS vía chat

Debe utilizarse cuando la venta ocurre dentro de una conversación y YUPY participa en la entrega.

Canales posibles:

WhatsApp;
chat propio de YUPY;
otro chat compatible.

WhatsApp es un canal. La experiencia es POS vía chat.

POS integrado

Debe utilizarse cuando un sistema de punto de venta crea y cierra la venta, y necesita consumir la respuesta de YUPY.

Puede presentar el QR en su propia pantalla, imprimirlo, enviarlo por otro canal o solicitar una entrega complementaria.

Selección del perfil de cobro

La empresa puede tener perfiles distintos por:

razón social;
local;
moneda;
banco;
marca;
canal;
unidad de negocio;
ambiente.

La selección debe ser explícita mediante collection_profile_id o mediante una regla predeterminada configurada y auditable.

Múltiples QR

Un perfil puede devolver varios QR elegibles.

Cada uno debe tener:

payment_option_id;
tipo;
imagen;
nombre receptor;
instrucciones;
fuente de conciliación asociada.

La plataforma de la empresa decide si muestra uno, varios o todos. YUPY puede incorporar en el futuro estrategias automáticas de selección, pero esa optimización no forma parte del contrato actual.

Transferencia bancaria opcional

Solo debe mostrarse cuando el perfil contenga una cuenta autorizada.

La plataforma debe utilizar exactamente los valores devueltos para banco, tipo de cuenta, número, CCI y nombre receptor.

La transferencia debe conciliarse contra la cuenta correspondiente y no contra cualquier movimiento de la empresa.

Árbol de decisión

¿La empresa quiere controlar su interfaz?

Sí: direct_api + client_managed.
No: evaluar experiencia administrada por YUPY.

¿El comprador puede abrir una página administrada por YUPY?

Sí: web_checkout + yupy_checkout.
No: continuar.

¿La venta ocurre en una conversación?

Sí: chat_pos + yupy_chat_delivery.
No: continuar.

¿Existe un POS que controla la venta?

Sí: integrated_pos.
No: utilizar API directa o Web Checkout.

Ejemplos

Ecommerce con interfaz propia

Sistema de origen: ecommerce
Experiencia: direct_api
Presentación: client_managed
Canal: web
Perfil: QR Yape + QR Plin
Resultado: la tienda muestra los QR y espera conciliación

Reserva atendida por WhatsApp

Sistema de origen: sistema de reservas
Experiencia: chat_pos
Presentación: yupy_chat_delivery
Canal: whatsapp
Perfil: QR Yape + transferencia opcional

Caja física

Sistema de origen: POS
Experiencia: integrated_pos
Presentación: integrated_pos
Canal: pos_system
Perfil: QR Yape + QR Plin

Reglas financieras comunes

Mostrar un QR no confirma pago.
Entregar un mensaje no confirma pago.
“Ya pagué” no confirma pago.
Un movimiento detectado todavía puede ser ambiguo.
Solo la conciliación permite confirmar la orden.
El vencimiento operativo no elimina la posibilidad de detectar un pago tardío.
La conciliación no debe depender de quién mostró el QR.

Antipatrones

Llamar modalidad al canal.
Llamar perfil de cobro a una experiencia visual.
Enviar libremente números de cuenta o QR en cada orden.
Utilizar teléfono o monto como único identificador de venta.
Modificar la imagen QR devuelta.
Conciliar por monto sin revisar operaciones simultáneas.
Utilizar una única columna status para todo.
Presentar medios futuros como si estuvieran disponibles.

Nota de extensibilidad futura

La arquitectura está diseñada para incorporar otras billeteras virtuales, tarjetas de débito o crédito, Google Pay, Apple Pay y eventualmente criptoactivos o criptomonedas.

Cada nuevo medio deberá publicarse como un tipo de opción versionado y deberá definir proveedor, liquidación, seguridad, conciliación, reembolsos, cumplimiento y pruebas.

En la versión actual solo se consideran operativos Yape QR, Plin QR y transferencia bancaria opcional.

Criterios de aceptación

Perfil de cobro identificado.
Experiencia de integración identificada.
Estrategia de presentación identificada.
Canal separado.
Plataforma responsable de la presentación definida.
Múltiples QR tratados como opciones identificables.
Transferencia limitada a perfiles habilitados.
Conciliación independiente de la interfaz.
POS vía chat separado de POS integrado.
Capacidades actuales separadas del roadmap.

API Technical Docs