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, comreason 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
Regras de negócio
Recusa: resposta síncrona e notificação
A recusa volta na resposta da criação, comstatus 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 objetocustomer da cobrança de cartão aceita estes campos:
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
numberecvv. Registre apenas os 6 primeiros e os 4 últimos dígitos, que a própria resposta devolve (firstSixelastFour). - Mantenha a chave secreta no servidor. O navegador nunca chama
POST /v1/chargesdireto. - Para recompra, use o cofre de cartões, que guarda o cartão na Finvia e devolve um identificador.
Passo a passo
Cobrança parcelada de produto físico
Respostas possíveis
- Aprovada
- Recusada
- Em análise
- Sem endereço (400)
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 (chavesk_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.
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ê recebecharge.refunded. Veja Estorno. - Pré-chargeback: quando o titular contesta a compra no emissor, a cobrança pode receber um alerta (
pre_chargeback), avisado pelocharge.pre_chargeback. - Bloqueio: durante a disputa, a equipe Finvia pode bloquear a cobrança (
isBlocked: true, status aindapaid), avisado pelocharge.blocked. - Chargeback formalizado: chega pelo
charge.updatedcomstatus: "chargeback"napostbackUrle, quando o valor é revertido do saldo, também pelocharge.refunded.
Erros comuns
Perguntas frequentes
Preciso esperar um webhook para saber se o cartão foi aprovado?
Preciso esperar um webhook para saber se o cartão foi aprovado?
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.Quantas parcelas posso oferecer?
Quantas parcelas posso oferecer?
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.Posso guardar o cartão do cliente para a próxima compra?
Posso guardar o cartão do cliente para a próxima compra?
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.Posso cobrar o cartão todo mês sem o cliente informar o CVV?
Posso cobrar o cartão todo mês sem o cliente informar o CVV?
Não pela rota de cobrança: ela exige o CVV em toda cobrança. Para cobrança recorrente, use Assinaturas.
Como testo uma recusa?
Como testo uma recusa?
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, compaide webhookcharge.paid. - CHG-02: cartão parcelado (ex.: 3x), com
installmentsrefletido. - CHG-03: cartão
4444333322221112, comrefusedna própria resposta e o webhookcharge.refused. - CHG-07: estorno total.
- CHG-10: item físico sem endereço (
400) e com endereço (201).
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.

