Skip to main content
Uma loja virtual que vende produtos físicos precisa de um checkout que aceite as formas de pagamento que o cliente espera e mantenha o estoque alinhado com o pagamento. Também precisa avisar o sistema de pedidos quando o dinheiro entra e tratar o pós-venda: devolução, contestação e recompra. Esta página mostra como montar esse fluxo completo com a API da Finvia.
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 Trilha Leve é uma loja virtual de equipamentos de camping com sede em Curitiba. Ela fatura cerca de R$ 430 mil por mês, com 1.800 pedidos e ticket médio de R$ 240. Os pedidos saem por transportadora para todo o Brasil. O que a Trilha Leve precisa:
  • Pix com validade curta, para não segurar estoque de pedido que não vai ser pago.
  • Cartão parcelado em até 6x, porque barracas e mochilas passam de R$ 600.
  • Apple Pay no checkout web, para clientes que compram pelo iPhone.
  • 3D Secure no cartão digitado, conduzido pela Finvia, sem montar a autenticação do zero.
  • Pedido atualizado sozinho quando o pagamento é confirmado, estornado ou contestado.
  • Recompra com um clique para quem já comprou, com o cartão guardado no cofre da Finvia.

O que a Finvia resolve

Para o negócio: a mesma rota de cobrança (POST /v1/charges) atende Pix, cartão digitado, cartão salvo e Apple Pay. No cartão, a aprovação ou a recusa volta na própria resposta, então o checkout pode oferecer outra forma de pagamento na mesma tela. No Pix, o QR Code volta na resposta e a confirmação chega depois, por webhook (uma notificação que a Finvia envia ao sistema da loja). O estorno é feito por API. Quando uma venda é contestada (chargeback no cartão ou MED no Pix), a cobrança é bloqueada e a loja recebe um aviso.

Arquitetura da solução

O desenho abaixo mostra o caminho de uma compra na Trilha Leve, do checkout ao pedido liberado, com a rota usada em cada passo. O 3DS só entra quando a política 3DS da conta pede. O Apple Pay usa a mesma rota, com o objeto wallet. Depois da criação, cada cobrança segue um destes caminhos. O desenho mostra o que o sistema de pedidos faz em cada um. O aviso de Pix expirado e o chargeback formalizado chegam só como charge.updated no postbackUrl. A liberação do bloqueio não gera aviso.

Passo a passo

1

Prepare credenciais e webhooks

No painel (https://app.finvia.com.br), em Configurações > Chave de API, revele a chave secreta (sk_) e a chave pública (pk_). A secreta fica só no servidor. A pública vai para o navegador, onde o Apple Pay a usa. Se a chave for gerada por outro usuário, ele precisa ter o perfil Owner ou Manager: a chave age com o perfil de quem a gerou, e o perfil Desenvolvedor recebe 403 ao criar cobranças.Em Configurações > Webhooks, cadastre a URL que vai receber os eventos de cobrança, por exemplo https://loja.exemplo.com.br/webhooks/finvia. Envie também uma URL de postback em toda cobrança (postbackUrl). Além dos mesmos eventos do endpoint, ela recebe o evento legado charge.updated, que é o único aviso de Pix expirado e de recusa informada depois pela adquirente, e o único que traz o status: "chargeback" do chargeback formalizado.
Para o desenvolvedor: use URLs diferentes para o endpoint e para o postbackUrl, como nesta página (/webhooks/finvia e /webhooks/finvia/postback). Se a mesma URL estiver nos dois lugares, ela recebe cada evento duas vezes.
2

Crie a cobrança Pix com validade curta

O cliente escolhe Pix no checkout. A Trilha Leve cria a cobrança com validade de 15 minutos (900 segundos, o mínimo aceito), reserva o estoque durante esse prazo e mostra o QR Code.
Como o item é physical, o shippingAddress é obrigatório. Sem ele, a API responde 400 com Shipping info must be provided for merchants selling physical items. e não cria a cobrança. addressLine2 e neighborhood são opcionais: se o cliente não tem complemento, omita o campo.A resposta traz status pending e, em paymentDetails, o copyPaste (código copia e cola) e o qrCodeBase64 (imagem pronta para a tag <img>). Se qrCodeBase64 vier null, mostre só o copyPaste.
Guarde o id junto do pedido TL-10482. É ele que liga o pedido aos webhooks.
3

Crie a cobrança no cartão parcelado com 3DS gerenciado

Para o cartão digitado, a Trilha Leve pede à Finvia que conduza a autenticação 3D Secure (3DS), a verificação do portador junto ao banco emissor. Com threeDSMode: "managed", envie também o objeto browser, com os dados do navegador do comprador. Dentro dele, userAgent e ipAddress são obrigatórios.
O 3DS só entra quando a política 3DS da conta pede (3DS obrigatório, ou valor igual ou acima do mínimo configurado). A resposta depende do caso:Com authentication_required, abra o endereço recebido em authenticationUrl em um modal, iframe ou nova aba. Use o valor exatamente como veio, sem montar nem alterar a URL. A página da Finvia conduz a verificação e o desafio do banco e conclui a cobrança. O resultado chega pelos webhooks (charge.paid, charge.pending, charge.refused ou charge.failed) e pode ser conferido em GET /v1/charges/{id}. A página não devolve o comprador à loja automaticamente, então mantenha o checkout aberto acompanhando o resultado. O passo a passo está em 3DS gerenciado.
Se o comprador abandonar a autenticação, a cobrança continua em authentication_required e não gera webhook. Os dados do cartão ficam guardados por 15 minutos; depois disso, a cobrança não é mais processada e é preciso criar outra. Nunca trate uma cobrança em authentication_required como paga.
4

Ofereça Apple Pay no checkout web

A preparação é feita uma vez, com a chave secreta: registrar o domínio do checkout (POST /v1/apple-pay/domains), hospedar o arquivo de verificação em /.well-known/apple-developer-merchantid-domain-association e validar o domínio (POST /v1/apple-pay/domains/{id}/validate). Registrar o primeiro domínio ativa o Apple Pay na conta. Cada hostname (inclusive www) é um registro separado. No navegador, o evento onvalidatemerchant chama POST /v1/apple-pay/validate-merchant com a chave pública.Quando o cliente autoriza, o backend envia o payment.token sem alterações em paymentMethod.wallet.token. A moeda precisa ser BRL e customer.document é obrigatório, porque o token da Apple não traz CPF. Colete o CPF antes de abrir a folha de pagamento.
O 3D Secure não se aplica ao Apple Pay: a autenticação já vem no token. Configure supportedNetworks só com visa e masterCard, as redes suportadas hoje. No Modo Teste, a cobrança Apple Pay sai aprovada e não há como forçar uma recusa com o token da Apple.
5

Atualize o pedido pelos webhooks

O sistema de pedidos reage aos eventos de cobrança. Os eventos do envelope padrão (id, event, livemode, data) chegam aos endpoints do painel e também ao postbackUrl. Nesse envelope, as chaves do primeiro nível de data vêm em snake_case.
Para o desenvolvedor: os endpoints do painel não recebem aviso de expiração do Pix nem de recusa informada depois pela adquirente. Esses casos chegam só como charge.updated no postbackUrl (formato camelCase, sem id e sem livemode). Controle também o prazo de 15 minutos no seu sistema e, antes de liberar o estoque, consulte a cobrança com GET /v1/charges/{id} para ter certeza de que ela não foi paga no último segundo.
6

Estorne quando houver devolução

O cliente devolveu o saco de dormir. A Trilha Leve recebe o produto, confere e pede o estorno. A API faz só estorno total, de cobrança paid em Pix ou cartão, e cada cobrança aceita um estorno.
A resposta vem com status refunded: a cobrança passa a refunded e o evento charge.refunded é enviado. No Pix, a devolução é enviada na hora para a conta de origem; 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 do cliente conforme o prazo do banco emissor.
7

Trate bloqueios, chargeback e MED

Quando uma venda é contestada, a equipe Finvia bloqueia a cobrança. No cartão, a contestação é o chargeback, aberto pelo banco emissor. No Pix, é o MED (Mecanismo Especial de Devolução), o mecanismo do Pix para pedir a devolução de um pagamento. O bloqueio não muda o status: a cobrança continua paid e passa a ter isBlocked: true.A liberação do bloqueio não gera aviso. Para saber se ele continua, consulte isBlocked em GET /v1/charges/{id} ou liste as cobranças bloqueadas com GET /v1/charges?status=blocked. Não existe rota de API para enviar defesa: o alerta de chargeback ou MED chega por e-mail à conta, e as evidências da venda são enviadas em resposta a esse e-mail, dentro do prazo indicado nele. O fluxo completo está em Bloqueio, chargeback e MED.
8

Ofereça recompra com cartão salvo

Para a recompra com um clique, a Trilha Leve cadastra o cliente e registra o cartão no cofre da Finvia na primeira compra em que o cliente autoriza guardar o cartão.
O cartão nasce com status active, sem transação de teste. Na recompra, a cobrança usa o id do cartão como cardTokenId e pede o CVV de novo ao cliente. Sem o cvv, a API responde 400 CVV is required when using cardTokenId.
Nos exemplos, 2RhQg9M7ZCg3X3nMb9W1kX8Q é o cliente e 2RhQgK4vN8pT1wZ6yB3mC7dF é o cartão.

Regras e cuidados

Valor em reais. "amount": 239.8 é R$ 239,80. Confira também se a soma de unit_price × quantity dos itens bate com o amount, para o pedido e a cobrança terem o mesmo total.
Cofre compartilhado entre teste e produção. No Modo Teste, a cobrança com cardTokenId é simulada, mas o cadastro do cartão é real e o mesmo cartão funciona com a chave de produção. Uma chamada com a chave de produção cobra de verdade.
  • Endereço de entrega. Com algum item physical, envie shippingAddress com postalCode, addressLine1 (logradouro e número), city, state e country em três letras (BRA). addressLine2 e neighborhood são opcionais.
  • Rastreio. trackingInfo é enviado na criação da cobrança. A documentação não traz uma rota para atualizar o rastreio depois, então use trackingStatus awaiting_shipment na criação e acompanhe a entrega no seu sistema.
  • Recusa no cartão. A recusa volta na resposta de criação, com o motivo em reason. O charge.refused (ou charge.failed) também é enviado, mas a resposta síncrona é a fonte principal.
  • Postback em toda cobrança. Sem postbackUrl, a loja não recebe o aviso de Pix expirado nem o charge.updated com status: "chargeback", que chegam só nesse canal.
  • Sem Idempotency-Key. Se a criação der timeout, não reenvie às cegas: um segundo POST cria outra cobrança, e no cartão isso é cobrança em dobro. Recupere o id pelo webhook charge.created ou pela listagem, filtrando pelo dia e pelo e-mail ou documento do cliente (GET /v1/charges?createdAtStart=2026-03-10&createdAtEnd=2026-03-10&[email protected]), e compare metadata e amount com o pedido. O procedimento está em Paginação, ordenação e idempotência.
  • CVV a cada compra. A cobrança com cartão salvo exige o CVV do comprador sempre. Ela não serve para cobrança automática sem o cliente presente.

Variações do caso

Uma cobrança só com itens "type": "digital" não precisa de shippingAddress. Se o pedido misturar vale-presente e produto físico, basta um item physical para o endereço passar a ser obrigatório. O fluxo de liberação após charge.paid é o mesmo descrito em Infoprodutos.
Sem usar threeDSMode: "managed", a loja pode autenticar antes da cobrança com o SDK de segurança ou com as rotas de 3DS e enviar o resultado no objeto threeDS da cobrança. Só state: "success" permite seguir quando o 3DS é exigido pela configuração da conta.
installments aceita de 1 a 12. O valor de amount é o total da compra. A taxa de cada parcela é a configurada na sua conta na Finvia.
Aí o dinheiro deixa de ser só da Trilha Leve, e o desenho muda para o modelo com subcontas e split. Veja Marketplace e PSP.

Checklist de implementação

  • Chave secreta gerada por Owner ou Manager e guardada só no servidor
  • Chave pública configurada no front-end para o Apple Pay
  • Endpoint de webhook cadastrado no painel, em HTTPS
  • postbackUrl enviado em toda cobrança, em uma URL diferente da do endpoint
  • amount em reais e igual à soma dos itens
  • shippingAddress com os campos obrigatórios sempre que houver item physical
  • Pix com expirationInSeconds a partir de 900 e controle do prazo no sistema de pedidos
  • QR Code exibido a partir de qrCodeBase64, com copyPaste como alternativa
  • Tratamento de paid, refused, failed, pending, in_analysis e authentication_required na resposta de criação
  • Comprador levado à authenticationUrl sem alterar a URL, com o resultado acompanhado por webhook ou consulta
  • Idempotência persistente pelo id do evento, separação por livemode e confirmação com GET /v1/charges/{id}
  • Domínio do Apple Pay registrado e com status verified; CPF coletado antes da folha de pagamento
  • Estorno total implementado, sem reenvio quando a resposta for 422 de estorno já existente
  • Tratamento de charge.blocked, charge.pre_chargeback e do charge.updated com chargeback
  • Recompra pedindo o CVV a cada compra

Como homologar

As regras de 3DS e de antifraude da conta continuam valendo no Modo Teste. Se a conta exige 3DS ou tem antifraude ligado, a recusa pode vir dessas etapas, com reason começando com 3ds_ ou antifraud_denied. Para o CHG-03, use uma conta sem 3DS obrigatório. O detalhe de cada cenário e a evidência esperada estão no roteiro de homologação.

Veja também

Pix

Validade, QR Code e confirmação do pagamento.

3DS gerenciado

Autenticação conduzida pela Finvia.

Webhooks de cobrança

Eventos, envelopes e o canal de postback.

Bloqueio, chargeback e MED

Como acompanhar e responder a uma disputa.