Stripe Connect em Fluxos Reais de Marketplace

Stripe Connect em um marketplace não é uma integração de checkout. É um sistema de ciclo de vida para contas conectadas, cobranças de clientes, taxas da plataforma, repasses, reembolsos e estados de conformidade que mudam de forma independente ao longo do tempo. A confiabilidade em produção vem de manter esses estados no seu banco de dados e tratar os eventos do Stripe como entradas, não como a fonte da verdade.

O que é o Stripe Connect para marketplaces?

O Stripe Connect permite que uma plataforma receba pagamentos de clientes e repasse os valores a vendedores, criadores ou prestadores de serviço. A plataforma normalmente fica com uma taxa. Seja com direct charges, destination charges ou o modelo de separate charges and transfers, a parte difícil é a mesma: o onboarding da conta pode estar incompleto, repasses podem atrasar, reembolsos podem exigir a reversão de transferências e webhooks podem chegar mais de uma vez.

Se você guarda apenas os IDs dos objetos do Stripe e reconstrói o significado de negócio pela API a cada requisição, vai perder o controle dos estados parciais. Mantenha um modelo de domínio explícito para o status da conta, o resultado dos payment intents, o status das transferências e os jobs de reconciliação.

Decisões de design que se sustentam

1. Mantenha os estados de pagamento e de repasse explícitos no seu próprio banco de dados.
2. Trate os handlers de webhook como idempotentes.
3. Separe o fluxo de cobrança do cliente do fluxo de repasse ao prestador.
4. Faça da reconciliação um processo de segundo plano de primeira classe.
5. Bloqueie o checkout para contas que não estão aptas a receber repasses.

O sucesso do ponto de vista do cliente ("cartão cobrado") não é o mesmo que o sucesso do ponto de vista do vendedor ("fundos disponíveis e transferíveis"). Modelar os dois como um único booleano é como marketplaces criam tickets de suporte.

Como o tratamento de webhooks deve funcionar?

O tratamento de webhooks deve começar pelo armazenamento durável e só depois processar. Persista cada evento com event_id, type, received_at, processed_at e status antes de qualquer efeito colateral. Deduplique por event_id. Processe com uma chave de operação determinística, como transfer:{stripe_transfer_id}:create, para que retentativas não criem transferências duplicadas.

Faça o mínimo no handler HTTP: verifique a assinatura, grave a linha do evento, enfileire um job e retorne 200 rapidamente. O trabalho pesado pertence a workers com retentativas, backoff e visibilidade de dead-letter.

O que mais ajudou em produção

• Uma tabela durável de eventos com chave no event_id do Stripe.
• Handlers seguros para retentativa, com chaves de operação determinísticas.
• Workers de fila para efeitos colaterais que não bloqueiam, como e-mails, atualizações de CRM e lançamentos contábeis.
• Monitoramento de repasses atrasados e de valores de transferência divergentes.
• Estados explícitos de "onboarding incompleto" que escondem vendedores do checkout até que os requisitos sejam cumpridos.
• Um job de reconciliação noturno que compara transferências e saldos locais com o Stripe.

Modos de falha que costumam aparecer

• Entregas duplicadas de webhook causando transições de estado duplicadas.
• Contas conectadas com onboarding parcial que ainda podem ser selecionadas no checkout.
• Lógica de reembolso que estorna o cliente, mas não reverte as transferências da plataforma.
• Assumir que charge.succeeded significa que o vendedor pode ser pago imediatamente.
• Falhas silenciosas no endpoint de webhook depois que um deploy muda o signing secret ou a URL.
• Misturar destination charges e transferências separadas sem documentar as implicações de taxas e impostos.

Um checklist prático de implementação

• Escolha um padrão de cobrança do Connect e documente o motivo.
• Guarde localmente as flags de capability das contas conectadas e atualize-as a partir dos eventos de conta.
• Condicione a listagem no marketplace e o checkout à capability, não apenas a "conta criada".
• Escreva handlers de reembolso e disputa que saibam reverter ou recuperar transferências.
• Crie alertas para atraso de fila, falhas no processamento de webhooks e repasses parados além de um limite.
• Mantenha uma visão administrativa de conta, pagamento, transferência e reconciliação para o suporte.

Como reconciliar o dinheiro do marketplace com segurança?

Reconciliar significa comparar o que o seu banco de dados acredita que aconteceu com o que o Stripe informa. Rode isso de forma agendada, e não só quando um cliente reclama. Compare payment intents, charges, transfers, refunds e payouts com as linhas locais. Sinalize as divergências com contexto suficiente para uma pessoa agir: IDs dos objetos, valores, moedas e o último status local conhecido.

Para assinaturas ou taxas recorrentes de marketplace, acompanhe também o estado da fatura separadamente do estado da transferência. Uma fatura paga ainda pode deixar um vendedor sem receber se a etapa de transferência falhou. É exatamente nessa lacuna que o volume de suporte cresce.

Quando redesenhar em vez de remendar?

Remende quando um único handler está errado ou quando a falta de uma verificação de status deixa contas incompletas chegarem ao checkout. Redesenhe quando o sucesso do pagamento, o repasse ao vendedor, reembolsos e disputas estão codificados como flags improvisadas, sem histórico de eventos. Se ninguém consegue responder "qual é a fonte da verdade do saldo deste vendedor?" sem abrir o Dashboard do Stripe, o modelo ainda precisa de uma máquina de estados de verdade.

Sistemas de pagamento em produção são, em grande parte, sobre transições de estado seguras e observabilidade clara, não só chamadas de API. Se você precisa de ajuda para projetar ou consertar fluxos de marketplace com Stripe Connect, esse é um dos sistemas que construo e conserto para clientes.