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

Usuário → UI do OfferHub:
  “Adicionar Fundos”

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

Orquestrador do OfferHub → API da Airtm:
  Criar Compra (intenção de pay-in)

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

Usuário → Fluxo de Pagamento Hospedado da 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)

Airtm → Webhook do OfferHub:
  Compra confirmada

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)

Usuário → UI do OfferHub: Adicionar Fundos
OfferHub → API da Airtm: Criar Compra
Usuário → Airtm: Concluir Pagamento
Airtm → Webhook do OfferHub: Compra Confirmada
OfferHub → Supabase: Atualizar saldo derivado

---

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.