Cobranças Pix

Crie uma cobrança Pix com QR Code (escopo DEPOSIT). Para o merchant, use o merchantId de um já existente ou o objeto merchant, que cria/atualiza pelo externalId e ainda aceita regras de split em recipients.

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

Campo	Obrigatório	Descrição
`amount`	sim	Valor em centavos
`callbackUrl`	sim	URL do webhook de confirmação
`merchant`	não	Cria/atualiza um merchant inline: `externalId`, `name`, `commissionBasisPoints` e `recipients` (splits)
`merchantId`	não	Vincula a um merchant existente (use no lugar de `merchant`)
`reseller` / `resellerId`	não	Parceiro/indicador inline ou já existente
`generatedName` / `generatedDocument` / `generatedEmail`	não	Dados do pagador
`expiresIn`	não	Validade em segundos (padrão 600)

Envie merchant ou merchantId, nunca os dois (mesma regra para reseller/resellerId). Para evitar cobranças duplicadas em retentativas, envie o cabeçalho Idempotency-Key.

Criar o merchant (e o split) na cobrança

Para abrir um merchant na hora e já dividir o valor, mande o objeto merchant com recipients:

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-0002" \
  -d '{
    "amount": 2000,
    "callbackUrl": "https://sualoja.com/webhooks/payerpix",
    "merchant": {
      "externalId": "loja-001",
      "name": "Minha Loja",
      "recipients": [
        { "recipientType": "USER", "recipientId": "<UUID_DO_VENDEDOR>", "splitValue": 5000 },
        { "recipientType": "MERCHANT", "recipientId": "<UUID_DO_MERCHANT>", "isRemainder": true, "splitValue": 1 }
      ]
    }
  }'

splitValue em PERCENTAGE é basis points (5000 = 50%). Detalhes em Splits.

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.

Merchants

Saldos e Saques