Implementar este caso com um assistente de IA
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 (A resposta traz
3600 segundos).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
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 O mesmo evento pode chegar mais de uma vez. Guarde os
status paid confirmado pela API. O webhook é o gatilho, e a consulta é a confirmação.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
- Pix mínimo de 15 minutos.
expirationInSecondsaceita a partir de900. Para prazos em dias, useexpirationInDays(mínimo1). - Sem endereço em produto digital.
shippingAddressé para produto físico. Em cobrança só com itensdigital, não envie. - Postback em toda cobrança. O
charge.updatedcomstatus: "chargeback"e os avisos de recusa informada depois pela adquirente chegam só pelopostbackUrl. - 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
E se o curso tiver um professor coprodutor?
E se o curso tiver um professor coprodutor?
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 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
split manda a parte do coprodutor para a subconta dele: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.E se houver afiliados?
E se houver afiliados?
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.E se a escola quiser vender o curso por assinatura mensal?
E se a escola quiser vender o curso por assinatura mensal?
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.E se o aluno quiser comprar o segundo curso sem digitar o cartão de novo?
E se o aluno quiser comprar o segundo curso sem digitar o cartão de novo?
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 semshippingAddress; com itemphysical, endereço completo - Pix com validade definida (a partir de
900segundos) - Cartão com
installmentsaté12 - Liberação de acesso só com
statuspaidconfirmado emGET /v1/charges/{id} - Idempotência persistente pelo
iddo evento - Suspensão de acesso em
charge.blockedecharge.pre_chargeback, e revogação emcharge.refundede nocharge.updatedcomchargeback - Estorno com checagem prévia para não duplicar
-
postbackUrlem 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.

