Financiar cuenta (recarga)
Objetivo
Permitir a un usuario agregar fondos a su cuenta del mercado utilizando métodos de pago locales familiares, sin exponer stablecoins, wallets o conceptos de blockchain. Estamos usando USDC en Stellar para este ejemplo.
Actores
Usuario
Frontend de OfferHub
Orquestador de OfferHub (Backend)
Supabase (perfil de usuario y vinculación de cuenta)
API de Airtm
Rails de pago de Airtm
Precondiciones
El usuario está autenticado vía Supabase
El usuario tiene un perfil válido en OfferHub
El usuario ha vinculado una cuenta Airtm (KYC completado)
OfferHub tiene credenciales válidas de la API de Airtm
Los endpoints de webhook están registrados y verificados
Si la cuenta Airtm no está vinculada, el usuario es redirigido al flujo de incorporación de Airtm primero.
Resumen del flujo
El flujo de financiación es iniciado por el usuario, ejecutado por Airtm, y orquestado por OfferHub.
OfferHub nunca recibe ni retiene fondos de usuarios.
Flujo paso a paso
1. El usuario inicia la recarga
El usuario selecciona:
monto
moneda / método de pago (según lo soportado por Airtm)
OfferHub valida:
sesión de usuario (Supabase)
vinculación de cuenta Airtm
2. OfferHub crea la intención de pago en Airtm
La solicitud incluye:
referencia de usuario Airtm (email o ID de usuario)
monto
moneda
referencias de retorno / callback
Este paso aún no mueve fondos — crea una intención de pago.
3. El usuario completa el pago vía Airtm
Airtm se encarga de:
selección del método de pago
rails locales (transferencia bancaria, wallet, etc.)
controles de cumplimiento
ejecución de la transacción
OfferHub está no involucrado durante este paso.
4. Airtm confirma el pago (Webhook)
El webhook incluye:
ID de la purchase
referencia de usuario Airtm
monto
estado final
OfferHub debe:
verificar la firma del webhook
asegurar idempotencia
persistir el evento
5. OfferHub actualiza el saldo del marketplace
OfferHub:
registra la recarga exitosa en su libro mayor interno (estado derivado)
marca al usuario como listo para financiar
actualiza el estado de la UI
Importante: El “saldo” de OfferHub es una vista, no custodia. Airtm sigue siendo el sistema de registro de los fondos.
Post-condiciones
El usuario tiene saldo disponible para:
financiar escrows
comprar bienes o servicios
No se han transferido fondos al marketplace ni al escrow todavía
El registro de auditoría contiene:
intención de pay-in
evento de confirmación
vinculación de usuario
Resultados
✅ El saldo del usuario en el marketplace aumentó (derivado)
✅ El saldo en Airtm aumentó (fuente de la verdad)
✅ Entrada en el registro de auditoría creada
✅ El usuario es elegible para financiar escrows
Escenarios de falla y manejo
Pago fallido
Airtm envía webhook de fallo
OfferHub actualiza la UI y registra la razón
Sin cambio de saldo
Webhook no recibido
OfferHub consulta el estado de la purchase en Airtm
El trabajo de conciliación vuelve a intentar
Webhook duplicado
La clave de idempotencia previene el doble crédito
Notas de seguridad y cumplimiento
OfferHub nunca almacena:
detalles bancarios
credenciales de pago
saldos de Airtm
Todos los endpoints de webhook deben:
verificar firmas
hacer cumplir la protección contra reprodución
Todas las acciones de financiación deben registrarse
Diagrama de secuencia (simplificado)
Razonamiento del diseño
Por qué Airtm posee el saldo
entidad financiera regulada
responsabilidad de cumplimiento
evita riesgo de custodia
Por qué OfferHub rastrea un saldo derivado
mejora la experiencia de usuario
habilita verificaciones de elegibilidad instantáneas
evita llamadas constantes a la API
Nota educativa
Este flujo funcionará para cualquier activo emitido en la red Stellar, solo tienes que apuntar al Trustline. Para este ejemplo estamos usando USDc en Stellar.
Última actualización