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.
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.

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

Valor total da cobrança, em centavos inteiros. R$ 100,00 = 10000. Um decimal aqui é recusado com 422.

Required range: x >= 1
​
customer
object
required
​
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
​
expires_in
integer | null
default:3600

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

Required range: 60 <= x <= 604800
​
items
object[] | null

Opcional. Sem itens, montamos um a partir de description.

Maximum array length: 100

Response

Cobrança criada e aguardando pagamento.

​
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. Todos os estados exceto pending são terminais - exceto os que ainda admitem estorno.

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.

Available options:
pending,
paid,
expired,
canceled,
partially_refunded,
refunded,
failed
​
payment_method
enum<string>
required
Available options:
pix
​
amount
integer<int64>
required

Valor cobrado, em centavos inteiros.

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

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

​
net_amount
integer<int64>

O que fica com o vendedor, em centavos inteiros (amount - platform_fee).

​
refunded_amount
integer<int64>

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

​
description
string | null
​
reference
string | null
​
customer
object

O comprador, como devolvemos.

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