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

flowchart TD
    U["👤 Usuário (conta)"] -->|possui vários| M1["🏪 Merchant A"]
    U -->|possui vários| M2["🏪 Merchant B"]
    M1 --> S1["📜 Regra de Split"]
    S1 -->|divide a receita| P1["👤 Recebedor (USER)"]
    S1 -->|divide a receita| P2["🏪 Recebedor (MERCHANT)"]

    classDef u fill:#eaf1fb,stroke:#1f5fb0,color:#0b2a4a;
    classDef m fill:#e8f6f3,stroke:#13796d,color:#0b3b34;
    class U u; class M1,M2,S1,P1,P2 m;

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 pela rota de criação de 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: o merchant deve ser criado antes, pela sua rota própria. 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.

Criar um merchant

A criação é feita pela rota própria de merchants (escopo ADMIN):

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

A resposta inclui o id do merchant — guarde‑o para vincular cobranças depois.

Não crie merchants pela rota de cobrança. O fluxo correto é: criar o merchant aqui e, na cobrança Pix, apenas referenciar o merchantId.

Listar meus merchants

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

Saldo de um merchant

curl https://api.betpaympix.com/v1/merchants/{id}/wallet \
  -H "Authorization: Bearer PP_seu_token"
# { "balanceAvailable": 154200, "balanceBlocked": 0, "total": 154200 }

Extrato de um merchant

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

Atualizar um merchant (admin)

curl -X PATCH https://api.betpaympix.com/v1/admin/merchants/{id} \
  -H "Authorization: Bearer PP_seu_token" \
  -H "Content-Type: application/json" \
  -d '{ "commissionBasisPoints": 750, "isActive": true }'

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": ... }

Saldo de um merchant

curl https://api.betpaympix.com/v1/merchants/{id}/wallet \
  -H "Authorization: Bearer PP_seu_token"
# { "balanceAvailable": 154200, "balanceBlocked": 0, "total": 154200 }

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:

flowchart TD
    C["🍫 Cliente paga R$ 20,00
(Pix confirmado)"] --> M["🏪 Mercado do Bairro
Merchant"]
    M --> R{"📜 Regra de Split
(ativa neste merchant)"}
    R -->|"50%"| A["🧑 Adolescente que vendeu
recebedor: USER
R$ 10,00"]
    R -->|"resto (50%)"| D["🏪 Caixa do mercado
recebedor: MERCHANT · isRemainder
R$ 10,00"]

    classDef money fill:#e8f6f3,stroke:#13796d,color:#0b3b34;
    classDef store fill:#eaf1fb,stroke:#1f5fb0,color:#0b2a4a;
    class A,D money; class M,R store;

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 da API

Basis points: splitValue em percentual é medido 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 isRemainder leva exatamente o que sobrou.

Como os dados se organizam

flowchart LR
    MM["🏪 Merchant"] --> SR["📜 SplitRule
(uma ativa por merchant)"]
    SR --> R1["👤 SplitRecipient
vendedor · 50%"]
    SR --> R2["👤 SplitRecipient
indicador · 10%"]
    SR --> R3["🏪 SplitRecipient
mercado · resto"]
    PG["💸 Pagamento confirmado"] --> PS["🧾 PaymentSplit (por venda)
quanto cada um recebeu + status"]
    SR -.aplica.-> PS

    classDef a fill:#eef0f6,stroke:#5b658c,color:#16203a;
    class MM,SR,R1,R2,R3,PG,PS a;

• SplitRule — a "combinação" do merchant (uma regra ativa por vez).
• SplitRecipient — cada participante da combinação (percentual ou valor fixo).
• PaymentSplit — o registro do que de fato cada um recebeu em cada venda, com status (PENDING → COMPLETED).

Criar a regra (API)

curl -X POST https://api.betpaympix.com/v1/admin/merchants/{id}/split-rules \
  -H "Authorization: Bearer PP_seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      { "recipientType": "USER",     "recipientId": "uuid-vendedor",  "splitValue": 5000, "splitType": "PERCENTAGE" },
      { "recipientType": "USER",     "recipientId": "uuid-indicador", "splitValue": 1000, "splitType": "PERCENTAGE" },
      { "recipientType": "MERCHANT", "recipientId": "uuid-merchant",  "splitValue": 0,    "splitType": "PERCENTAGE", "isRemainder": true }
    ]
  }'

A partir daí, toda venda desse merchant é dividida automaticamente conforme a regra — sem repasse manual.

Consultar

# Regras ativas do merchant
curl https://api.betpaympix.com/v1/admin/merchants/{id}/split-rules \
  -H "Authorization: Bearer PP_seu_token"

# O que foi distribuído em cada pagamento
curl https://api.betpaympix.com/v1/admin/merchants/{id}/splits \
  -H "Authorization: Bearer PP_seu_token"

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