> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v1-pt/dapps-oss/offerhub-marketplace/fluxos-principais/financiar-conta-recarga.md). # 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](/trustless-work/v1-pt/introducao/stellar-and-soroban-the-backbone-of-trustless-work/trustlines.md). Para este exemplo estamos usando USDc na Stellar. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.trustlesswork.com/trustless-work/v1-pt/dapps-oss/offerhub-marketplace/fluxos-principais/financiar-conta-recarga.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.