Cobranças Pix

Gerar, consultar, cancelar cobranças Pix In e receber confirmações via webhook.

Ciclo de vida

PENDING → CONFIRMED

PENDING → EXPIRED

PENDING → CANCELLED

Cobranças iniciam como PENDING. Ao ser pago, o adquirente notifica via webhook e o status muda para CONFIRMED. Cobranças não pagas após expires_in segundos tornam-se EXPIRED. É possível cancelar manualmente uma cobrança PENDING antes do vencimento.

Criar cobrança — curl

# Cobrança simples
curl -s -X POST https://api.brpix.app/v1/pix/charges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "49.90",
    "description": "Pedido #9872",
    "expires_in": 3600,
    "external_id": "ORD-9872"
  }'

# Resposta 201
{
  "id": "pix_c_a1b2c3d4",
  "status": "PENDING",
  "amount": "49.90000",
  "currency": "BRL",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "expires_at": "2026-10-10T15:00:00-03:00",
  "created_at": "2026-10-10T14:00:00-03:00"
}

Criar cobrança com split — curl

# Split: 90% fica na conta, 10% vai para parceiro
curl -s -X POST https://api.brpix.app/v1/pix/charges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "100.00",
    "description": "Venda com comissão",
    "split": [
      { "recipient_org_id": "org_uuid_parceiro", "percentage": "10.00000" }
    ]
  }'

Split: a soma dos percentuais do array split deve ser ≤ 100%. O percentual restante fica na conta geradora. Aceita até N níveis. Apenas org_ids com KYC aprovado podem ser destinatários de split.

Criar cobrança com split — Node.js

import crypto from 'crypto'

const res = await fetch('https://api.brpix.app/v1/pix/charges', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    amount: '100.00',
    description: 'Venda #1234',
    split: [
      { recipient_org_id: 'org_abc123', percentage: '15.00000' },
    ],
  }),
})

const charge = await res.json()
console.log(charge.qr_code) // exibir QR Code ao cliente

Webhook de confirmação

Quando o pagamento é confirmado, o BRPix envia um webhook para a URL configurada no painel em Configurações → Webhooks. Configure o endpoint que receberá as notificações.

Payload do webhook

{
  "event": "pix_in.confirmed",
  "charge_id": "pix_c_a1b2c3d4",
  "amount": "49.90000",
  "end_to_end_id": "E12345678202610101400abcdef012",
  "confirmed_at": "2026-10-10T14:07:23-03:00",
  "external_id": "ORD-9872"
}

Idempotência no recebimento: seu endpoint deve ser idempotente — o webhook pode ser entregue mais de uma vez em caso de falha na resposta. Use o charge_id ou end_to_end_id para verificar se já processou.

Consultar cobrança

curl -s https://api.brpix.app/v1/pix/charges/pix_c_a1b2c3d4 \
  -H "Authorization: Bearer <access_token>"

Cancelar cobrança

curl -s -X DELETE https://api.brpix.app/v1/pix/charges/pix_c_a1b2c3d4 \
  -H "Authorization: Bearer <access_token>"

# Resposta 200
{ "cancelled": true }