Skip to main content
Uma cobrança no cartão nasce de POST /v1/charges com payment_method: "credit_card" e um objeto card. O restante da chamada é igual ao PIX — mesmos amount, items, customer e Idempotency-Key.
Os valores aqui são inteiros em centavos: R$ 100,00 se envia como 10000. Decimais são recusados com 422, e o porquê está em Valores em centavos.

​
A regra

O número do cartão não entra nessa chamada. O que entra é um token de uso único, produzido no navegador pela biblioteca de tokenização da Pagar.me, ou o id de um cartão guardado.
Cobrança de R$ 100,00 em 3x
Mandar card numa cobrança PIX volta 422, e omiti-lo numa de cartão também. A dupla payment_method + card anda junta.

​
Ao contrário do PIX, uma recusa cria cobrança

Esta é a distinção que mais gera chamado. Um 422 significa que nada foi criado — o corpo não passou na validação. Um 402 card_declined significa que a cobrança existe, com status failed, e o seu ch_ está em error.details.charge_id.
402
Grave esse ch_ junto do pedido. Ele aparece em GET /v1/charges, conta na sua taxa de aprovação e é por ele que o suporte encontra a tentativa — jogar a resposta fora deixa você sem nada para mostrar quando o comprador jurar que tentou pagar. A message é nossa e é a que você pode mostrar ao comprador. O decline_code é da operadora, e serve para o seu time entender o padrão das recusas, não para virar texto na tela.

​
Parcelas e juros

installments é obrigatório. Mesmo à vista, mande 1 — deixá-lo de fora não vira um padrão implícito, volta 422. A grade de parcelas não é fixa: ela muda por bandeira e por valor, e quem a calcula somos nós. Consulte-a em GET /v1/installments e mostre ao comprador os valores que vieram de lá. O juro, quando houver, é cobrado do comprador e soma ao total. Ele volta em card.interest, em centavos, e o amount da cobrança continua sendo o preço do seu produto — é o que faz a sua conciliação fechar sem descobrir a diferença no fim do mês.

​
O que a resposta traz

Toda cobrança tem o objeto card. Numa cobrança PIX ele vem com os membros nulos, o que evita que o seu código precise checar a existência do objeto antes de ler um campo. Numa venda no cartão ele traz bandeira, quatro últimos dígitos, titular, parcelas, juros, o resultado da autenticação do portador e o authorized_at.
authorized_at não é paid_at. A autorização reserva o limite no cartão; a captura é o que move o dinheiro. Quem confirma a venda para o seu sistema continua sendo o webhook charge.paid.

​
O que dá errado

Uma venda no cartão também pode entrar em in_analysis antes de decidir. Ela não está paga nem recusada: a análise de fraude segurou o pagamento e o desfecho chega por charge.in_analysis e depois por charge.paid ou charge.failed. Ver Ciclo de vida.

​
Veja também

Autenticação do portador

Quando o 3DS entra e o que ele muda numa contestação.

Cofre de cartões

Cobrar de novo sem pedir nada ao comprador.

Ciclo de vida

Os dez estados, incluindo in_analysis e chargedback.
Ficou algo de fora? Chame no WhatsApp. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.