Implementar este caso com um assistente de IA
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
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
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
Prepare credenciais e webhooks
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.Crie a cobrança Pix com validade curta
900 segundos, o mínimo aceito), reserva o estoque durante esse prazo e mostra o QR Code.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.id junto do pedido TL-10482. É ele que liga o pedido aos webhooks.Crie a cobrança no cartão parcelado com 3DS gerenciado
threeDSMode: "managed", envie também o objeto browser, com os dados do navegador do comprador. Dentro dele, userAgent e ipAddress são obrigatórios.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.Ofereça Apple Pay no checkout web
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.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.Atualize o pedido pelos webhooks
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.Estorne quando houver devolução
paid em Pix ou cartão, e cada cobrança aceita um estorno.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.Trate bloqueios, chargeback e MED
paid e passa a ter isBlocked: true.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.Ofereça recompra com cartão salvo
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.2RhQg9M7ZCg3X3nMb9W1kX8Q é o cliente e 2RhQgK4vN8pT1wZ6yB3mC7dF é o cartão.Regras e cuidados
- Endereço de entrega. Com algum item
physical, envieshippingAddresscompostalCode,addressLine1(logradouro e número),city,stateecountryem três letras (BRA).addressLine2eneighborhoodsã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 usetrackingStatusawaiting_shipmentna 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. Ocharge.refused(oucharge.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 ocharge.updatedcomstatus: "chargeback", que chegam só nesse canal. - Sem
Idempotency-Key. Se a criação der timeout, não reenvie às cegas: um segundoPOSTcria outra cobrança, e no cartão isso é cobrança em dobro. Recupere oidpelo webhookcharge.createdou 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 comparemetadataeamountcom 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
E se a loja vender também produtos digitais, como vale-presente?
E se a loja vender também produtos digitais, como vale-presente?
"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.E se a loja preferir fazer o 3DS por conta própria?
E se a loja preferir fazer o 3DS por conta própria?
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.E se o cliente quiser pagar em 12x?
E se o cliente quiser pagar em 12x?
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.E se a loja tiver lojas parceiras vendendo no mesmo site?
E se a loja tiver lojas parceiras vendendo no mesmo site?
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
-
postbackUrlenviado em toda cobrança, em uma URL diferente da do endpoint -
amountem reais e igual à soma dos itens -
shippingAddresscom os campos obrigatórios sempre que houver itemphysical - Pix com
expirationInSecondsa partir de900e controle do prazo no sistema de pedidos - QR Code exibido a partir de
qrCodeBase64, comcopyPastecomo alternativa - Tratamento de
paid,refused,failed,pending,in_analysiseauthentication_requiredna resposta de criação - Comprador levado à
authenticationUrlsem alterar a URL, com o resultado acompanhado por webhook ou consulta - Idempotência persistente pelo
iddo evento, separação porlivemodee confirmação comGET /v1/charges/{id} - Domínio do Apple Pay registrado e com
statusverified; CPF coletado antes da folha de pagamento - Estorno total implementado, sem reenvio quando a resposta for
422de estorno já existente - Tratamento de
charge.blocked,charge.pre_chargebacke docharge.updatedcomchargeback - Recompra pedindo o CVV a cada compra
Como homologar
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.

