{
"object": "charge",
"id": "ch_01k1y6r6m6q2x0p3d9v4t7c8n2",
"amount": 123,
"currency": "BRL",
"platform_fee": 123,
"net_amount": 123,
"refunded_amount": 123,
"description": "<string>",
"reference": "<string>",
"metadata": {
"carrinho": "cart_88f21",
"campanha": "black-friday"
},
"customer": {
"name": "<string>",
"email": "<string>",
"document": "111.***.***-35"
},
"pix": {
"qr_code": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"end_to_end_id": "<string>"
},
"card": {
"last_four": "<string>",
"holder_name": "<string>",
"installments": 123,
"interest": 123,
"three_d_secure": {
"transaction_id": "<string>"
},
"authorized_at": "2023-11-07T05:31:56Z"
},
"boleto": {
"line": "34191.79001 01043.510047 91020.150008 1 92230000050000",
"barcode": "<string>",
"url": "<string>",
"pdf": "<string>",
"nosso_numero": "<string>",
"due_at": "2023-11-07T05:31:56Z"
},
"created_at": "2023-11-07T05:31:56Z",
"paid_at": "2023-11-07T05:31:56Z",
"expired_at": "2023-11-07T05:31:56Z",
"refunded_at": "2023-11-07T05:31:56Z"
}Cobrança
Campo a campo do objeto que toda rota de cobrança devolve — e que chega nos webhooks.
null, nunca ausentes. Marcar
como opcional o que nunca falta obrigaria você a testar a existência de uma chave que sempre
existe.Isso vale para pix, card e boleto também: numa cobrança de cartão os objetos pix e
boleto vêm com os membros nulos. O seu código lê charge.card.brand sem checar se card
existe.Qual bloco ler
payment_method diz qual dos três está preenchido. Os outros dois vêm com todos os membros null.
payment_method | O bloco com dados | O campo que o comprador usa |
|---|---|---|
pix | pix | pix.qr_code — o copia-e-cola |
credit_card | card | nenhum, já pagou |
boleto | boleto | boleto.line — a linha digitável |
boleto.line nulo significa que o documento não existe. Quando o provedor recusa a
emissão, a cobrança nasce failed e não há o que pagar. Ver
Cobrança por boleto.O que NÃO está aqui
E não vai estar, de propósito:- Os seis primeiros dígitos do cartão (o BIN). Somados aos quatro últimos, são material de correlação que você não precisa.
- O código de retorno da adquirente. Ele sai numa recusa, em
error.details.decline_code, onde quem lê é o seu servidor. - A nota do antifraude. Numa resposta pública ela seria um oráculo de risco para quem testa cartão em lote.
- As referências da Pagar.me. O
id(ch_…) é o nosso, e é o único que você precisa.
Os quatro valores, e a pegadinha entre eles
| Campo | O que é |
|---|---|
amount | O que o comprador paga. No parcelado, já inclui o juro |
card.interest | O juro do parcelamento, pago por ele. 0 no Pix e à vista |
platform_fee | A nossa taxa, calculada sobre o preço do produto |
net_amount | O que sobra para você |
net_amount não é amount − platform_fee. Essa conta dá um número maior, e a diferença é o
juro: 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:amount = net_amount + platform_fee + interest + co-produção
amount − platform_fee fecha. É por isso que quem
integrou só Pix nunca tropeçou nisso.POST você manda o preço do produto, e aqui
volta o total. O preço do produto, de volta, é amount − card.interest. Ver
Taxas e liquidação.
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.Veja também
Ciclo de vida
status e as transições possíveis.Taxas e liquidação
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.
"charge"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.
"ch_01k1y6r6m6q2x0p3d9v4t7c8n2"
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.
pending, processing, in_analysis, paid, expired, canceled, partially_refunded, refunded, failed, chargedback 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.
pix, credit_card, boleto 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.
"BRL"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.
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:
amount = net_amount + platform_fee + interest + co-produção
No Pix e no cartão à vista o juro é zero, e aí
amount - platform_fee fecha.
Total já devolvido ao comprador, em centavos inteiros. Acumulado entre estornos parciais.
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.
Show child attributes
Show child attributes
{
"carrinho": "cart_88f21",
"campanha": "black-friday"
}
null na cobrança que não tem comprador vinculado. A chave em
si nunca falta.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes