Skip to main content
A cobrança (charge) é o pedido de pagamento que o seu cliente vai pagar. Toda venda feita pela API da Finvia nasce de uma única rota, POST /v1/charges, e depois é acompanhada pela resposta da criação, pelos webhooks e pela consulta da cobrança. Com esse ciclo claro, a integração libera o pedido só quando ele foi pago e não deixa de liberar um pedido pago.
Para o negócio: com uma mesma integração você recebe por Pix, cartão de crédito digitado, cartão salvo e Apple Pay, e pode dividir o valor entre contas (split). A forma de pagamento muda só um bloco da requisição, o paymentMethod. O restante (valor, cliente, itens, endereço) é igual para todas.

Quando usar

Formas de pagamento

O campo paymentMethod.type define a forma de pagamento. Cartão digitado, cartão salvo e Apple Pay usam o mesmo type (credit_card) e se diferenciam pelos campos que vão junto.

Qual escolher em cada situação

A lista do que está habilitado para a sua conta, por moeda, vem de GET /v1/payment-methods. Para cobrar, a conta também precisa ter taxa configurada para o método e a moeda: sem ela, a API responde 422 Fees not configured.
O desenho abaixo resume a tabela: com duas ou três perguntas sobre o seu cenário, você chega à forma de pagamento indicada. Cartão digitado, cartão salvo e Apple Pay usam o mesmo type (credit_card) e aceitam de 1 a 12 parcelas. O Pix é sempre à vista. O desenho abaixo mostra o caminho comum a toda cobrança, da criação até a liberação do pedido, e o que fazer com cada status da resposta. Depois de paid, a cobrança ainda pode ser bloqueada ou mudar para refunded, pre_chargeback ou chargeback. Por isso o receptor de webhooks continua ativo mesmo depois de liberar o pedido.

Como funciona

1

Seu servidor cria a cobrança

Você chama POST /v1/charges com a chave secreta, informando valor, moeda, cliente, itens e forma de pagamento. Guarde o id devolvido: ele identifica a cobrança em todas as etapas seguintes.
2

A resposta síncrona diz o que fazer agora

No cartão, a resposta já traz o resultado (paid, refused ou failed), ou in_analysis quando o antifraude manda para revisão manual. No Pix, traz o QR Code com status pending. Com 3D Secure gerenciado, pode vir authentication_required com a authenticationUrl para o comprador se autenticar.
3

Os webhooks contam o que aconteceu depois

Mudanças posteriores (Pix pago, estorno, bloqueio, alerta de chargeback) chegam por webhook, uma notificação que a Finvia envia ao seu sistema. Quais eventos vão aos endpoints do painel e quais vão à postbackUrl está na tabela de eventos por canal.
4

Seu sistema confirma e libera o pedido

Antes de liberar produto ou acesso, confirme o status com GET /v1/charges/{id}. Os webhooks não têm assinatura, então a consulta à API é a sua confirmação.

Ciclo de vida da cobrança

Além do status, uma cobrança paga pode ficar bloqueada durante uma disputa (MED no Pix ou chargeback no cartão). O status continua paid e o bloqueio aparece em isBlocked na consulta e no evento charge.blocked. O detalhamento de cada status está em Status de cobrança.
Trate pending como “ainda não pago”. Libere o pedido só com paid confirmado por GET /v1/charges/{id}. Uma cobrança paid ainda pode ser bloqueada ou mudar depois para refunded, pre_chargeback ou chargeback, por isso o seu sistema precisa continuar ouvindo os webhooks.

O que vem na resposta e o que vem por webhook

A resposta da criação traz id, status, paymentDetails e reason, mais authenticationUrl e customerId em alguns casos. Os detalhes completos da cobrança (valor líquido, cliente, metadata, split, datas) vêm na consulta e nos webhooks.

Regras de negócio

Enviar o valor em centavos multiplica a cobrança por 100. 1000 gera uma cobrança de R$ 1.000,00, e não de R$ 10,00.

Itens físicos e digitais

O type de cada item diz se você entrega algo pelo correio ou transportadora (physical) ou se entrega acesso, arquivo ou serviço online (digital).
  • Produto digital (curso, ebook, software): envie items[].type digital, sem shippingAddress.
  • Produto físico (roupa, eletrônico, cosmético): envie items[].type physical e o shippingAddress. Se quiser, envie também trackingInfo com o código e a situação do envio (awaiting_shipment, on_the_way ou delivered).
Se algum item for physical e o corpo não trouxer shippingAddress, a API responde 400 com a mensagem literal Shipping info must be provided for merchants selling physical items., antes de criar a cobrança. A regra depende só dos itens enviados.

Metadata

metadata é um objeto livre onde você guarda informações suas na cobrança, como o número do pedido. Ele volta na consulta e nos webhooks, o que ajuda a ligar o evento recebido ao pedido do seu sistema.
Escreva as chaves de metadata em camelCase (orderId) ou com uma palavra só (pedido). Assim elas voltam iguais em todos os canais, e todos os exemplos desta documentação seguem essa regra.
Chaves com sublinhado (snake_case, como order_id) mudam de formato conforme o canal. Nos webhooks do envelope padrão (charge.paid, charge.refunded e os demais), elas voltam exatamente como foram enviadas (order_id). Nas respostas de GET /v1/charges e GET /v1/charges/{id} e no charge.updated legado, voltam convertidas para camelCase (orderId). Se a sua integração já usa snake_case, leia os dois formatos.

Timeout na criação

A API não aceita cabeçalho de idempotência e não busca cobranças por metadata. Se a chamada de criação der timeout, siga esta ordem:
1

Não reenvie o POST de imediato

Se a primeira chamada chegou, um novo POST cria uma segunda cobrança. No cartão, isso é cobrança em dobro.
2

Procure o charge.created

Com um endpoint de webhook cadastrado, o charge.created chega assim que a cobrança é gravada e traz o id e a metadata como foram enviadas. É a forma mais confiável de recuperar o id.
3

Busque na listagem

GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=<documento ou e-mail do comprador>&size=50, com a mesma chave usada na criação. Compare metadata e amount do seu lado.
4

Só então crie de novo

Se nada for encontrado, a cobrança não foi criada e é seguro tentar de novo. Use um timeout de cliente generoso (por exemplo, 60 segundos): o cartão é processado de forma síncrona.
Detalhes em Idempotência e em Listar cobranças.

postbackUrl

postbackUrl é uma URL sua, informada na própria cobrança, que recebe de forma assíncrona os eventos dessa cobrança. Ela não muda a resposta da criação.
  • Recebe os mesmos eventos de cobrança que os endpoints do painel, no envelope padrão: charge.created, charge.pending, charge.paid, charge.refused, charge.failed, charge.refunded, charge.pre_chargeback e charge.blocked. Não há filtro de eventos nesse canal.
  • Recebe também o charge.updated legado, que vai só para a postbackUrl, em camelCase e sem id nem livemode. Ele avisa mudanças informadas depois pelo adquirente (pagamento, recusa ou falha assíncrona, estorno, chargeback), o fim do 3DS gerenciado com recusa, o bloqueio e o alerta de pré-chargeback.
  • Se a mesma URL estiver cadastrada como endpoint e como postbackUrl, ela recebe cada evento duas vezes.
Sem postbackUrl, você não recebe o desfecho de cobranças que ficaram em in_analysis nem o aviso de chargeback formalizado. Os formatos estão na tabela de eventos por canal.

Passo a passo

Exemplo de uma cobrança Pix para um produto digital, com metadata e postback.
Resposta 201:
Para cobrar com outra forma de pagamento, troque apenas o paymentMethod. Os exemplos completos de cada forma estão nos guias específicos e em Criar uma cobrança.

Erros comuns

Perguntas frequentes

Não. Você pode enviar name e email (ou phone) dentro de customer e a API cria ou localiza o cliente na mesma chamada. O customerId da resposta traz o cliente usado, quando a cobrança chega ao adquirente. Se você já tem o cliente cadastrado, envie só o id dele. Veja Clientes.
Os endpoints do painel recebem pagamento, recusa síncrona, estorno, bloqueio e pré-chargeback. Dois avisos chegam só pelo charge.updated, na postbackUrl: o desfecho de cobranças que ficaram em in_analysis ou pending no cartão e o status chargeback do chargeback formalizado (quando o valor é revertido do saldo, os endpoints recebem também charge.refunded). Se você não usa postbackUrl, consulte essas cobranças periodicamente.
Pode. Uma cobrança paid pode ser bloqueada (isBlocked: true, ainda paid) ou ir para refunded (estorno), pre_chargeback (alerta de contestação) ou chargeback. Mantenha o seu endpoint de webhook ativo e o pedido ligado ao id da cobrança.
Não há filtro por metadata. Grave o id assim que a criação responder. Se perdeu o id, use o charge.created ou a listagem com período e searchFor, como em Timeout na criação.
Chame GET /v1/payment-methods. O filtro currency mostra o que está disponível para uma moeda específica. Pix e Apple Pay aceitam somente BRL.

Como testar

Use a chave de teste (sk_test_). No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação e o resultado do cartão depende do número usado (cartões de teste). Execute os cenários da seção “Cobrança sem split” do roteiro de homologação:
  • CHG-01 e CHG-02: cartão aprovado à vista e parcelado.
  • CHG-03: cartão recusado, com refused na resposta e o webhook charge.refused.
  • CHG-04 e CHG-05: Pix gerado e Pix pago.
  • CHG-06: consulta da cobrança.
  • CHG-07: estorno total.
  • CHG-08 e CHG-09: recebimento e simulação de webhook.
  • CHG-10: item físico sem endereço (400) e com endereço (201).
Se você usa split, execute também SPL-01 a SPL-06.

Veja também

Pix

QR Code, validade e confirmação por webhook.

Cartão de crédito

Cartão digitado, parcelamento e recusas.

Webhooks de cobrança

Eventos e formato dos payloads.

Criar uma cobrança

Todos os campos da rota.