Skip to main content
POST
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.
Envie Idempotency-Key nesta chamada e você pode repetir com tranquilidade depois de um erro de rede: a mesma chave devolve o recurso que já existe, em vez de criar um segundo. Veja Idempotência.
items é obrigatório. Mande pelo menos um item, e a soma de quantity * amount de todos eles precisa bater exatamente com o amount da cobrança — senão a chamada volta 422 items_do_not_match_amount. Vendendo uma coisa só, mande um item único com o valor cheio.
A resposta traz pix.qr_code, o payload copia-e-cola. A imagem do QR não é devolvida: você a gera localmente a partir do payload. Ver Checkout PIX de ponta a ponta.

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.

Scopes

​
charges:write

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
​
amount
integer<int64>
required

O preço do que você está vendendo, em centavos inteiros. R$ 100,00 = 10000. Um decimal aqui é recusado com 422.

No cartão PARCELADO, o amount que volta na resposta é MAIOR que este: o juro é cobrado do comprador e soma ao total. Você manda o preço do produto; nós calculamos o que ele paga. Ver amount no objeto Charge.

Required range: x >= 1
​
customer
object
required
​
items
object[]
required

A soma de quantity × amount de todos os itens deve bater exatamente com o amount da cobrança.

No PIX é obrigatório. Os itens são a única descrição do que está sendo vendido que chega ao arranjo de pagamento, e é o que o comprador lê no aplicativo do banco ao confirmar - uma cobrança que não diz o que cobra chega à tela dele como um valor sem causa.

No cartão, mande items OU description. Aquela tela não existe ali, e montar um array cuja soma tem de fechar para vender uma coisa só é trabalho sem função: description: "Plano mensal" basta, e nós derivamos o item. Quem vende um carrinho continua mandando os itens.

Required array length: 1 - 100 elements
​
description
string | null

Aparece para o comprador na tela de pagamento.

Maximum string length: 255
​
reference
string | null

Sua referência (número do pedido, id interno). Volta na consulta e nos webhooks, e serve de filtro em GET /v1/charges - é o que permite casar a cobrança com o seu pedido sem guardar o nosso id.

Maximum string length: 120
​
metadata
object | null

Até 20 pares de chave/valor seus, devolvidos na consulta e nos webhooks. É o reference para quem precisa de mais de um rótulo - com uma diferença: reference filtra a listagem, metadata não.

Os valores devem ser strings. Um número aqui é recusado com 422: {"total": 10.10} voltaria como 10.1, e a formatação do seu dado é sua. Envie {"total": "10.10"}.

Example:
​
expires_in
integer | null
default:86400

Validade do QR, em segundos. O piso de 60s evita uma cobrança que expira antes de o comprador abrir o aplicativo do banco. Omitindo o campo, a cobrança vale 24 horas.

Required range: 60 <= x <= 604800
​
customer_ip
string<ip> | null

O IP do comprador, em IPv4 ou IPv6.

Numa integração servidor-a-servidor quem abre a conexão conosco é o seu servidor. Sem este campo é o endereço dele que guardamos, e o "Local" da venda no painel apontaria para o seu datacenter em toda cobrança. Mande o IP de quem está comprando e o dado passa a valer numa contestação.

Fica fora de customer porque é da tentativa, não do cadastro: muda a cada compra da mesma pessoa.

Example:

"189.45.12.7"

​
payment_method
enum<string>
default:pix

Omitido, é pix - e continua sendo, para sempre. Toda integração que existe hoje manda o corpo sem este campo, e torná-lo obrigatório as quebraria todas por uma adição nossa.

Com credit_card, o objeto card passa a ser obrigatório e expires_in passa a ser recusado: cartão não expira.

Com boleto, o objeto boleto é opcional - a plataforma já tem prazo e instruções padrão. Boleto só está disponível para lojas em conta de split na Pagar.me; fora desse arranjo a resposta é 422 com boleto_not_available.

Available options:
pix,
credit_card,
boleto
​
boleto
object | null

Opcional quando payment_method é boleto, e recusado nos demais - mandá-lo num PIX devolve 422, pela mesma razão do card: aceitar e ignorar faria você acreditar que emitiu um boleto.

​
card
object | null

Obrigatório quando payment_method é credit_card, e recusado nos demais. Mandá-lo num PIX devolve 422: aceitar e ignorar faria você ver a cobrança nascer e acreditar que cobrou no cartão.

​
three_d_secure
enum<string>
default:automatic

A autenticação do portador é opcional nesta API, e o padrão é não autenticar. Você não precisa deste campo para cobrar no cartão.

Mande required quando quiser autenticar: a cobrança passa a exigir card.three_ds, e você roda o desafio no navegador antes de cobrar - ver POST /v1/three_ds_tokens. É o caminho de quem quer a transferência de responsabilidade: sem autenticação, uma contestação por "não fui eu" sai do seu saldo; com ela, responde o banco emissor.

automatic (o padrão) e off fazem a mesma coisa hoje: não autenticam. off existe para quem já o escreveu no código um dia e não deve ver a cobrança quebrar por uma simplificação nossa.

O interruptor de 3DS da sua conta, no painel, não vale aqui - ele governa os checkouts hospedados por nós, onde somos nós que montamos a tela e podemos pedir o desafio ao comprador. Nesta API quem monta a tela é você, e exigir um identificador que só o navegador produz devolveria um 422 impossível de resolver a quem cobra de um servidor.

Available options:
automatic,
required,
off
​
save_card
boolean
default:false

Guarda o cartão no cofre se, e somente se, a venda for aprovada, e a próxima cobrança usa card.id. Recusada, nada é guardado: uma referência de autorização negada é uma referência que a própria Pagar.me pode não honrar depois.

O pm_ não volta nesta resposta - ele nasce depois dela. Busque-o em GET /v1/cards?customer_document=….

Recusado junto com card.id: aquele cartão já está guardado, e aceitar-e-ignorar ensinaria errado.

Guardar credencial de pagamento sem o comprador ter pedido é problema regulatório antes de ser problema de produto. O consentimento é seu para colher.

​
recurrence
object | null

Declare aqui quando esta cobrança é parte de uma assinatura.

Só no cartão; num PIX é recusado com 422. E installments passa a aceitar apenas 1: a bandeira não parcela uma cobrança recorrente - quem quer dividir uma assinatura cobra mais vezes, não uma vez em doze.

Omitir o campo numa cobrança de série não dá erro nenhum, e é justamente o problema: a Pagar.me aceita o pedido, e a falta vira multa de bandeira semanas depois. Mastercard, Visa e Elo exigem a declaração.

Declarar recorrência **não** devolve o liability shift. Ela é conformidade de bandeira - evita multa, não evita contestação. A proteção continua vindo da autenticação do portador, e por isso o caminho seguro é **autenticar a primeira cobrança** (com o comprador na tela, sem cartão guardado) e deixar as seguintes correrem declaradas.

Numa loja que exige 3DS, uma cobrança com card.id e recurrence passa em vez de levar 403 one_click_requires_three_ds - e corre sem transferência de responsabilidade. É uma escolha sua.

​
device_event_id
string | null

O identificador do evento de identificação do aparelho - é o deviceEventId que o createToken() da Pagar.me devolve ao seu JavaScript.

Opcional sempre. Bloqueador de anúncio corta a identificação com frequência, e recusar a venda porque o enriquecimento de risco não carregou troca uma fraude possível por uma perda certa.

Maximum string length: 255

Response

Cobrança criada e aguardando pagamento.

Uma cobrança, como a API a devolve. Todo campo desta lista está sempre presente - os anuláveis vêm com null, nunca ausentes. Marcar como opcional o que nunca falta obrigaria você a testar a existência de uma chave que sempre existe.

Nos webhooks há uma exceção documentada: veja ChargeMinimal.

​
object
string
required
Allowed value: "charge"
​
id
string
required

Código público da cobrança. Nunca é a chave primária: expor o autoincremento diria a qualquer cliente quantas vendas a plataforma inteira processou.

Example:

"ch_01k1y6r6m6q2x0p3d9v4t7c8n2"

​
status
enum<string>
required

Situação da cobrança. Só os estados de trânsito - pending, processing e in_analysis - ainda mudam sozinhos; os demais são terminais, exceto os que ainda admitem estorno.

processing e in_analysis são do cartão: a autorização é decidida na mesma requisição, mas pode parar na análise de fraude antes de virar paid ou failed. No PIX a cobrança vai direto de pending para o desfecho.

partially_refunded é estado próprio, e não um refunded com asterisco: tratar uma venda devolvida pela metade como estornada faria seu relatório descontar o valor inteiro.

chargedback é definitivo: o dinheiro voltou pelo caminho da bandeira, e nem cancelamento nem estorno são mais possíveis.

Available options:
pending,
processing,
in_analysis,
paid,
expired,
canceled,
partially_refunded,
refunded,
failed,
chargedback
​
payment_method
enum<string>
required

O meio pelo qual esta cobrança foi criada. Omitir o campo na criação continua significando pix - é o que toda integração que existe hoje espera, e mudar isso as quebraria todas de uma vez.

Available options:
pix,
credit_card,
boleto
​
amount
integer<int64>
required

O que o comprador paga, em centavos inteiros.

Cuidado com a assimetria, porque ela é a pegadinha desta API: no POST você manda o PREÇO DO PRODUTO, e aqui volta o TOTAL. No Pix e no cartão à vista os dois são iguais; no cartão parcelado este é maior, porque inclui o juro que o comprador pagou.

O preço do produto, de volta, é amount - interest.

​
currency
string
required
Allowed value: "BRL"
​
platform_fee
integer<int64>
required

Nossa taxa, em centavos inteiros. Congelada na criação: reflete o contrato que valia quando a venda aconteceu, não o de hoje.

Ela incide sobre o preço do produto (amount - interest), e não sobre o total pago. É o que faz parcelar não custar nada a você - ver net_amount.

​
net_amount
integer<int64>
required

O que fica com o vendedor, em centavos inteiros.

Não é amount - platform_fee. Essa conta dá um número maior, e a diferença é o JURO do parcelamento: ele está dentro do amount porque o comprador o pagou, mas não é receita de ninguém aqui - atravessa até o arranjo de pagamento.

A identidade que fecha, e que o banco confere em toda cobrança:

No Pix e no cartão à vista o juro é zero, e aí amount - platform_fee fecha.

​
refunded_amount
integer<int64>
required

Total já devolvido ao comprador, em centavos inteiros. Acumulado entre estornos parciais.

​
description
string | null
required
​
reference
string | null
required
​
metadata
object
required

O que você enviou na criação. Sempre um objeto, {} quando não houve nada - nunca null, para o seu código não ter dois casos a tratar.

Example:
​
customer
object | null
required

null na cobrança que não tem comprador vinculado. A chave em si nunca falta.

​
pix
object
required

Presente em toda cobrança, inclusive nas de cartão - onde os três campos vêm null. Um objeto sempre presente evita o if (charge.pix) antes de cada leitura.

​
card
object
required

Presente em toda cobrança, inclusive nas de PIX - onde os campos vêm null. Mesma regra do pix acima, e pelo mesmo motivo.

O que não está aqui, e não vai estar: os seis primeiros dígitos, o código de retorno da adquirente e a nota do antifraude. Os dois primeiros são diagnóstico nosso; a nota numa resposta pública seria um oráculo de risco para quem testa cartão em lote. O código de recusa sai numa recusa, em error.details.decline_code, onde quem lê é o seu servidor.

​
boleto
object
required

Presente em toda cobrança, inclusive nas de PIX e de cartão - onde os campos vêm null. Mesma regra do pix e do card, e pelo mesmo motivo.

Boleto é oferecido apenas a lojas em conta de split na Pagar.me. Numa loja fora desse arranjo, POST /v1/charges com payment_method: boleto responde 422 com boleto_not_available.

​
created_at
string<date-time> | null
required
​
paid_at
string<date-time> | null
required
​
expired_at
string<date-time> | null
required
​
refunded_at
string<date-time> | null
required