Metodología de integración

Estado documental: Propuesto. Esta metodología debe utilizarse como guía de diseño, desarrollo, pruebas y activación.

Principio general

Una integración YUPY no comienza con el diseño visual del QR. Comienza definiendo qué operación comercial se cobrará, qué recursos receptores utilizará la empresa, cómo se identificará cada transacción y cómo se demostrará que un movimiento bancario corresponde a la venta correcta.

La experiencia visible es una parte del sistema. La identidad transaccional, la detección bancaria, la conciliación, los eventos y el cierre comercial son el núcleo.

Etapa 1: definir el alcance comercial

La ficha inicial debe indicar:

• qué operación se cobrará;
• qué sistema la origina;
• qué ambientes existirán;
• qué perfiles de cobro se utilizarán;
• qué medios estarán habilitados inicialmente;
• quién presentará las opciones al comprador;
• qué sistemas deben actualizarse;
• quién resuelve excepciones.

Operación comercial:
Sistema de origen:
Experiencia de integración:
Estrategia de presentación:
Canal:
Perfil de cobro:
Medios habilitados:
Sistemas que reciben resultados:
Responsables:
Casos de excepción:

Etapa 2: inventariar perfiles de cobro

Cada perfil debe documentar:

• empresa propietaria;
• ambiente;
• moneda;
• QR de Yape habilitados;
• QR de Plin habilitados;
• cuentas bancarias y CCI habilitados para transferencias;
• nombre receptor que puede mostrarse;
• fuente bancaria usada para conciliación;
• reglas de selección entre múltiples QR o cuentas;
• permisos y responsables.

Los QR y cuentas no deben enviarse libremente desde cada plataforma. Deben configurarse, verificarse y referenciarse mediante collection_profile_id.

Etapa 3: separar experiencia, presentación, canal y medio

La arquitectura debe distinguir:

Experiencia de integración:
direct_api | web_checkout | chat_pos | integrated_pos

Estrategia de presentación:
client_managed | yupy_checkout | yupy_chat_delivery | integrated_pos

Canal:
web | whatsapp | yupy_chat | other_chat | pos_system | mobile_app

Medio disponible actualmente:
yape_qr | plin_qr | bank_transfer

Ejemplo:

Sistema de origen: ecommerce
Experiencia de integración: direct_api
Estrategia de presentación: client_managed
Canal: web
Perfil de cobro: COLLECTION-PERU-01
Medios: yape_qr, plin_qr

Etapa 4: mapear datos

Para cada dato deben definirse origen, formato, obligatoriedad, validación, sensibilidad, retención y comportamiento cuando falta.

Etapa 5: minimizar información

Solo deben enviarse datos necesarios para identificar la operación, presentar el cobro, conciliar, atender excepciones y generar reportes autorizados.

No deben enviarse contraseñas, credenciales bancarias, secretos, tokens de terceros ni datos personales sin propósito definido.

metadata no debe convertirse en un depósito general ni reemplazar campos contractuales.

Etapa 6: diseñar identidad e idempotencia

La plataforma debe definir:

• external_transaction_id estable;
• almacenamiento de yupy_transaction_id;
• generación de Idempotency-Key;
• manejo de reintentos;
• conflictos por payload diferente;
• política para identificadores externos duplicados.

Misma clave + mismo payload
→ devolver la misma operación o un resultado equivalente

Misma clave + payload diferente
→ rechazar por conflicto

Etapa 7: diseñar la presentación

Cuando la estrategia sea client_managed, la plataforma de la empresa debe definir:

• qué opciones elegibles mostrará;
• cómo mostrará el monto;
• cómo mostrará el QR sin modificarlo;
• cómo presentará el número de cuenta o CCI;
• cómo informará vencimiento y espera;
• cómo conservará payment_option_id;
• cómo evitará afirmar que el pago está confirmado antes de la conciliación.

La presentación puede cambiar sin alterar la lógica financiera, siempre que conserve la identidad de la orden y de las opciones.

Etapa 8: diseñar estados separados

Estado operativo

created
active
expired
cancelled
closed

Estado financiero

awaiting_payment
payment_reported
movement_detected
reconciliation_pending
reconciled
amount_difference
ambiguous
not_found
late_detected

Estado de entrega

not_applicable
pending
sent
delivered
opened
failed

No debe utilizarse una única columna genérica para representar simultáneamente la vida de la orden, la realidad financiera y la entrega por canal.

Etapa 9: diseñar la conciliación

La estrategia debe identificar información disponible desde:

• orden;
• perfil de cobro;
• opción presentada;
• movimiento bancario;
• comprador;
• vendedor;
• turno;
• local;
• canal;
• constancia o señal auxiliar.

Debe contemplar monto, moneda, cuenta receptora, fecha y hora, ventana temporal, movimientos ya utilizados, órdenes simultáneas, pagos tardíos, diferencias y duplicados.

Cuando no exista evidencia suficiente, YUPY no debe conciliar arbitrariamente.

Etapa 10: contrato de eventos

La plataforma debe definir endpoint receptor, autenticación, firma, deduplicación, reintentos, persistencia y recuperación.

Cada evento debe incluir:

• event_id;
• tipo;
• fecha;
• yupy_transaction_id;
• external_transaction_id;
• payment_option_id cuando se conozca;
• estado nuevo;
• datos financieros relevantes.

Etapa 11: ambientes

Sandbox y producción deben separar credenciales, perfiles de cobro, QR, cuentas, URLs, firmas, webhooks, registros y reportes.

No deben utilizarse cuentas reales en pruebas salvo un piloto autorizado y controlado.

Etapa 12: matriz de pruebas

Cada prueba debe conservar entrada, salida, estado anterior, estado posterior, eventos, códigos, logs y evidencia.

Etapa 13: piloto controlado

El piloto debe limitar operaciones, perfiles, cuentas, locales, vendedores, horarios y montos cuando corresponda.

Debe existir un responsable capaz de revisar pendientes, resolver ambigüedades, detener el flujo, comparar contra el banco y documentar diferencias.

Etapa 14: activación

La activación necesita contratos aprobados, credenciales de producción, perfiles autorizados, webhooks configurados, alertas, responsables, rollback, monitoreo y soporte.

No debe activarse una integración solo porque la plataforma logra mostrar un QR. También deben funcionar correlación, conciliación, eventos, reintentos, auditoría y cierre comercial.

Etapa 15: operación y mejora

Después de activar se deben revisar tasa de conciliación automática, operaciones ambiguas, pagos tardíos, diferencias, movimientos no identificados, eventos fallidos, tiempos de confirmación y trabajo manual restante.

En el futuro YUPY podrá incorporar otros medios de pago, entre ellos tarjetas, otras billeteras, Google Pay, Apple Pay o criptoactivos. Cada incorporación deberá añadir un tipo de opción versionado, controles propios, pruebas y validación legal y operativa. La arquitectura flexible no implica disponibilidad inmediata.

Control de cambios

Toda modificación contractual debe indicar versión, fecha, alcance, compatibilidad, campos añadidos, campos deprecados, migración y pruebas.

No se debe cambiar silenciosamente el significado de un estado, el formato de un campo, la idempotencia, un webhook, una opción de pago o una regla de conciliación.

Criterios de aceptación

1. Alcance documentado.
2. Perfil de cobro documentado.
3. Mapeo de datos aprobado.
4. Experiencia y presentación definidas.
5. Identificadores e idempotencia definidos.
6. Estados separados.
7. Estrategia de conciliación definida.
8. Contrato de eventos definido.
9. Matriz de pruebas ejecutable.
10. Piloto y activación planificados.
11. Responsables operativos identificados.
12. Rollback documentado.
13. Decisiones futuras separadas de capacidades actuales.