Skip to main content
Quem vende curso online, e-book, mentoria gravada ou comunidade paga entrega o produto no instante em que libera o acesso. Por isso, o ponto central da integração é liberar só depois que o pagamento estiver confirmado, e revogar quando houver reembolso ou contestação. Esta página mostra esse fluxo e, nas variações, como dividir a receita com coprodutores e afiliados.
Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em Integrar com IA.

Implementar este caso com um assistente de IA

Open in Cursor

O cenário

A Planilha Pro Educação vende cursos de Excel e análise de dados para profissionais de escritório. O carro-chefe é o curso Excel do Zero ao Dashboard, por R$ 497,00, em até 12x no cartão ou à vista no Pix. Em lançamentos, ela recebe até 1.200 pedidos em uma semana. O que a Planilha Pro precisa:
  • Pix com prazo de 1 hora, para o aluno pagar no app do banco sem pressa e sem deixar pedidos abertos por dias.
  • Cartão parcelado em até 12x.
  • Acesso à plataforma de aulas liberado só com pagamento confirmado.
  • Reembolso por API quando o aluno pede dentro do prazo de garantia da escola.
  • Em alguns cursos, divisão da receita com um professor coprodutor.

O que a Finvia resolve

Para o negócio: a cobrança é criada com itens do tipo digital, sem endereço de entrega. No cartão, o resultado volta na resposta. No Pix, a confirmação chega por webhook (charge.paid). A Planilha Pro libera o acesso quando recebe esse evento e confirma o status consultando a cobrança na API, porque os webhooks não têm assinatura criptográfica. O reembolso é um estorno total feito por API. Com o Connect, a receita de um curso pode ser dividida com coprodutores e afiliados no momento da venda.

Arquitetura da solução

O desenho abaixo mostra a venda de um curso da Planilha Pro, do checkout à liberação do acesso. A linha pontilhada da coprodução só existe quando a escola usa o Connect, como na variação do fim da página. A liberação e a revogação do acesso seguem as regras do desenho abaixo.

Passo a passo

1

Monte os itens do pedido

Os cursos vão como itens "type": "digital", e a cobrança não leva endereço de entrega. Se a Planilha Pro vender também uma apostila impressa, basta um item physical no pedido para o shippingAddress passar a ser obrigatório. Sem ele, a API responde 400 com Shipping info must be provided for merchants selling physical items..
2

Crie a cobrança Pix

O aluno escolhe Pix. A cobrança vale 1 hora (3600 segundos).
A resposta traz status pending e o QR Code em paymentDetails. Mostre a imagem de qrCodeBase64 e um botão para copiar o copyPaste, que é o que o aluno usa quando está comprando pelo próprio celular.
3

Ou crie a cobrança no cartão parcelado

Com status paid, o pagamento foi aprovado. Com refused ou failed, o motivo vem em reason e a página de checkout oferece o Pix ou outro cartão. Com in_analysis, a cobrança foi para revisão manual do antifraude: não libere o acesso e aguarde o desfecho.
4

Libere o acesso só com pagamento confirmado

A regra da Planilha Pro é: nenhum acesso é liberado sem status paid confirmado pela API. O webhook é o gatilho, e a consulta é a confirmação.
Para o desenvolvedor: no cartão, a resposta da criação já traz paid. Você pode liberar o acesso a partir dela, porque ela vem da chamada que o seu servidor fez à API. O que não deve liberar acesso sozinho é um POST recebido no endpoint de webhook sem confirmação: qualquer um que descubra a URL pode enviar um payload falso.
O mesmo evento pode chegar mais de uma vez. Guarde os id de evento já processados em banco de dados ou cache persistente, que sobrevivem a uma reinicialização do servidor.
5

Reembolse dentro da garantia

A Planilha Pro oferece garantia de 7 dias. Quando o aluno pede o reembolso, o sistema verifica o prazo pela política da escola e pede o estorno total:
A API faz só estorno total, e cada cobrança aceita um único estorno. Se a chamada der timeout, consulte a cobrança antes de reenviar: se ela já estiver refunded, não peça de novo. No Pix, a devolução é enviada na hora para a conta de origem do aluno; peça o estorno em até 90 dias do pagamento, que é o prazo das regras do Pix. No cartão, o crédito aparece na fatura conforme o prazo do banco emissor.
6

Acompanhe contestações

Se o aluno contestar a compra no banco (chargeback no cartão ou MED, o Mecanismo Especial de Devolução, no Pix), a equipe Finvia bloqueia a cobrança. Ela continua paid, passa a ter isBlocked: true, e o evento charge.blocked chega aos endpoints e ao postbackUrl. A Planilha Pro suspende o acesso enquanto a disputa corre e guarda as evidências da venda: registro de acesso às aulas, e-mail de compra, aceite dos termos. O alerta chega por e-mail à conta, e a Planilha Pro envia essas evidências em resposta a esse e-mail, dentro do prazo indicado nele. Não existe rota de API para defesa.A liberação do bloqueio não gera aviso: consulte isBlocked em GET /v1/charges/{id} para saber se o acesso pode voltar. O fluxo completo está em Bloqueio, chargeback e MED.

Regras e cuidados

Não libere acesso a partir do webhook sem consultar a API. Os webhooks não têm assinatura HMAC (Webhooks): confirme o status com GET /v1/charges/{id} antes de entregar o produto.
Valor em reais. "amount": 497 é R$ 497,00. Enviar 49700 gera uma cobrança de R$ 49.700,00.
  • Pix mínimo de 15 minutos. expirationInSeconds aceita a partir de 900. Para prazos em dias, use expirationInDays (mínimo 1).
  • Sem endereço em produto digital. shippingAddress é para produto físico. Em cobrança só com itens digital, não envie.
  • Postback em toda cobrança. O charge.updated com status: "chargeback" e os avisos de recusa informada depois pela adquirente chegam só pelo postbackUrl.
  • Prazo de garantia é da sua política. A API não impõe prazo máximo para pedir o estorno (no Pix, peça em até 90 dias do pagamento, pelas regras do Pix). Quem decide se o pedido está dentro da garantia é o seu sistema.
Os formatos dos avisos são diferentes. No envelope padrão (charge.paid, charge.refunded e os demais), as chaves do primeiro nível de data vêm em snake_case (psp_ref_id, merchant_id) e o metadata volta como foi enviado. O charge.updated e as respostas da API usam camelCase, inclusive nas chaves de metadata. Por isso, os exemplos usam chaves de metadata de uma palavra só (pedido, curso), que ficam iguais em todos os formatos.

Variações do caso

A divisão automática exige o Connect. A Planilha Pro passa a ser a conta master e o coprodutor, uma subconta do mesmo grupo, com cadastro e KYC próprios. Na venda criada pela conta master, o split manda a parte do coprodutor para a subconta dele:
O percentual incide sobre o valor líquido: o valor da venda menos a taxa transacional da Finvia. Se o acordo de coprodução já é sobre o líquido (“40% do que entrar”), informe 40. Se o acordo é sobre o bruto, ajuste o percentual com a fórmula de Cálculo de split. Se a Planilha Pro antecipar o recebível, o split é recalculado sobre o valor já descontada a taxa de antecipação.A parte do coprodutor é repassada quando o recebível da Planilha Pro é liquidado: no Pix, logo após a confirmação do pagamento; no cartão, parcela a parcela, em D+30, D+60 e assim por diante. Os eventos da cobrança vão só para a Planilha Pro, dona da venda; a subconta do coprodutor não recebe esses avisos.
Cada afiliado vira uma subconta no grupo da escola. Na venda indicada por um afiliado, a cobrança leva um segundo item no split, com a subconta do afiliado e o percentual combinado. A soma de todos os percentuais não pode passar de 100%, e o que sobra fica com quem originou a venda. Como o afiliado só recebe por subconta ativa, inclua o cadastro e o KYC dele no processo de entrada no programa.
Use as assinaturas, que cobram o cartão automaticamente a cada ciclo. O desenho, com liberação e bloqueio de acesso por subscription.*, está em SaaS por assinatura. As cobranças recorrentes das assinaturas não recebem split, então um curso em coprodução vendido por assinatura não divide a receita automaticamente.
Registre o cartão no cofre com POST /v1/cards (cliente com e-mail e CPF) e use cardTokenId na próxima compra. O CVV continua obrigatório a cada cobrança. Veja Cartão salvo.

Checklist de implementação

  • Itens enviados com "type": "digital" e sem shippingAddress; com item physical, endereço completo
  • Pix com validade definida (a partir de 900 segundos)
  • Cartão com installments até 12
  • Liberação de acesso só com status paid confirmado em GET /v1/charges/{id}
  • Idempotência persistente pelo id do evento
  • Suspensão de acesso em charge.blocked e charge.pre_chargeback, e revogação em charge.refunded e no charge.updated com chargeback
  • Estorno com checagem prévia para não duplicar
  • postbackUrl em toda cobrança
  • Para coprodução e afiliados: Connect habilitado, subcontas ativas e percentuais somando até 100%

Como homologar

No Modo Teste, o Pix passa sozinho para paid cerca de 5 segundos depois da criação (CHG-05), e o cartão 4444333322221112 gera a recusa do CHG-03. Use o reenvio de webhook de teste (CHG-09, POST /v1/charges/{id}/resend-webhook) para testar o tratamento de outros status: ele dispara um evento novo, com id novo, e não altera a cobrança. Como a consulta GET /v1/charges/{id} continua mostrando o status real, a liberação de acesso só acontece com um pagamento confirmado. Detalhes no roteiro de homologação.

Veja também

Webhooks de cobrança

Eventos, envelopes e retentativas.

Estorno

Estorno total e o que acontece com a cobrança.

Split

Como dividir uma venda entre contas do mesmo grupo.

Reenviar webhook de teste

Simule eventos no sandbox.