Skip to main content
Um cartão guardado deixa a segunda compra acontecer num toque. Você cobra citando um código pm_, e o comprador não redigita número, validade nem CVV.

​
Como um cartão entra

De dois jeitos, e o primeiro é o melhor sempre que existir.

​
Na venda, com save_card

Como efeito de uma venda aprovada em que alguém pediu para guardar:
Ao criar a cobrança
Uma cobrança recusada não guarda nada. Se o cofre falhar por qualquer motivo, a venda segue aprovada: guardar um cartão nunca pode derrubar um pagamento que já deu certo. Prefira este caminho. A cobrança aprovada é a prova de que aquele cartão era mesmo do comprador, e essa prova aparece depois na taxa de aprovação das cobranças seguintes.

​
Sem cobrar, com POST /v1/cards

Para quando não há primeira venda: assinatura com teste grátis, cobrança adiada, upsell combinado antes de qualquer cobrança.
Ao guardar, pedimos ao provedor uma verificação sem valor: ele consulta a bandeira e o emissor para saber se o cartão existe e pode transacionar, sem tocar no limite do comprador. Falhando, nada é guardado.
Essa verificação é menos que uma autorização, e a diferença é real: um cartão guardado por aqui passou por uma consulta, não por uma venda. É por isso que esta rota tem um limite de chamadas bem mais apertado que o resto da API — a mesma consulta que valida um cartão legítimo serve para descobrir, de graça, se um número roubado está vivo. Vinte por minuto cobrem o uso real; quem precisa migrar uma base grande fala com a gente antes.
O mesmo plástico guardado de novo devolve o mesmo pm_ — não cria um segundo.

​
Como cobrar com ele

Em POST /v1/charges, troque o token pelo id:
card.id e save_card não convivem na mesma cobrança: um cartão que já está no cofre não entra nele de novo.

​
Consultar e remover

Os três endpoints pedem o escopo cards:manage: A listagem filtra por customer_document, que é como você encontra os cartões de um comprador específico. Cartões vencidos ficam de fora por padrão; include_expired=true os traz de volta. Remover revoga, não apaga. O cartão deixa de poder ser cobrado na hora, e o registro continua existindo — é o que permite responder “com que cartão foi aquela cobrança de março” um ano depois. Apagar a linha deixaria a sua conciliação com um buraco justamente nas vendas que alguém contestou.
last_four e brand são para exibir, nunca para reconhecer. Dois cartões do mesmo comprador podem terminar nos mesmos quatro dígitos, e a bandeira que precifica a parcela é detectada pelo BIN antes da autorização. O que identifica um cartão é o pm_.

​
O que dá errado

A referência guardada pertence à conta do adquirente que a criou. Trocar a conta da sua loja invalida todos os cartões do cofre de uma vez, e as recompras passam a ser recusadas com uma mensagem genérica da operadora — que se parece com cartão sem limite. Antes de trocar de conta, conte com os compradores tendo de digitar o cartão outra vez.

​
Veja também

Cartão guardado

Campo a campo do que estas rotas devolvem.

Cobrança no cartão

Parcelas, juros e o objeto card da resposta.

Assinaturas

Cobrar em série com o pm_, e o que a bandeira exige.

Autenticação do portador

Por que o cofre e a autenticação não convivem.
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.