Introdução

A PayerPix é uma infraestrutura de pagamentos Pix com suporte a múltiplos merchants sob uma mesma conta: cada merchant tem saldo e extrato isolados, e a receita pode ser dividida automaticamente entre vários recebedores (splits).

Conceitos

• Usuário (conta de API): dono das credenciais. Pode possuir vários merchants.
• Merchant: unidade de recebimento (loja, marca, cliente). Tem balanceAvailable e balanceBlocked próprios.
• Cobrança Pix: um pagamento de entrada (DEPOSIT) com QR Code. Pode ser vinculada a um merchant.
• Split: regra que distribui a receita de um merchant entre recebedores (usuários ou merchants).

Um usuário tem vários merchants (1→N). Cada merchant pode dividir sua receita entre vários recebedores via splits — é onde a relação vira muitos‑para‑muitos no fluxo do dinheiro.

Base e convenções

Fluxo típico

1. Crie o merchant (POST /v1/merchants) — ver Merchants.
2. Gere a cobrança Pix referenciando o merchant pelo campo merchantId.
3. Receba o webhook de confirmação na sua callbackUrl.
4. Concilie e repasse: consulte os saldos por merchant e use splits para repasses automáticos.

Importante: crie o merchant antes (POST /v1/merchants). Na geração de cobrança você apenas informa o merchantId de um merchant já existente.

Autenticação

Todas as requisições autenticadas usam um API Token no cabeçalho Authorization:

Authorization: Bearer PP_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• O token tem o prefixo PP_.
• É exibido uma única vez na criação — guarde com segurança. No servidor é armazenado apenas como hash.
• Cada token carrega escopos (permissões).

Escopos

Erros de autenticação

Exemplo

curl https://api.betpaympix.com/v1/user/balance \
  -H "Authorization: Bearer PP_seu_token"

Merchants

Um merchant é uma unidade de recebimento com saldo isolado. Um usuário pode ter vários. Pela API você cria um merchant e consulta o seu extrato.

Criar um merchant

curl -X POST https://api.betpaympix.com/v1/merchants \
  -H "Authorization: Bearer PP_seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loja Exemplo",
    "externalId": "loja-001",
    "commissionBasisPoints": 500
  }'

Resposta (201):

{
  "id": "b3f1c2a4-1111-2222-3333-444455556666",
  "name": "Loja Exemplo",
  "externalId": "loja-001",
  "isActive": true,
  "balanceAvailable": 0,
  "balanceBlocked": 0,
  "commissionBasisPoints": 500,
  "createdAt": "2026-06-03T12:00:00Z"
}

Guarde o id — ele é usado para vincular cobranças (merchantId) e consultar o extrato.

Extrato do merchant

curl "https://api.betpaympix.com/v1/merchants/{id}/transactions?status=COMPLETED" \
  -H "Authorization: Bearer PP_seu_token"

Filtros opcionais: status, dateFrom, dateTo. Retorna as transações daquele merchant (cobranças e movimentações), com id, amount (centavos), status, type, datas e endToEndId.

A posse é validada no servidor: você só acessa merchants da sua própria conta.

Cobranças Pix

Crie uma cobrança Pix com QR Code (escopo DEPOSIT). Para vincular a um merchant, informe apenas o merchantId de um merchant já existente.

Criar cobrança

curl -X POST https://api.betpaympix.com/v1/pix \
  -H "Authorization: Bearer PP_seu_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-2024-0001" \
  -d '{
    "amount": 1990,
    "callbackUrl": "https://sualoja.com/webhooks/payerpix",
    "merchantId": "b3f1c2a4-1111-2222-3333-444455556666",
    "generatedName": "Cliente Final",
    "generatedDocument": "12345678909",
    "expiresIn": 600
  }'

Resposta (201):

{
  "id": "0e9c...uuid",
  "status": "PENDING",
  "amount": 1990,
  "type": "DEPOSIT",
  "qrCodeText": "00020126...br.gov.bcb.pix...6304ABCD",
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgo...",
  "qrCodeUrl": "https://api.betpaympix.com/v1/pix/qrcode/0e9c...uuid",
  "createdAt": "2026-06-03T12:00:00Z",
  "paidAt": null
}

Campos do corpo

Para evitar cobranças duplicadas em retentativas, envie o cabeçalho Idempotency-Key.

Consultar status

curl "https://api.betpaympix.com/v1/pix?id=0e9c...uuid" \
  -H "Authorization: Bearer PP_seu_token"

QR Code (imagem PNG)

GET https://api.betpaympix.com/v1/pix/qrcode/{id}

Retorna image/png (endpoint público). Útil para exibir direto no checkout.

Saldos e Saques

Saldo do usuário

curl https://api.betpaympix.com/v1/user/balance \
  -H "Authorization: Bearer PP_seu_token"
# { "balanceAvailable": ..., "balanceBlocked": ..., "total": ... }

Saque do usuário (Pix)

curl -X POST https://api.betpaympix.com/v1/withdraw \
  -H "Authorization: Bearer PP_seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "pixKey": "12345678909",
    "pixType": "CPF",
    "description": "Saque",
    "callbackUrl": "https://sualoja.com/webhooks/payerpix"
  }'

Tipos de chave Pix (pixType)

CPF · CNPJ · EMAIL · PHONE · EVP

Status de saque

PENDING · ANALYSIS · COMPLETED · FAILED · CANCELED

Divisão de receita (Splits)

O split divide automaticamente o dinheiro de cada pagamento entre vários recebedores. Em vez de receber tudo e repassar na mão, a PayerPix já entrega a parte certa para cada um, no momento da venda.

A ideia, com um exemplo do dia a dia 🍫

Imagine o mercado do bairro (esse é o merchant).

O dono compra caixas de bombom e entrega uma caixa para cada adolescente da vizinhança sair vendendo. O combinado é simples: quem vender ganha 50% do valor da venda, e os outros 50% voltam para o mercado.

Quando um cliente compra uma caixa por R$ 20,00, o dinheiro se divide sozinho:

Cada adolescente é um recebedor da regra. Dá para ter vários (até 10 por regra) — por exemplo, ainda separar uma fatia para quem indicou o vendedor.

Do exemplo para os conceitos

Basis points: percentuais são medidos em basis points — 10000 = 100%, 5000 = 50%, 250 = 2,5%. Isso evita arredondamentos.

Exemplo com 3 recebedores

Venda de R$ 20,00 (2000 centavos):

A soma sempre fecha 100%: o recebedor marcado como remainder leva exatamente o que sobrou.

Como configurar

As regras de split de cada merchant são definidas no painel da PayerPix (ou com o seu gerente de conta). Uma vez configurada a regra, toda venda daquele merchant é dividida automaticamente — sem nenhum repasse manual e sem precisar mudar suas integrações de cobrança.

Webhooks

Ao criar uma cobrança ou saque, informe uma callbackUrl. Quando o status mudar (ex.: pagamento confirmado), a PayerPix faz um POST para essa URL.

Payload

{
  "eventType": "payment.completed",
  "payload": {
    "id": "0e9c...uuid",
    "externalId": "TX-9931",
    "status": "COMPLETED",
    "amount": 1990,
    "paidAt": "2026-06-03T12:03:11Z",
    "payerName": "Maria Souza",
    "payerDocument": "***.456.789-**",
    "endToEndId": "E1234567890..."
  },
  "deliveryAttempt": 1,
  "timestamp": "2026-06-03T12:03:12Z"
}

Boas práticas

1. Responda 2xx rapidamente e processe de forma assíncrona.
2. Trate idempotência pelo payload.id (pode haver reentrega).
3. Confirme o estado consultando GET /v1/pix?id=... antes de liberar o produto/serviço.
4. Proteja a callbackUrl com um segredo/rota não‑adivinhável.

Status possíveis