Financiar conta (recarga)
Objetivo
Permitir que um usuário adicione fundos à sua conta do marketplace usando métodos de pagamento locais familiares, sem expor stablecoins, carteiras ou conceitos de blockchain. Estamos usando USDC na Stellar para este exemplo.
Atores
Usuário
Frontend do OfferHub
Orquestrador do OfferHub (Backend)
Supabase (perfil do usuário e vinculação de conta)
API da Airtm
Rails de Pagamento da Airtm
Pré-condições
O usuário está autenticado via Supabase
O usuário tem um perfil válido no OfferHub
O usuário vinculou uma conta Airtm (KYC concluído)
O OfferHub possui credenciais válidas da API da Airtm
Os endpoints de webhook estão registrados e verificados
Se a conta Airtm não estiver vinculada, o usuário é redirecionado para o fluxo de integração da Airtm primeiro.
Visão Geral do Fluxo
O fluxo de financiamento é iniciado pelo usuário, executado pela Airtm, e orquestrado pelo OfferHub.
O OfferHub nunca recebe ou mantém fundos dos usuários.
Fluxo Passo a Passo
1. Usuário Inicia Recarrega
O usuário seleciona:
quantia
moeda / método de pagamento (conforme suportado pela Airtm)
O OfferHub valida:
sessão do usuário (Supabase)
vinculação da conta Airtm
2. OfferHub Cria Intenção de Pay-In na Airtm
A requisição inclui:
referência do usuário Airtm (email ou ID do usuário)
quantia
moeda
referências de retorno / callback
Esta etapa ainda não movimenta fundos — ela cria uma intenção de pagamento.
3. Usuário Conclui Pagamento via Airtm
A Airtm lida com:
seleção do método de pagamento
rails locais (transferência bancária, carteira, etc.)
verificações de conformidade
execução da transação
O OfferHub está não envolvido durante esta etapa.
4. Airtm Confirma Pagamento (Webhook)
O webhook inclui:
ID da compra
referência do usuário Airtm
quantia
status final
O OfferHub deve:
verificar a assinatura do webhook
garantir idempotência
persistir o evento
5. OfferHub Atualiza Saldo do Marketplace
OfferHub:
registra a recarga bem-sucedida em seu razão interna (estado derivado)
marca o usuário como pronto para financiar
atualiza o estado da UI
Importante: O “saldo” do OfferHub é uma visão, não custódia. A Airtm permanece o sistema de registro dos fundos.
Pós-Condições
O usuário tem saldo disponível para:
escrow de financiamento
compra de bens ou serviços
Nenhum fundo foi movido para o marketplace ou escrow ainda
O log de auditoria contém:
intenção de pay-in
evento de confirmação
vinculação do usuário
Saídas
✅ Saldo do usuário no marketplace aumentou (derivado)
✅ Saldo na Airtm aumentou (fonte da verdade)
✅ Entrada no log de auditoria criada
✅ Usuário está elegível para financiar escrows
Cenários de Falha e Tratamento
Pagamento Falhou
A Airtm envia webhook de falha
O OfferHub atualiza a UI e registra o motivo
Sem alteração de saldo
Webhook Não Recebido
O OfferHub consulta o status da compra na Airtm
Job de reconciliação tenta novamente
Webhook Duplicado
Chave de idempotência previne crédito duplo
Notas de Segurança e Conformidade
O OfferHub nunca armazena:
detalhes bancários
credenciais de pagamento
saldos da Airtm
Todos os endpoints de webhook devem:
verificar assinaturas
impor proteção contra replay
Todas as ações de financiamento devem ser registradas
Diagrama de Sequência (Simplificado)
Justificativa de Design
Por que a Airtm Detém o Saldo
entidade financeira regulamentada
responsabilidade de conformidade
evita risco de custódia
Por que o OfferHub Rastreia um Saldo Derivado
melhora a UX
possibilita verificações instantâneas de elegibilidade
evita chamadas constantes à API
Nota Educacional
Este fluxo funcionará para qualquer ativo emitido na rede Stellar, você só precisa apontar para o Trustline. Para este exemplo estamos usando USDc na Stellar.
Atualizado