Skip to main content
Cria uma cobrança Pix sem produtos vinculados e devolve o QR Code e o Copia e Cola para o cliente pagar. Método: POST /api/v1/transactions Autenticação: Obrigatória — inclua o header Authorization: Bearer sk_live_sua_api_key.
Para vender produtos do catálogo, use POST /api/v1/orders em vez deste endpoint.

​
Antes de começar

Cadastre a URL do seu servidor nas configurações de API do painel e marque o evento payment.paid. A confirmação do pagamento chega por webhook, não na resposta desta chamada. Sem isso, você cria a cobrança mas não fica sabendo quando o cliente paga.

​
Parâmetros do corpo

​
string
required
Use PIX_IN.
​
number
required
Valor em reais, com decimais. Mínimo de 1.00. Exemplo: 50 = R$50,00 e 19.9 = R$19,90.
​
string
Descrição da cobrança.
​
object
Dados de quem vai pagar, com name, email e document (CPF ou CNPJ).
​
boolean
default:"true"
Envie false para receber somente o Copia e Cola, sem a imagem do QR Code.

​
Exemplo de requisição

O corpo não leva URL de webhook: a cobrança usa a URL já cadastrada na sua api_key.
A resposta traz o QR Code e o status PENDING. O aviso de que o cliente pagou chega depois, no seu webhook — veja Receber o aviso de pagamento.

​
Resposta

​
Valores e taxa

​
number
Valor da venda, em reais.
​
number
Taxa da plataforma sobre a venda.
​
number
O que entra na sua carteira.
​
boolean
true quando a loja repassa a taxa ao cliente. Nesse caso o cliente paga amount + feeAmount e você recebe o valor cheio.

​
Confirmação pendente

Se a API responder 502 com code: "PaymentPendingConfirmation", a cobrança pode ter sido criada. Consulte a transação pelo id antes de tentar de novo, para não cobrar o cliente duas vezes. O campo retryable indica se é seguro repetir.

​
Confirmar o pagamento

O Pix é confirmado em segundos, mas a confirmação chega ao seu sistema pelo webhook, não na resposta desta chamada. A cobrança nasce como PENDING.
Nunca libere o produto com base no que o navegador do cliente informa. Espere o webhook ou consulte a cobrança pela API.

​
Receber o aviso de pagamento

Com a URL cadastrada e o evento payment.paid marcado, você recebe no seu servidor:
O data.id é o mesmo id que esta chamada devolveu, então use-o para achar a cobrança no seu banco. O externalReference serve para conciliação.
1

Valide a assinatura

Confira o header X-Webhook-Signature antes de confiar no conteúdo. Veja Validar a assinatura.
2

Responda 2xx rápido

O tempo limite é de 15 segundos. Se o processamento for demorado, enfileire e responda antes.
3

Trate como idempotente

Use requestId como chave para não processar a mesma entrega duas vezes.
Vale assinar também payment.failed e payment.pix.expired, para liberar o carrinho quando a cobrança não for paga. A lista completa está em Eventos.

​
Sem webhook

Dá para consultar GET /api/v1/transactions/:id e verificar se o status virou COMPLETED. Serve para conciliação, mas não substitui o webhook: consultar em laço gasta requisição do seu limite e atrasa a entrega ao cliente.