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, customer e Idempotency-Key.
Quer o passo a passo com o código do formulário pronto para copiar? Está em Cobrar no cartão de ponta a ponta. Esta página explica o que cada campo significa; aquela mostra como fazer.
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.

​
O mínimo

Isto cobra. Não falta nada.
Cobrança de R$ 100,00 à vista
Três coisas que valem saber sobre esse corpo:
  • items não aparece. No cartão, description serve no lugar dele — montar um array cuja soma tem de fechar com amount para vender uma coisa só é trabalho sem função. No PIX items continua obrigatório, porque é o que o comprador lê no aplicativo do banco.
  • billing_address não aparece. É opcional, e sobe a aprovação. Dois campos bastam: CEP e número — completamos o resto.
  • Nada de 3DS. A autenticação do portador é opcional nesta API. Ver Autenticação do portador quando quiser a transferência de responsabilidade.

​
O número do cartão não passa por aqui

O que entra em card é um token de uso único, produzido no navegador pelo nosso vext.js, ou o id de um cartão guardado. Nenhum endpoint desta API aceita number ou cvv — mandá-los devolve 422, e não um silêncio. O número vai do navegador direto à adquirente: não passa pelo seu servidor nem pelos nossos, e é isso que mantém a sua aplicação e a nossa fora do escopo de PCI. Duas consequências que valem saber antes de desenhar a sua tela:
  • O token vale cerca de um minuto e serve uma vez só. Por isso a tokenização acontece no envio do formulário, nunca na abertura da página.
  • payment_method e card andam juntos. Mandar card numa cobrança Pix volta 422, e omiti-lo numa de cartão também.
O formulário pronto, a chave publicável e os domínios estão em Cobrar no cartão.

​
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.
O amount que você manda é o preço do produto. O amount que volta é o que o comprador paga — no parcelado, um número maior, com o juro dentro. O preço do produto, de volta, é amount − card.interest.E cuidado: net_amount não é amount − platform_fee. A diferença é o juro, que não é receita de ninguém aqui. Ver Cobrança.
Consequência que surpreende: parcelar não lhe custa nada. O seu líquido é o mesmo em 1x e em 12x. Ver Taxas e liquidação.

​
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. Campo a campo, com o que é anulável e o que nunca falta, em Cobrança.
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.