Receber por PIX

Criar a cobrança

POST /integration/v1/charges

{
  "amount": "100.00",
  "method": "pix",
  "description": "Pedido 1234",
  "payerName": "Fulano de Tal",
  "payerDocument": "123.456.789-11",
  "payerEmail": "fulano@exemplo.com.br",
  "callbackUrl": "https://loja.exemplo.com.br/webhooks/pedido/1234"
}

Só amount e method são obrigatórios. O documento do pagador pode vir com ou sem máscara — não validamos dígito verificador, recebemos o que você tem.

A resposta

{
  "success": true,
  "status": 201,
  "body": {
    "id": "3f7c2a9e-8b14-4d6a-9c55-1e2f3a4b5c6d",
    "method": "pix",
    "status": "pending",
    "statusLabel": "Aguardando pagamento",
    "amount": "100.00",
    "netAmount": "97.50",
    "expiresAt": "2026-08-20T15:03:11Z",
    "pixPayload": "00020126580014BR.GOV.BCB.PIX...",
    "qrCodeImage": "data:image/png;base64,iVBORw0KG...",
    "checkoutPath": "/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
  },
  "meta": { }
}

pixPayload é o "copia e cola" — mostre-o como texto copiável. qrCodeImage é o mesmo conteúdo já renderizado, para quem não quer gerar o QR do próprio lado.

netAmount é o que entra no saldo da conta quando a cobrança for paga. amount − netAmount é o total de taxas retidas.

checkoutPath é o caminho da página de pagamento hospedada, relativo à raiz do domínio de checkout do seu provedor — use-o se preferir mandar o pagador para uma página pronta em vez de renderizar o QR você mesmo.

Os estados

status	Significa
pending	criada, aguardando pagamento
paid	paga — o saldo já entrou
expired	passou de expiresAt sem pagamento
canceled	cancelada antes do pagamento
refunded	devolvida

Saber que foi paga

Não consulte em laço. Assine o evento charge.paid — ver Webhooks.

A callbackUrl que você mandou na criação recebe os eventos daquela cobrança, sem cadastro prévio. É o caminho mais curto se você tem um endpoint por pedido.

Se você também tem um endereço cadastrado na conta, receberá duas entregas por evento, com X-Webhook-Id diferentes. É a combinação que se escolhe de propósito — para deduplicar, use o id da cobrança no corpo.

Consultar uma cobrança

GET /integration/v1/charges/{id}

Útil depois de um timeout na criação, para descobrir se ela existe antes de tentar de novo.

:::note Criar cobrança não move dinheiro O saldo só é tocado quando o pagamento é confirmado. Uma cobrança pending é uma expectativa, e uma cobrança expired nunca custou nada. :::

Devolver

A devolução de PIX tem regras próprias do arranjo e não usa o endpoint de devolução de cartão. Fale com o seu provedor.