Criar cobrança Pix

​

Cria uma cobrança Pix com QR Code (texto copia e cola e imagem). Requer escopo DEPOSIT.

Merchant: vincule a um merchant existente com merchantId, ou crie/atualize um na hora com o objeto merchant (identificado pelo seu externalId). Não envie os dois.

Splits: para dividir o valor automaticamente entre recebedores, inclua merchant.recipients (até 10 recebedores, por percentual em basis points ou valor fixo).

Envie o cabeçalho Idempotency-Key para evitar cobranças duplicadas em retentativas.

Headers
  • Idempotency-Key
    Type: stringFormat: uuid

    Chave de idempotência (recomendado: UUID por intenção). Reenviar a mesma chave retorna o mesmo resultado sem duplicar a operação.

Body·
required
application/json

Para o merchant: envie merchantId (existente) ou o objeto merchant (cria/atualiza pelo externalId) — nunca os dois juntos. A mesma regra vale para resellerId vs reseller. As regras de split vão em merchant.recipients.

  • amount
    Type: integer
    min:  
    1
    required

    Valor em centavos.

  • callbackUrl
    Type: stringFormat: uri
    required

    URL que receberá o webhook de confirmação.

  • expiresIn
    Type: integer

    Validade da cobrança em segundos (padrão 600).

  • generatedDocument
    Type: string

    CPF/CNPJ do pagador (opcional).

  • generatedEmail
    Type: stringFormat: email

    E-mail do pagador (opcional).

  • generatedName
    Type: string
    max length:  
    100

    Nome do pagador (opcional). Apenas letras e espaços.

  • merchant
    Type: object ·

    Cria ou atualiza um merchant (identificado pelo externalId) no momento da cobrança. Inclua recipients para definir as regras de split aplicadas a este pagamento.

  • merchantId
    Type: stringFormat: uuid

    ID de um merchant já existente. Use no lugar de merchant.

  • reseller
    Type: object ·
  • resellerId
    Type: stringFormat: uuid

    ID de um reseller já existente. Use no lugar de reseller.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/v1/pix
curl https://api.betpaympix.com/v1/pix \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "amount": 1990,
  "callbackUrl": "https://sualoja.com/webhooks/payerpix",
  "merchant": {
    "externalId": "loja-001",
    "name": "Minha Loja",
    "commissionBasisPoints": 0,
    "recipients": [
      {
        "recipientType": "USER",
        "recipientId": "",
        "splitValue": 1,
        "splitType": "PERCENTAGE",
        "isRemainder": false
      }
    ]
  },
  "merchantId": "b3f1c2a4-1111-2222-3333-444455556666",
  "reseller": {
    "externalUserId": "rs_001",
    "username": "joao.parceiro",
    "commissionPercentage": 5
  },
  "resellerId": "",
  "generatedName": "Cliente Final",
  "generatedEmail": "",
  "generatedDocument": "",
  "expiresIn": 600
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "externalId": "string",
  "status": "PENDING",
  "amount": 1990,
  "type": "DEPOSIT",
  "qrCodeText": "string",
  "qrCodeBase64": "string",
  "qrCodeUrl": "string",
  "serviceFeeCharged": 0,
  "endToEndId": "string",
  "createdAt": "2026-06-05T07:03:46.090Z",
  "paidAt": "2026-06-05T07:03:46.090Z"
}

Cobrança criada

PayerPix