DEV Community: CESAR EDUARDO STURMER

Destination charges na prática: split, estorno e a matemática das taxas

CESAR EDUARDO STURMER — Thu, 01 Oct 2026 00:00:00 +0000

O artigo anterior foi sobre a decisão: por que deleguei a infraestrutura financeira à Stripe em vez de construir o split na mão. Este é sobre como isso funciona por dentro — incluindo uma conta que quase todo mundo erra na primeira tentativa.

Onde a cobrança acontece

O Stripe Connect tem dois padrões principais de split. A diferença entre eles é onde a cobrança nasce.

Com separate charges and transfers , você cobra na conta da plataforma e depois cria um Transfer separado para o vendedor. São duas operações, em dois momentos, que você orquestra.

Com destination charges , a cobrança já nasce sabendo para onde parte dela vai:

const paymentIntent = await stripe.paymentIntents.create({
  amount: calculation.amountInCents,
  currency: "brl",
  payment_method_types: [billingType === "card" ? "card" : billingType],
  application_fee_amount: calculation.applicationFeeAmount,
  transfer_data: {
    destination: stripeAccountId,
  },
  description,
  metadata: { serviceId, providerId /* ... */ },
});

Uma operação. A Stripe cobra do aluno, retém application_fee_amount para a plataforma e transfere o líquido para a conta Connect do provider assim que a cobrança é capturada.

Três consequências que importam:

O aluno vê uma cobrança só , no nome da plataforma. Um lançamento no extrato, não dois.
O provider recebe automaticamente , sem nenhuma rotina de repasse minha.
Eu nunca fico com o dinheiro dele em custódia.

O detalhe que me fez escolher: estorno

Essa é a parte pouco comentada, e foi decisiva.

Quando você estorna uma cobrança feita com destination charge, a application_fee correspondente é revertida automaticamente , na proporção do estorno. A Stripe ajusta os dois lados numa operação só.

Parece um detalhe contábil, mas olhe o que ele elimina. O surfaai tem cancelamento com direito de arrependimento: dentro de sete dias, o aluno recebe estorno real, proporcional aos créditos que não usou. Com split manual, eu teria que escrever a lógica de "devolver minha taxa também", lidar com o caso de o provider já ter sacado o valor, e reconciliar tudo isso.

Com destination charges, o estorno proporcional é uma chamada:

await stripe.refunds.create({
  payment_intent: payment.stripe_payment_intent_id,
  amount: toCents(valorProporcional),
});

E a taxa volta sozinha, na proporção certa. Zero código meu para a parte financeira do cancelamento.

As taxas não vêm da API

Para mostrar ao aluno quanto custa cada meio de pagamento no checkout, eu preciso saber a taxa antes de criar a cobrança. A tentação é consultar a Stripe. Eu não consulto.

As taxas vivem numa tabela do banco, carregadas por loadStripeFees(), com um fallback hardcoded no código:

export const STRIPE_BR_FEES: StripeFeesConfig = {
  card: {
    domestic: { percentageFee: 3.99, fixedFee: 0.39 },
    international: { percentageFee: 5.99, fixedFee: 0.39 },
    installmentExtraPercentPerMonth: 0,
  },
  pix: { percentageFee: 1.19, fixedFee: 0, capAmount: 999.0 },
  boleto: { percentageFee: 0, fixedFee: 3.45 },
};

Duas decisões empilhadas aqui.

Por que não a API: o checkout precisa ser instantâneo. Uma chamada externa só para exibir um número coloca latência e um ponto de falha num lugar onde o usuário está decidindo se compra. Taxas de gateway mudam em escala de meses, não de segundos.

Por que no banco, e não só no código: quando a Stripe reajusta uma taxa, eu quero corrigir pelo painel administrativo, não abrir um pull request e esperar deploy. O valor hardcoded é a rede de segurança para quando o banco não responde.

A conta que quase todo mundo erra

Aqui está a parte interessante. O surfaai permite configurar quem paga a taxa do gateway: a plataforma, o provider ou o aluno. Quando a taxa é repassada ao aluno, aparece um problema circular.

A intuição diz: calcule a taxa sobre o preço e some.

Com um serviço de R$ 100 e cartão a 3,99% + R$ 0,39:

taxa = 100 × 0,0399 + 0,39 = R$ 4,38
total cobrado = R$ 104,38

Está errado. A Stripe não cobra a taxa sobre os R$ 100 — ela cobra sobre o valor da transação, que agora é R$ 104,38:

taxa real = 104,38 × 0,0399 + 0,39 = R$ 4,56

Faltam R$ 0,18. Pouco numa venda, relevante em milhares delas, e sempre saindo do seu bolso.

O valor correto exige resolver a circularidade. Chamando o preço de base, a taxa percentual de p e a fixa de f:

total = base + taxa
taxa = total × p + f

Substituindo e isolando:

total = base + (total × p + f)
total − total × p = base + f
total = (base + f) / (1 − p)

E a taxa, que é o que eu preciso somar:

taxa = (base × p + f) / (1 − p)

Que é exatamente o que está no código:

export function calculateStripeFeeGrossUp(/* ... */): number {
  const { percentageFee, fixedFee } = getStripeFee(
    billingType, installments, isInternational, fees,
  );
  const pct = percentageFee / 100;

  // PIX tem cap — verificar se o gross-up também atingiria o cap
  if (billingType === "pix") {
    const fee = round2((pct * baseAmount + fixedFee) / (1 - pct));
    return fee > fees.pix.capAmount ? fees.pix.capAmount : fee;
  }
  // ...
}

Conferindo com os números de antes:

taxa = (100 × 0,0399 + 0,39) / (1 − 0,0399)
     = 4,38 / 0,9601
     = R$ 4,56

total = R$ 104,56
verificação: 104,56 × 0,0399 + 0,39 = R$ 4,56 ✓

Fecha. Esse padrão tem nome — gross-up — e aparece em qualquer lugar onde um valor percentual é calculado sobre um total que o inclui: imposto retido, comissão sobre comissão, taxa repassada.

Repare também no tratamento do cap do PIX. Um método com teto de taxa precisa verificar o limite depois do gross-up, não antes: a fórmula pode empurrar o valor acima do teto, e aí o teto é que vale.

O que eu levei disso

Destination charges substituiu, com duas propriedades de um objeto, o que seria um módulo inteiro de custódia e reconciliação. O estorno automático da taxa sozinho já pagaria a escolha.

Mas a lição que ficou é outra: delegar a infraestrutura não te isenta de entender a mecânica. O gross-up não é problema da Stripe, é meu. Se eu tivesse tratado o split como caixa-preta, estaria perdendo centavos em cada transação — e centavos em volume são a diferença entre margem e prejuízo.

No próximo artigo, um bug de verdade: como um aluno apertando F5 duas vezes gerou crédito dobrado, e o que isso me ensinou sobre onde o dinheiro pode ser criado.

Postmortem: o crédito duplicado que um F5 criava

CESAR EDUARDO STURMER — Thu, 01 Oct 2026 00:00:00 +0000

Este é um relato de incidente real do surfaai. O artigo seguinte da série generaliza o padrão; aqui eu conto o que aconteceu comigo, incluindo a parte em que meu diagnóstico inicial estava errado.

O sintoma

Um aluno comprou um pacote de créditos e ficou com o dobro do que pagou. Um pagamento, dois registros em user_credits, cada um com a quantidade cheia.

Não era erro de arredondamento nem bug de contagem. Eram duas linhas no banco, criadas com segundos de diferença, idênticas exceto pelo id.

Como estava construído

No desenho original, o fluxo de compra era assim:

o front cria o PaymentIntent
o aluno paga
a Stripe devolve a confirmação ao front
o front chama a rota que cria o crédito

O passo 4 é o problema, e levei um tempo para enxergar — porque o código do passo 4 estava correto. Ele validava o pagamento, checava o valor, criava o registro certo. Revisei várias vezes procurando o erro na lógica.

O erro não estava na lógica. Estava no fato de o passo 4 existir onde existia.

O que realmente acontecia

A página de confirmação disparava a criação do crédito ao montar. Se ela montasse duas vezes, o crédito era criado duas vezes.

E ela montava duas vezes com uma facilidade constrangedora:

o aluno aperta F5 na tela de confirmação
a conexão oscila, o navegador reenvia a requisição
o React remonta o componente

Nenhum desses casos é exótico. O primeiro é o que qualquer pessoa faz quando a tela demora.

Minha primeira hipótese foi condição de corrida entre duas requisições simultâneas, e cheguei a pensar em resolver com um lock. Estava olhando para o lugar errado: não era concorrência, era repetição. O cliente podia chamar a operação quantas vezes quisesse, e nada no sistema dizia que ela só podia valer uma vez.

Por que o cliente nunca deveria ter esse poder

Tem um ponto mais profundo aqui, e ele só ficou claro quando fui integrar PIX e boleto.

Cartão tem um momento em que o front "sabe" que deu certo. PIX e boleto não têm. O aluno fecha a aba, paga pelo app do banco quarenta minutos depois, e nunca mais volta ao site. Não existe nenhum instante no navegador em que esse pagamento confirma.

Ou seja: mesmo que o fluxo client-side funcionasse perfeitamente para cartão, ele era estruturalmente incapaz de atender metade dos meios de pagamento. O bug do F5 foi o sintoma que apareceu primeiro, mas a arquitetura já estava errada antes dele.

A correção

Crédito passou a nascer exclusivamente do evento payment_intent.succeeded do webhook da Stripe. O front não cria mais nada — ele só consulta o estado.

Isso muda a natureza do problema. A origem passa a ser única e confiável: a Stripe assina cada evento, e cada evento tem um id estável. Cartão, PIX e boleto convergem para o mesmo caminho, porque todos geram o mesmo evento.

Mas trocar o cliente pelo webhook não resolve a duplicação sozinho — e esse foi o segundo aprendizado. Webhooks são entregues com garantia at-least-once: a Stripe reenvia o evento se não receber 2xx rápido o bastante. Eu troquei "o usuário pode chamar duas vezes" por "a Stripe pode chamar duas vezes".

A diferença é que agora eu tinha com o que trabalhar: um identificador único por evento.

A primeira barreira ficou na entrada do handler:

const { data: existingEvent } = await db
  .from('stripe_webhook_events')
  .select('id, processed')
  .eq('stripe_event_id', event.id)
  .maybeSingle();

if (existingEvent?.processed) {
  return NextResponse.json({ success: true, message: 'Already processed' });
}

E a última, no banco, como rede de segurança — uma constraint de unicidade que falha se o crédito já existir:

if (creditError) {
  // 23505 = unique_violation: crédito já criado por webhook concorrente — OK
  if ((creditError as any).code === '23505') return;
  throw creditError;
}

Esse return silencioso no 23505 é deliberado. Se dois webhooks passarem pela primeira barreira ao mesmo tempo — e passam, porque entre o select e o insert existe uma janela —, o banco é o único árbitro confiável. O segundo apanha a violação e desiste sem erro, porque o resultado desejado já aconteceu.

Entre essas duas há uma terceira camada. O artigo seguinte destrincha as três, por que cada uma pega um caso diferente, e por que remover qualquer uma reabre o buraco.

O que eu faria diferente

Teria começado pelo webhook. Não por prever o bug, mas porque PIX e boleto já estavam no roadmap desde o início. Se eu tivesse desenhado para o meio de pagamento mais restritivo em vez do mais conveniente, o fluxo client-side nunca teria existido.

Teria colocado a constraint antes do código. A unicidade no banco não foi a primeira coisa que fiz — foi a última. Devia ter sido a primeira. Constraint de banco é a única garantia que não depende de eu ter pensado em todos os caminhos do código.

Teria desconfiado antes do "o código está certo". Passei tempo demais relendo uma função correta. A pergunta útil não era "esse código está certo?", era "o que acontece se isso rodar duas vezes?". Para qualquer operação que mexe com dinheiro, essa deveria ser a primeira pergunta, não a última.

A regra

Toda operação que cria, move ou destrói dinheiro precisa de uma origem única e de um identificador que permita reconhecê-la se ela voltar. O cliente nunca pode ser essa origem — não porque o código dele seja ruim, mas porque você não controla quantas vezes ele roda.

Por que Stripe Connect Express em vez de split manual

CESAR EDUARDO STURMER — Thu, 01 Oct 2026 00:00:00 +0000

Quando você monta o pagamento de um marketplace, a primeira ideia que aparece é quase sempre a mesma: cobrar o valor cheio do comprador, guardar o dinheiro na conta da plataforma e, depois, transferir a parte do vendedor.

Chamo isso de split manual. Parece simples porque você já sabe fazer as duas pontas: receber um pagamento e mandar uma transferência. O que não é óbvio é tudo que mora no meio.

Este artigo é sobre por que não fiz isso no surfaai — e o que eu teria assumido se tivesse feito.

O que "split manual" realmente exige

No momento em que o dinheiro do provider passa pela sua conta, você deixa de ser uma plataforma de software. Você vira, na prática, um intermediário financeiro. Isso traz uma lista de responsabilidades que não aparecem no diagrama de arquitetura:

Custódia. O dinheiro do provider está na sua conta, misturado com o seu. Se a empresa tiver qualquer problema de fluxo de caixa, o dinheiro de terceiros está exposto. Separar isso corretamente é um problema contábil e jurídico, não técnico.

KYC e KYB. Para repassar dinheiro a alguém, você precisa saber quem é essa pessoa. Documento, validação, verificação de titularidade da conta bancária, checagem de listas restritivas. E isso não é "uma vez": precisa ser monitorado e reverificado.

Reconciliação. Para cada pagamento, você precisa saber quanto entrou, quanto é seu, quanto é do provider, quanto já foi repassado e quanto falta. Com estorno parcial, chargeback e parcelamento no meio, essa conta fica difícil rápido.

Timing. Transfere quando? Na confirmação do pagamento? Depois do serviço prestado? Em D+30? Cada resposta é uma regra de negócio que vira código, e cada regra tem um caso de borda que você vai descobrir em produção.

Falha e retentativa. A transferência falhou porque a conta do provider estava errada. E agora? Quem detecta, quem notifica, quem reprocessa, e como você garante que a retentativa não transfere duas vezes.

Nenhum desses problemas é sobre o seu produto. Todos consomem tempo de engenharia que não vai para o produto.

As três portas do Connect

O Stripe Connect resolve isso, mas oferece três tipos de conta, e a escolha importa:

	Standard	Express	Custom
Quem faz o onboarding	o próprio provider, na Stripe	Stripe, dentro do seu fluxo	você, via API
Dashboard do provider	completo, da Stripe	reduzido, da Stripe	nenhum, você constrói
Responsabilidade por KYC	Stripe	Stripe	sua
Esforço de implementação	baixo	baixo	alto
Controle da experiência	baixo	médio	total

Standard exige que o provider tenha ou crie uma conta Stripe completa. Para um instrutor que quer só receber pelas aulas, é fricção demais — ele abandona no meio.

Custom devolve para você exatamente o que eu queria evitar: a responsabilidade de KYC e a construção de toda a interface de onboarding, extrato e saque.

Express fica no meio: o provider passa por um fluxo de onboarding hospedado pela Stripe, curto e em português, e ganha um painel simples para ver os recebimentos. Eu não vejo nem armazeno documento nenhum. A Stripe assume o KYC.

Para um produto tocado por uma pessoa, essa divisão é a diferença entre o projeto existir e não existir.

O que o código vira

Com Express e destination charges, o repasse inteiro cabe em duas propriedades do PaymentIntent:

const paymentIntent = await stripe.paymentIntents.create({
  amount: calculation.amountInCents,
  currency: "brl",
  application_fee_amount: calculation.applicationFeeAmount,
  transfer_data: {
    destination: stripeAccountId,
  },
  description,
  metadata: { serviceId, providerId /* ... */ },
});

application_fee_amount é o que fica comigo. transfer_data.destination é a conta do provider. A Stripe cobra do aluno, retém minha taxa e credita o líquido ao provider — sem nenhuma rotina de repasse minha, sem o dinheiro passar pela minha conta como custódia.

O artigo seguinte da série detalha essa mecânica e a matemática das taxas.

O que eu abri mão

Seria desonesto apresentar isso como escolha sem custo.

Perdi o controle do timing. Com destination charges, o repasse acontece quando o pagamento é capturado. Se eu quisesse segurar o valor até a aula acontecer — um escrow — precisaria de outro desenho, provavelmente separate charges and transfers.

Fiquei preso à Stripe. As contas Connect são da Stripe. Migrar de gateway com providers já onboardados significa refazer o onboarding de todos. É um custo de saída real, e eu já paguei um parecido quando migrei de Asaas para Stripe — o artigo 6 conta essa história.

Dependo do onboarding deles. Se o fluxo da Stripe rejeitar um provider, ou pedir um documento que ele não tem à mão, eu não tenho como contornar. Já aconteceu.

Foram trade-offs aceitáveis para este produto. Num marketplace onde o dinheiro precisa ficar retido até a entrega, a conta seria outra.

A regra que ficou

A decisão de arquitetura mais importante quase nunca é qual ferramenta usar. É onde traçar a linha entre o que você constrói e o que você delega — e, principalmente, quais responsabilidades você aceita junto com o código que escreve.

Custódia de dinheiro de terceiros e verificação de identidade são responsabilidades caras, contínuas e completamente fora do meu produto. Delegar isso não foi preguiça de engenharia. Foi a escolha de gastar o tempo de engenharia no que o aluno e o provider realmente veem.

Construindo o surfaai do zero: stack, decisões e o que eu faria diferente

CESAR EDUARDO STURMER — Wed, 30 Sep 2026 22:33:00 +0000

Depois de alguns anos como engenheiro de software em empresas — arquitetura de frontend, sistemas distribuídos, produtos que outras pessoas definiam — decidi construir algo do zero, sozinho: do primeiro commit até estar rodando em produção, com usuários reais e dinheiro de verdade passando pelo sistema.

Esse algo é o surfaai.

Esta é a primeira de uma série de artigos técnicos sobre as decisões que tomei construindo o surfaai. Não é um tutorial de "como fazer X" — é um relato real de arquitetura: os trade-offs que pesei, os erros que cometi, e o que eu faria diferente se começasse hoje. Se você já pensou em sair de só integrar sistemas dos outros para construir o seu, ou só curte ver decisão técnica real — com o porquê, não só o resultado final —, essa série é para você.

Por que o surfaai

O surfaai nasceu de um problema simples: conectar alunos a providers numa plataforma que cuidasse de agendamento, pagamento e repasse automático — sem que cada provider precisasse resolver seu próprio checkout, suas taxas e seu split.

Toda plataforma que conecta duas pontas com dinheiro no meio esbarra cedo ou tarde na mesma pergunta difícil: quem fica responsável pela parte financeira? Deixar cada provider resolver isso por conta própria significa fricção de onboarding, inconsistência de experiência para o aluno e nenhum controle real sobre a operação. Foi esse problema que me fez construir a camada de pagamento dentro do produto, em vez de empurrá-la para fora dele.

A stack

Next.js + React + TypeScript no front e nas rotas de API
Tailwind para a UI
Supabase (Postgres + Auth + RLS) como backend
Stripe Connect Express para pagamentos e repasse aos providers

Cada peça foi escolhida pensando em um time pequeno mantendo um produto com dinheiro real passando por ele — produtividade de desenvolvimento sem abrir mão de segurança e corretude financeira.

O desafio central: marketplace de verdade precisa de split

A parte mais delicada de um marketplace não é o cadastro nem o agendamento — é garantir que o dinheiro do aluno chegue certo ao provider, com a taxa da plataforma descontada corretamente, de forma auditável e sem condições de corrida.

Isso significou usar Stripe Connect com destination charges. O PaymentIntent é criado na plataforma, com a taxa de aplicação e o destino do repasse apontando para a conta Connect do provider:

const paymentIntent = await stripe.paymentIntents.create({
  amount: calculation.amountInCents,
  currency: "brl",
  application_fee_amount: calculation.applicationFeeAmount,
  transfer_data: {
    destination: stripeAccountId,
  },
  // ...
});

São duas linhas que carregam muita coisa: o Stripe faz a transferência do líquido para o provider automaticamente assim que o pagamento confirma, e a plataforma nunca custodia o dinheiro de terceiros. Detalho essa arquitetura — e por que não fiz o split na mão — nos próximos dois artigos.

Uma decisão que valeu a pena: créditos só nascem no webhook

Desde cedo, créditos de compra nunca são criados no client-side — só a partir do evento payment_intent.succeeded do webhook do Stripe.

Isso resolve dois problemas de uma vez. O primeiro é duplicação por condição de corrida: o usuário atualiza a página de confirmação duas vezes e ganha crédito dobrado. O segundo é mais sutil — métodos assíncronos como PIX e boleto simplesmente não têm um "momento no front" em que o pagamento confirma. O webhook é o único lugar onde cartão, PIX e boleto convergem para o mesmo caminho.

Esse é o assunto dos artigos 4 e 5 da série: o incidente real que me ensinou isso, e o padrão que saiu dele.

Migração de gateway em produção

O surfaai não nasceu no Stripe. Começou no Asaas, e migrei com usuários ativos e compras acontecendo. Foi a decisão mais arriscada do projeto, e o artigo 6 conta como foi feito sem interromper o fluxo de compra de quem estava usando.

O que vem a seguir

Nos próximos artigos:

por que Stripe Connect Express em vez de split manual
destination charges na prática, com o código e a matemática das taxas
o bug de crédito duplicado: um postmortem
idempotência em webhook de pagamento, o padrão completo
migração de gateway com a plataforma em produção

Se você constrói produtos com pagamento embutido, ou só curte ver decisão real de arquitetura com os trade-offs e os erros no caminho, essa série é para você.