Skip to main content
Na cobrança com cartão de crédito digitado, o cliente informa os dados do cartão no seu checkout e o seu servidor envia esses dados à Finvia na criação da cobrança. A aprovação ou a recusa volta na própria resposta, e o seu checkout já sabe se pode confirmar o pedido ou oferecer outra forma de pagamento.
Para o negócio: o cartão permite parcelar em até 12 vezes e dá a resposta na própria criação da cobrança. Quando a compra é recusada, o campo reason explica o motivo, e o checkout pode sugerir outro cartão ou o Pix sem o cliente sair da página.

Quando usar

Como funciona

O desenho abaixo mostra a cobrança com cartão digitado e os quatro resultados que podem voltar na resposta da criação. Uma recusa por 3D Secure obrigatório também chega no ramo de recusa, com reason começando em 3ds_. O caminho com authentication_required continua no guia de 3DS gerenciado.
1

O cliente preenche o cartão no seu checkout

Número, nome impresso, validade, CVV e quantidade de parcelas.
2

Seu servidor cria a cobrança

Você chama POST /v1/charges com paymentMethod.type credit_card e os dados do cartão, usando a chave secreta.
3

A resposta traz o resultado

status paid (aprovada), refused (recusada) ou failed (falha no processamento). Em recusas, reason explica o motivo. A resposta também pode vir in_analysis (revisão manual do antifraude) ou, com 3DS gerenciado, authentication_required.
4

O checkout mostra o resultado

Aprovada: confirme o pedido. Recusada: mostre o motivo e ofereça outra forma de pagamento.
5

Os webhooks acompanham o pós-venda

charge.paid, charge.refused ou charge.failed registram o resultado nos endpoints e na postbackUrl. Estornos, bloqueios e alertas de chargeback chegam depois.

Campos do cartão

Mês e ano são strings com tamanho fixo. "3" e "28" são rejeitados. Envie "03" e "2028".

Regras de negócio

Recusa: resposta síncrona e notificação

A recusa volta na resposta da criação, com status refused (ou failed) e o motivo em reason. O seu checkout deve tratar esse resultado ali mesmo, sem esperar webhook. Os webhooks complementam a resposta: O envelope padrão não traz o motivo da recusa. Ele aparece na resposta da criação, na consulta da cobrança e no charge.updated. Para cobranças que ficam em in_analysis ou pending, acompanhe pela postbackUrl ou consulte GET /v1/charges/{id}.

Dados do cliente e IP

O objeto customer da cobrança de cartão aceita estes campos:
Para o desenvolvedor: o IP do cliente é o do navegador, não o do seu servidor. Se a sua aplicação fica atrás de proxy ou balanceador, leia o IP no cabeçalho que o proxy repassa (ex.: X-Forwarded-For), conforme a configuração da sua infraestrutura.

Segurança no checkout

Nesta forma de pagamento, os dados completos do cartão passam pelo seu servidor, porque é ele que chama a API. Isso traz responsabilidades para a sua aplicação:
  • Use HTTPS em todas as páginas do checkout e em todas as chamadas, do navegador ao seu servidor e do seu servidor à API.
  • Não grave o número do cartão nem o CVV em banco de dados, arquivos ou caches. Use os dados só na chamada e descarte.
  • Não registre em log o corpo da requisição de cobrança sem mascarar number e cvv. Registre apenas os 6 primeiros e os 4 últimos dígitos, que a própria resposta devolve (firstSix e lastFour).
  • Mantenha a chave secreta no servidor. O navegador nunca chama POST /v1/charges direto.
  • Para recompra, use o cofre de cartões, que guarda o cartão na Finvia e devolve um identificador.
Verifique com a sua área de segurança e conformidade os requisitos que se aplicam à sua empresa por trafegar dados de cartão no seu servidor.

Passo a passo

Cobrança parcelada de produto físico

Respostas possíveis

paymentDetails é anulável. Trate o caso em que ele vem null e use status e reason para decidir o que mostrar ao cliente. customerId não vem quando a cobrança é barrada antes de chegar ao adquirente (antifraude ou 3DS).

Cartões de teste

No Modo Teste (chave sk_test_), a cobrança vai para um processador simulado e o resultado depende só do número do cartão. Envie o número só com dígitos. Nome, CVV e validade não influenciam o resultado: use qualquer nome, CVV numérico de 3 dígitos e validade futura (mês com 2 dígitos, ex.: 05, e ano com 4). O parcelamento de 1 a 12 vezes funciona igual, desde que a conta tenha taxa configurada para o número de parcelas. A recusa é síncrona e vem na própria resposta.
Esses números só valem com a chave de teste. Com a chave de produção, a cobrança vai para a adquirente real. As regras de 3D Secure e de antifraude da sua 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 em 3ds_ ou antifraud_denied.

Estorno e chargeback

  • Estorno: uma cobrança paga pode ser estornada por POST /v1/refunds, sempre pelo valor total. O pedido vai à adquirente na hora, e o crédito aparece na fatura do comprador conforme o prazo do banco emissor. Você recebe charge.refunded. Veja Estorno.
  • Pré-chargeback: quando o titular contesta a compra no emissor, a cobrança pode receber um alerta (pre_chargeback), avisado pelo charge.pre_chargeback.
  • Bloqueio: durante a disputa, a equipe Finvia pode bloquear a cobrança (isBlocked: true, status ainda paid), avisado pelo charge.blocked.
  • Chargeback formalizado: chega pelo charge.updated com status: "chargeback" na postbackUrl e, quando o valor é revertido do saldo, também pelo charge.refunded.
O fluxo completo está em Bloqueio, chargeback e MED.

Erros comuns

Perguntas frequentes

Não. Aprovação e recusa voltam na resposta da criação. Os webhooks charge.paid, charge.refused e charge.failed complementam a resposta. A exceção é a cobrança que fica in_analysis ou pending: o desfecho chega depois, pelo charge.updated na postbackUrl ou pela consulta.
De 1 a 12, desde que a sua conta tenha taxa configurada para o número de parcelas. A quantidade usada volta em paymentDetails.installments.
Use o cofre de cartões com POST /v1/cards e cobre depois com cartão salvo. Não guarde número e CVV no seu banco de dados.
Não pela rota de cobrança: ela exige o CVV em toda cobrança. Para cobrança recorrente, use Assinaturas.
No Modo Teste, use o cartão 4444333322221112. A resposta vem refused com reason card_declined e o webhook charge.refused é enviado. Use uma conta sem 3DS obrigatório, para a recusa não vir da autenticação.

Como testar

Com a chave de teste (sk_test_) e os cartões de teste, execute no roteiro de homologação:
  • CHG-01: cartão 4444333322221111 à vista, com paid e webhook charge.paid.
  • CHG-02: cartão parcelado (ex.: 3x), com installments refletido.
  • CHG-03: cartão 4444333322221112, com refused na própria resposta e o webhook charge.refused.
  • CHG-07: estorno total.
  • CHG-10: item físico sem endereço (400) e com endereço (201).
Se a sua conta usa 3D Secure, inclua também o cenário de 3DS da sua conta.

Veja também

Cartão salvo

Recompra com um clique.

3D Secure

Autenticação do titular do cartão.

Estorno

Como devolver uma cobrança paga.

Criar uma cobrança

Todos os campos da rota.