Skip to main content
POST
Guardar cartão sem cobrar
Quando existe uma primeira venda, prefira save_card: true nela: é uma chamada a menos, e o cartão entra no cofre com uma autorização real no histórico. Esta rota é para os casos em que não há primeira venda ainda — assinatura com teste grátis, cobrança adiada, upsell combinado antes de qualquer cobrança.
O número do cartão não entra aqui. O que entra é o token de uso único que o vext.js criou no navegador — o mesmo token de uma cobrança. Ele vale cerca de um minuto.
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. Não é uma autorização — um cartão guardado por aqui passou por uma consulta, não por uma venda. A diferença aparece na taxa de aprovação da primeira cobrança.
O mesmo plástico guardado de novo devolve o mesmo pm_, e não cria um segundo. Ver Cofre de cartões.

Authorizations

Authorization
string
header
required

Chave secreta do vendedor, criada no painel em Desenvolvedores.

O valor em claro existe uma única vez, na criação. Guardamos só o hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto: um dump do nosso banco não permite cobrar em nome de ninguém.

A chave vai no servidor. Colocá-la no navegador do comprador a entrega a qualquer pessoa que abra a página.

Headers

Idempotency-Key
string

Identificador único da SUA tentativa. Use o mesmo valor ao repetir a requisição depois de um erro de rede.

Opcional, mas recomendado em toda criação de cobrança e estorno. Sem ele, uma repetição cria uma segunda cobrança.

Maximum string length: 255

Body

application/json

O corpo de POST /v1/cards. Mesmo vocabulário de POST /v1/charges de propósito: quem já integra a cobrança no cartão não tem um segundo formato para aprender.

O que não existe aqui: amount, items e installments - não há venda -, e card.id - esta rota cria a referência do cofre, e receber uma já existente seria pedir para guardar o que já está guardado. Mandar qualquer um deles devolve 422.

customer
object
required
card
object
required

Response

Cartão guardado. O mesmo plástico guardado de novo devolve o mesmo pm_ - não cria um segundo.

Um cartão guardado. Todo campo está sempre presente.

O que NÃO está aqui, e não vai estar: as referências da Pagar.me que de fato cobram, e os seis primeiros dígitos. As primeiras são o equivalente ao cartão para quem as tem; o BIN somado aos quatro últimos é material de correlação que você não precisa.

object
string
required
Allowed value: "card"
id
string
required
Pattern: ^pm_[0-9a-z]{26}$
brand
enum<string> | null
required
Available options:
visa,
mastercard,
elo,
hipercard,
amex,
diners,
discover,
aura,
null
last_four
string | null
required
exp_month
integer | null
required
Required range: 1 <= x <= 12
exp_year
integer | null
required
holder_name
string | null
required
expired
boolean
required

Vencido é ESTADO, e não ausência: o cartão continua na lista para você entender por que a cobrança de um clique parou de funcionar para aquele comprador.

created_at
string<date-time> | null
required
last_used_at
string<date-time> | null
required