Criar cobrança
Cria uma cobrança PIX com split entre o vendedor e a plataforma, e devolve o payload copia-e-cola.
10000. Decimais são
recusados com 422, e o porquê está em Valores em centavos.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.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
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
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.
255Body
Valor total da cobrança, em centavos inteiros. R$ 100,00 =
10000. Um decimal aqui é recusado com 422.
x >= 1Show child attributes
Show child attributes
Aparece para o comprador na tela de pagamento.
255Sua 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.
120Até 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"}.
Show child attributes
Show child attributes
{ "carrinho": "cart_88f21", "campanha": "black-friday" }
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.
60 <= x <= 604800O 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.
"189.45.12.7"
Opcional. Sem itens, montamos um a partir de description.
100Show child attributes
Show child attributes
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.
"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 POST /v1/charges só cria PIX, então toda cobrança criada por
esta API nasce pix. credit_card aparece nos webhooks e
no GET: as vendas de cartão feitas pelo checkout ou por link
de pagamento são suas também, e chegam pelos mesmos eventos.
pix, credit_card Valor cobrado, em centavos inteiros.
"BRL"Nossa taxa, em centavos inteiros. Congelada na criação: reflete o contrato que valia quando a venda aconteceu, não o de hoje.
O que fica com o vendedor, em centavos inteiros: amount menos
a nossa taxa e menos a taxa do meio de pagamento, que é
descontada direto do recebimento dele. Por isso
amount - platform_fee dá um número MAIOR que este.
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