PayerPix

https://payerpix.apidocumentation.com
Admin
PayerPix is a Pix payment infrastructure API supporting multiple merchants under a single account,...
Tokens:16,048
Snippets:147
Trust Score:6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Payment Status Webhook Request Example

Source: https://payerpix.apidocumentation.com/api-reference/tag/webhooks/webhook/post/paymentstatus

Example JSON payload sent to the callback URL when a payment status event occurs.

```json
{
  "eventType": "payment.completed",
  "deliveryAttempt": 1,
  "timestamp": "",
  "payload": {
    "id": "",
    "externalId": "TX-9931",
    "status": "PENDING",
    "amount": 1990,
    "paidAt": "",
    "payerName": "Maria Souza",
    "payerDocument": "***.456.789-**",
    "endToEndId": "E1234567890...",
    "merchantId": ""
  }
}
```

--------------------------------

### GET /v1/pix

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix

Lista as cobranças Pix existentes.

```APIDOC
## GET /v1/pix

### Description
Lista as cobranças Pix registradas no sistema.

### Method
GET

### Endpoint
/v1/pix
```

--------------------------------

### GET /v1/user/summary

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio

Obtém métricas e resumo da conta do usuário.

```APIDOC
## GET /v1/user/summary

### Description
Recupera métricas e um resumo geral da conta do usuário autenticado.

### Method
GET

### Endpoint
/v1/user/summary
```

--------------------------------

### GET /v1/user

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio

Recupera as informações do usuário autenticado.

```APIDOC
## GET /v1/user

### Description
Recupera os dados do perfil do usuário autenticado.

### Method
GET

### Endpoint
/v1/user
```

--------------------------------

### GET /v1/user/balance

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/balance

Recupera o saldo do usuário autenticado.

```APIDOC
## GET /v1/user/balance

### Description
Retorna o saldo disponível, saldo bloqueado e o total do usuário autenticado.

### Method
GET

### Endpoint
https://api.betpaympix.com/v1/user/balance

### Response
#### Success Response (200)
- **balanceAvailable** (number) - Saldo disponível
- **balanceBlocked** (number) - Saldo bloqueado
- **total** (number) - Saldo total

#### Response Example
{
  "balanceAvailable": 154200,
  "balanceBlocked": 0,
  "total": 154200
}
```

--------------------------------

### Withdraw Status Webhook Request Example

Source: https://payerpix.apidocumentation.com/api-reference/tag/webhooks/webhook/post/withdrawstatus

Example JSON payload structure for the withdraw status webhook event.

```json
{
  "eventType": "payment.completed",
  "deliveryAttempt": 1,
  "timestamp": "",
  "payload": {
    "id": "",
    "status": "PENDING",
    "amount": 10000,
    "pixKey": "",
    "pixType": "CPF",
    "completedAt": ""
  }
}
```

--------------------------------

### GET /v1/pix/qrcode/{id}

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix

Recupera o QR Code de uma cobrança Pix específica.

```APIDOC
## GET /v1/pix/qrcode/{id}

### Description
Recupera o QR Code associado a uma cobrança Pix específica através do seu identificador.

### Method
GET

### Endpoint
/v1/pix/qrcode/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Identificador da cobrança Pix
```

--------------------------------

### GET /v1/pix

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/cobran%C3%A7as-pix

Consulta o status de uma cobrança Pix específica através do seu ID.

```APIDOC
## GET /v1/pix

### Description
Consulta o status de uma cobrança Pix existente.

### Method
GET

### Endpoint
https://api.betpaympix.com/v1/pix

### Parameters
#### Query Parameters
- **id** (string) - Obrigatório - ID da cobrança a ser consultada
```

--------------------------------

### Consultar saldo do usuário via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/balance

Exemplo de requisição GET para o endpoint de saldo utilizando autenticação Bearer.

```shell
curl https://api.betpaympix.com/v1/user/balance \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /v1/user/summary

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/summary

Retrieves aggregated metrics for the authenticated user, including total deposits, withdrawals, and net balance.

```APIDOC
## GET /v1/user/summary

### Description
Retrieves aggregated financial metrics for the authenticated user.

### Method
GET

### Endpoint
https://api.betpaympix.com/v1/user/summary

### Authentication
- **Authorization**: Bearer token required (prefix 'PP_')

### Response
#### Success Response (200)
- **totalIn** (number) - Total incoming amount
- **totalOut** (number) - Total outgoing amount
- **net** (number) - Net balance
- **depositsCount** (number) - Total number of deposits
- **withdrawsCount** (number) - Total number of withdrawals

#### Response Example
{
  "totalIn": 154200,
  "totalOut": 50000,
  "net": 104200,
  "depositsCount": 37,
  "withdrawsCount": 4
}
```

--------------------------------

### GET /v1/merchants

Source: https://payerpix.apidocumentation.com/api-reference/tag/merchants

Retrieves a list of all merchants.

```APIDOC
## GET /v1/merchants

### Description
Retrieves a list of all merchants.

### Method
GET

### Endpoint
/v1/merchants
```

--------------------------------

### GET /v1/pix/qrcode/{id}

Source: https://payerpix.apidocumentation.com/740c1ae5c5e4-merchants-openapi.json

Retrieves the PNG image of a Pix charge QR code.

```APIDOC
## GET /v1/pix/qrcode/{id}

### Description
Retorna a imagem PNG do QR Code da cobrança. Endpoint público.

### Method
GET

### Endpoint
/v1/pix/qrcode/{id}

### Parameters
#### Path Parameters
- **id** (uuid) - Required - The charge ID.

### Response
#### Success Response (200)
- **image** (binary) - PNG image of the QR code.
```

--------------------------------

### Consultar transações via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/transactions

Exemplo de requisição GET para listar transações, utilizando autenticação Bearer Token.

```shell
curl 'https://api.betpaympix.com/v1/user/transactions?status=PENDING&type=DEPOSIT&dateFrom=&dateTo=' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /v1/user

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user

Retrieves the account data for the currently authenticated user.

```APIDOC
## GET /v1/user

### Description
Retorna os dados da conta autenticada.

### Method
GET

### Endpoint
https://api.betpaympix.com/v1/user

### Authentication
- **Authorization**: Bearer Token (API Token com prefixo `PP_`)

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the account
- **username** (string) - Username of the account
- **email** (string) - Email address associated with the account
- **balanceAvailable** (number) - Available balance
- **balanceBlocked** (number) - Blocked balance
- **status** (string) - Current status of the account (e.g., ACTIVE)

#### Response Example
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "username": "string",
  "email": "hello@example.com",
  "balanceAvailable": 1,
  "balanceBlocked": 1,
  "status": "ACTIVE"
}
```

--------------------------------

### Listar merchants via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/merchants/get/v1/merchants

Exemplo de requisição GET para listar todos os merchants, utilizando autenticação Bearer.

```shell
curl https://api.betpaympix.com/v1/merchants \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /v1/user/transactions

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/transactions

Recupera uma lista de transações do usuário autenticado com base nos filtros fornecidos.

```APIDOC
## GET /v1/user/transactions

### Description
Recupera uma lista de transações do usuário autenticado. É possível filtrar os resultados por status, tipo de transação e um intervalo de datas.

### Method
GET

### Endpoint
/v1/user/transactions

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filtra pelo status da transação (PENDING, COMPLETED, CANCELED, REFUNDED, EXPIRED)
- **type** (string) - Optional - Filtra pelo tipo de transação (DEPOSIT, WITHDRAW, PAYMENT)
- **dateFrom** (string) - Optional - Data de início no formato RFC 3339
- **dateTo** (string) - Optional - Data de fim no formato RFC 3339

### Request Example
curl 'https://api.betpaympix.com/v1/user/transactions?status=PENDING&type=DEPOSIT' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

### Response
#### Success Response (200)
- **id** (string) - Identificador da transação
- **type** (string) - Tipo da transação
- **status** (string) - Status da transação
- **amount** (number) - Valor da transação
- **endToEndId** (string) - Identificador E2E
- **createdAt** (string) - Data de criação
- **paidAt** (string) - Data de pagamento

#### Response Example
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "DEPOSIT",
    "status": "PENDING",
    "amount": 1990,
    "endToEndId": "string",
    "createdAt": "2026-08-28T21:17:59.848Z",
    "paidAt": "2026-08-28T21:17:59.848Z"
  }
]
```

--------------------------------

### Consultar status da cobrança via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix/get/v1/pix

Exemplo de requisição GET para consultar uma cobrança, exigindo um token de autenticação Bearer.

```shell
curl 'https://api.betpaympix.com/v1/pix?id=' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### GET /v1/pix

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix/get/v1/pix

Retrieves the details of a Pix charge by its unique identifier.

```APIDOC
## GET /v1/pix

### Description
Retrieves the status and details of a specific Pix charge using its internal UUID.

### Method
GET

### Endpoint
https://api.betpaympix.com/v1/pix

### Parameters
#### Query Parameters
- **id** (string) - Required - ID interno da cobrança (UUID).

### Response
#### Success Response (200)
- **id** (string) - Internal ID of the charge
- **externalId** (string) - External reference ID
- **status** (string) - Current status of the charge (e.g., PENDING)
- **amount** (number) - Charge amount
- **type** (string) - Type of transaction (e.g., DEPOSIT)
- **qrCodeText** (string) - Pix QR code text
- **qrCodeBase64** (string) - Pix QR code in Base64 format
- **qrCodeUrl** (string) - URL for the Pix QR code
- **serviceFeeCharged** (number) - Service fee applied
- **endToEndId** (string) - Pix End-to-End ID
- **createdAt** (string) - Creation timestamp
- **paidAt** (string) - Payment timestamp

#### Response Example
{
  "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-08-28T21:17:56.589Z",
  "paidAt": "2026-08-28T21:17:56.589Z"
}
```

--------------------------------

### GET /v1/merchants

Source: https://payerpix.apidocumentation.com/api-reference/tag/merchants/get/v1/merchants

Retrieves a list of all merchants associated with the authenticated account.

```APIDOC
## GET /v1/merchants

### Description
Lists all merchants associated with your account.

### Method
GET

### Endpoint
https://api.betpaympix.com/v1/merchants

### Request Example
```bash
curl https://api.betpaympix.com/v1/merchants \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the merchant
- **name** (string) - Name of the merchant
- **externalId** (string) - External identifier for the merchant
- **isActive** (boolean) - Status indicating if the merchant is active
- **balanceAvailable** (number) - Available balance for the merchant
- **balanceBlocked** (number) - Blocked balance for the merchant
- **commissionBasisPoints** (number) - Commission basis points
- **userId** (string) - Associated user ID
- **createdAt** (string) - Timestamp of creation
- **updatedAt** (string) - Timestamp of last update

#### Response Example
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Loja Exemplo",
    "externalId": "loja-001",
    "isActive": true,
    "balanceAvailable": 154200,
    "balanceBlocked": 0,
    "commissionBasisPoints": 500,
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2026-08-28T21:17:56.964Z",
    "updatedAt": "2026-08-28T21:17:56.964Z"
  }
]
```

--------------------------------

### GET /v1/merchants/{id}/wallet

Source: https://payerpix.apidocumentation.com/api-reference/tag/merchants

Retrieves the wallet information for a specific merchant.

```APIDOC
## GET /v1/merchants/{id}/wallet

### Description
Retrieves the wallet information for a specific merchant.

### Method
GET

### Endpoint
/v1/merchants/{id}/wallet

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the merchant.
```

--------------------------------

### Consultar saldo do usuário

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/saldos-e-saques

Utilize este endpoint para verificar o saldo disponível e bloqueado do usuário. Os valores são retornados em centavos.

```bash
curl https://api.betpaympix.com/v1/user/balance \
  -H "Authorization: Bearer $API_TOKEN"
# { "balanceAvailable": 50000, "balanceBlocked": 0, "total": 50000 }
```

--------------------------------

### POST /v1/pix

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/cobran%C3%A7as-pix

Cria uma nova cobrança Pix com QR Code. Permite vincular um merchant existente ou criar um novo inline, incluindo regras de split.

```APIDOC
## POST /v1/pix

### Description
Cria uma cobrança Pix com QR Code (escopo DEPOSIT). Permite definir o valor, URL de callback e dados do pagador.

### Method
POST

### Endpoint
https://api.betpaympix.com/v1/pix

### Parameters
#### Request Body
- **amount** (integer) - Obrigatório - Valor em centavos
- **callbackUrl** (string) - Obrigatório - URL do webhook de confirmação
- **merchant** (object) - Opcional - Cria/atualiza um merchant inline
- **merchantId** (string) - Opcional - Vincula a um merchant existente
- **reseller** / **resellerId** (string) - Opcional - Parceiro/indicador
- **generatedName** / **generatedDocument** / **generatedEmail** (string) - Opcional - Dados do pagador
- **expiresIn** (integer) - Opcional - Validade em segundos (padrão 600)

### Request Example
{
  "amount": 1990,
  "callbackUrl": "https://sualoja.com/webhooks/payerpix",
  "merchantId": "b3f1c2a4-1111-2222-3333-444455556666",
  "generatedName": "Cliente Final",
  "generatedDocument": "12345678909",
  "expiresIn": 600
}

### Response
#### Success Response (201)
- **id** (string) - ID da cobrança
- **status** (string) - Status da cobrança
- **qrCodeUrl** (string) - URL da imagem do QR Code

#### Response Example
{
  "id": "0e9c...uuid",
  "status": "PENDING",
  "amount": 1990,
  "type": "DEPOSIT",
  "qrCodeText": "00020126...",
  "qrCodeUrl": "https://api.betpaympix.com/v1/pix/qrcode/0e9c...uuid"
}
```

--------------------------------

### Realizar saque via Pix

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/saldos-e-saques

Endpoint para solicitar um saque. É obrigatório o envio do cabeçalho Idempotency-Key para evitar transações duplicadas.

```bash
curl -X POST https://api.betpaympix.com/v1/withdraw \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 10000,
    "pixKey": "12345678909",
    "pixType": "CPF",
    "description": "Saque",
    "callbackUrl": "https://sualoja.com/webhooks/payerpix"
  }'
```

--------------------------------

### Gerar cobrança Pix via cURL

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/quick-start

Utilize este comando para criar uma nova cobrança Pix. Certifique-se de substituir $API_TOKEN pelo seu token de autenticação e fornecer uma Idempotency-Key válida.

```bash
curl -X POST https://api.betpaympix.com/v1/pix \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 1990,
    "callbackUrl": "https://sualoja.com/webhooks/payerpix",
    "merchant": { "externalId": "minha-loja", "name": "Minha Loja" }
  }'
```

--------------------------------

### Exemplo de Requisição com cURL

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/autentica%C3%A7%C3%A3o

Exemplo de como realizar uma chamada autenticada para um endpoint da API utilizando cURL.

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

--------------------------------

### Criar merchant com split na cobrança

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/cobran%C3%A7as-pix

Cria um merchant inline durante a cobrança e define regras de divisão de valores entre destinatários.

```bash
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 }
      ]
    }
  }'
```

--------------------------------

### POST /v1/pix

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix

Cria uma nova cobrança Pix.

```APIDOC
## POST /v1/pix

### Description
Cria uma nova cobrança Pix de entrada.

### Method
POST

### Endpoint
/v1/pix
```

--------------------------------

### GET /v1/merchants/{id}/transactions

Source: https://payerpix.apidocumentation.com/api-reference/tag/merchants

Retrieves the transaction history for a specific merchant.

```APIDOC
## GET /v1/merchants/{id}/transactions

### Description
Retrieves the transaction history for a specific merchant.

### Method
GET

### Endpoint
/v1/merchants/{id}/transactions

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the merchant.
```

--------------------------------

### Exemplo de resposta da API

Source: https://payerpix.apidocumentation.com/api-reference/tag/merchants/get/v1/merchants

Estrutura JSON retornada pelo endpoint ao listar os merchants com sucesso.

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Loja Exemplo",
    "externalId": "loja-001",
    "isActive": true,
    "balanceAvailable": 154200,
    "balanceBlocked": 0,
    "commissionBasisPoints": 500,
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2026-08-28T21:17:56.964Z",
    "updatedAt": "2026-08-28T21:17:56.964Z"
  }
]
```

--------------------------------

### Configuração de Split na Cobrança Pix

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/splits

Exemplo de estrutura JSON para definir regras de split dentro do objeto merchant ao criar uma cobrança.

```json
{
  "amount": 2000,
  "callbackUrl": "https://sualoja.com/webhooks/payerpix",
  "merchant": {
    "externalId": "mercado-do-bairro",
    "name": "Mercado do Bairro",
    "recipients": [
      { "recipientType": "USER", "recipientId": "<UUID_VENDEDOR>", "splitValue": 5000 },
      { "recipientType": "USER", "recipientId": "<UUID_INDICOU>", "splitValue": 1000 },
      { "recipientType": "MERCHANT", "recipientId": "<UUID_MERCADO>", "isRemainder": true, "splitValue": 1 }
    ]
  }
}
```

--------------------------------

### Resposta de sucesso do saldo

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/balance

Estrutura JSON retornada pelo servidor ao consultar o saldo com sucesso.

```json
{
  "balanceAvailable": 154200,
  "balanceBlocked": 0,
  "total": 154200
}
```

--------------------------------

### POST /v1/pix

Source: https://payerpix.apidocumentation.com/740c1ae5c5e4-merchants-openapi.json

Creates a new Pix charge with a QR code.

```APIDOC
## POST /v1/pix

### Description
Cria uma cobrança Pix com QR Code. Requer escopo `DEPOSIT`. Para vincular a cobrança a um merchant, informe o campo **`merchantId`** com o ID de um merchant já existente. Use o cabeçalho `Idempotency-Key` para evitar duplicidades em retentativas.

### Method
POST

### Endpoint
/v1/pix

### Parameters
#### Header Parameters
- **Idempotency-Key** (string) - Optional - Chave de idempotência para evitar cobranças duplicadas.

### Request Body
- **body** (CreatePixChargeRequest) - Required - The Pix charge details.

### Response
#### Success Response (201)
- **charge** (PixCharge) - The created Pix charge.
```

--------------------------------

### Consultar status da cobrança

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/cobran%C3%A7as-pix

Endpoint para verificar o status de uma cobrança existente através do seu ID.

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

--------------------------------

### Criar cobrança Pix

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/cobran%C3%A7as-pix

Exemplo de requisição POST para criar uma cobrança Pix e a estrutura da resposta de sucesso.

```bash
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
  }'
```

```json
{
  "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
}
```

--------------------------------

### Autenticação via API Token

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/autentica%C3%A7%C3%A3o

Todas as requisições autenticadas devem incluir um token no cabeçalho Authorization. O token deve ser prefixado com 'PP_'.

```APIDOC
## Autenticação

### Descrição
Todas as requisições autenticadas utilizam um API Token enviado no cabeçalho `Authorization`.

### Cabeçalho
- **Authorization** (string) - Required - O valor deve ser `Bearer PP_seu_token`.

### Escopos
- **DEPOSIT**: Permite criar cobranças Pix (`POST /v1/pix`).
- **WITHDRAW**: Permite criar saques (`POST /v1/withdraw`).
- **MERCHANT**: Permite acesso aos endpoints de merchant (`/v1/merchants/*`).

### Erros
- **401**: Token ausente ou inválido.
- **403**: Token sem o escopo exigido ou acesso negado ao recurso.
```

--------------------------------

### API Configuration and Authentication

Source: https://payerpix.apidocumentation.com/api-reference/description/introduction

General configuration details for interacting with the PayerPix API.

```APIDOC
## API Configuration

### Base URL
`https://api.betpaympix.com/v1`

### Authentication
- **Type**: Bearer Token
- **Header**: `Authorization: Bearer PP_...`
- **Scopes**: `DEPOSIT`, `WITHDRAW`, `MERCHANT`

### Data Standards
- **Currency**: All values are in cents (e.g., 1990 = R$ 19,90).
- **Dates**: ISO-8601 format in UTC.
- **Idempotency**: Use the `Idempotency-Key` header for write operations to prevent duplicate requests.
```

--------------------------------

### Formato da resposta de erro

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/erros

Estrutura JSON retornada em casos de erro. Utilize o campo 'error' para lógica de tratamento, pois o campo 'message' pode sofrer alterações.

```json
{
  "statusCode": 400,
  "error": "WITHDRAW_INSUFFICIENT_FUNDS",
  "message": "Saldo insuficiente para o saque solicitado."
}
```

--------------------------------

### Consult Merchant Wallet Balance

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/merchants

Retrieves the available and blocked balances for a specific merchant ID.

```bash
curl https://api.betpaympix.com/v1/merchants/{id}/wallet \
  -H "Authorization: Bearer $API_TOKEN"
# { "balanceAvailable": 18910, "balanceBlocked": 0, "total": 18910 }
```

--------------------------------

### POST /paymentstatus

Source: https://payerpix.apidocumentation.com/api-reference/tag/webhooks/webhook/post/paymentstatus

Webhook disparado quando o status de uma cobrança ou saque é alterado.

```APIDOC
## POST /paymentstatus

### Description
Enviado para a `callbackUrl` configurada quando o status de uma cobrança ou saque muda. O receptor deve responder com um código 2xx rapidamente e implementar lógica de idempotência utilizando o campo `payload.id`.

### Method
POST

### Request Body
- **deliveryAttempt** (integer) - Número da tentativa de entrega.
- **eventType** (string) - Tipo do evento (payment.completed, payment.expired, payment.refunded, withdraw.completed, withdraw.failed, withdraw.canceled).
- **payload** (object) - Dados detalhados do pagamento ou saque.
- **timestamp** (string) - Data e hora do evento no formato RFC 3339.

### Request Example
{
  "eventType": "payment.completed",
  "deliveryAttempt": 1,
  "timestamp": "",
  "payload": {
    "id": "",
    "externalId": "TX-9931",
    "status": "PENDING",
    "amount": 1990,
    "paidAt": "",
    "payerName": "Maria Souza",
    "payerDocument": "***.456.789-**",
    "endToEndId": "E1234567890...",
    "merchantId": ""
  }
}

### Response
#### Success Response (200)
- Recebido
```

--------------------------------

### Resposta de sucesso do saque

Source: https://payerpix.apidocumentation.com/api-reference/tag/saques/post/v1/withdraw

Estrutura do objeto JSON retornado após a criação bem-sucedida de um saque.

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PENDING",
  "amount": 1,
  "pixKey": "string",
  "pixType": "CPF",
  "createdAt": "2026-08-28T21:17:58.588Z"
}
```

--------------------------------

### Configuração de Splits na Cobrança

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/splits

Exemplo de como incluir a configuração de recebedores (recipients) dentro do objeto merchant ao criar uma cobrança Pix.

```APIDOC
## Configuração de Splits

### Descrição
As regras de split são definidas no objeto `merchant` dentro da requisição de criação de cobrança Pix, utilizando o campo `recipients`.

### Parâmetros do Recebedor
- **recipientType** (string) - Obrigatório - Tipo do recebedor: `USER` ou `MERCHANT`.
- **recipientId** (string) - Obrigatório - UUID do recebedor.
- **splitValue** (integer) - Obrigatório - Valor da divisão. Em `PERCENTAGE`: *basis points* (ex: 5000 = 50%). Em `FIXED`: valor em centavos.
- **splitType** (string) - Opcional - Tipo de divisão: `PERCENTAGE` (padrão) ou `FIXED`.
- **isRemainder** (boolean) - Opcional - Define se o recebedor receberá o valor restante da transação.

### Exemplo de Requisição
```json
{
  "amount": 2000,
  "callbackUrl": "https://sualoja.com/webhooks/payerpix",
  "merchant": {
    "externalId": "mercado-do-bairro",
    "name": "Mercado do Bairro",
    "recipients": [
      { "recipientType": "USER", "recipientId": "<UUID_VENDEDOR>", "splitValue": 5000 },
      { "recipientType": "USER", "recipientId": "<UUID_INDICOU>", "splitValue": 1000 },
      { "recipientType": "MERCHANT", "recipientId": "<UUID_MERCADO>", "isRemainder": true, "splitValue": 1 }
    ]
  }
}
```
```

--------------------------------

### Exemplo de Payload de Webhook

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/webhooks

Estrutura JSON enviada pela PayerPix ao notificar um evento de pagamento concluído.

```json
{
  "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"
}
```

--------------------------------

### Retrieve user account data via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user

Use this cURL command to fetch the authenticated user's profile information. Ensure the Authorization header includes a valid Bearer token.

```shell
curl https://api.betpaympix.com/v1/user \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### POST /withdrawals

Source: https://payerpix.apidocumentation.com/740c1ae5c5e4-merchants-openapi.json

Creates a Pix withdrawal from the user's balance. Requires the WITHDRAW scope.

```APIDOC
## POST /withdrawals

### Description
Cria um saque Pix a partir do saldo do usuário. Requer escopo `WITHDRAW`.

### Method
POST

### Endpoint
/withdrawals

### Parameters
#### Header Parameters
- **Idempotency-Key** (string) - Optional - Chave de idempotência para evitar requisições duplicadas.

### Request Body
- **WithdrawRequest** (object) - Required - Objeto contendo os detalhes do saque (conforme schema WithdrawRequest).

### Response
#### Success Response (201)
- **Withdraw** (object) - Objeto contendo os detalhes do saque criado (conforme schema Withdraw).

#### Error Responses
- **400** - Payload inválido
- **403** - Sem permissão/escopo ou merchant de outro dono
```

--------------------------------

### POST /v1/withdraw

Source: https://payerpix.apidocumentation.com/api-reference/tag/saques/post/v1/withdraw

Cria um saque Pix a partir do saldo do usuário. Requer escopo WITHDRAW e uma chave de idempotência para evitar duplicidade.

```APIDOC
## POST /v1/withdraw

### Description
Cria um saque Pix a partir do saldo do usuário. Requer escopo `WITHDRAW`.

### Method
POST

### Endpoint
https://api.betpaympix.com/v1/withdraw

### Parameters
#### Headers
- **Idempotency-Key** (string) - Required - Chave de idempotência (UUID recomendado).
- **Authorization** (string) - Required - Bearer token com prefixo PP_.

#### Request Body
- **amount** (integer) - Required - Valor do saque (mínimo 1).
- **pixKey** (string) - Required - Chave Pix do destinatário.
- **pixType** (string) - Required - Tipo da chave Pix (CPF, CNPJ, EMAIL, PHONE, EVP).
- **callbackUrl** (string) - Optional - URL para retorno de status.
- **description** (string) - Optional - Descrição do saque.
- **pin** (string) - Optional - PIN de segurança (se configurado).

### Request Example
{
  "amount": 10000,
  "pixKey": "12345678909",
  "pixType": "CPF",
  "pin": "",
  "description": "",
  "callbackUrl": ""
}

### Response
#### Success Response (201)
- **id** (string) - ID do saque.
- **status** (string) - Status da operação (ex: PENDING).
- **amount** (integer) - Valor do saque.
- **pixKey** (string) - Chave Pix utilizada.
- **pixType** (string) - Tipo da chave Pix.
- **createdAt** (string) - Data de criação.

#### Response Example
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "PENDING",
  "amount": 1,
  "pixKey": "string",
  "pixType": "CPF",
  "createdAt": "2026-08-28T21:17:58.588Z"
}
```

--------------------------------

### Retrieve User Summary via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/summary

Use this request to fetch aggregated metrics. Ensure the Authorization header includes a valid bearer token.

```shell
curl https://api.betpaympix.com/v1/user/summary \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

--------------------------------

### Obter imagem do QR Code

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/cobran%C3%A7as-pix

Endpoint público para recuperar a imagem PNG do QR Code de uma cobrança.

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

--------------------------------

### Exemplo de Requisição de Cobrança Pix

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix/post/v1/pix

Corpo da requisição JSON para criar uma cobrança, incluindo detalhes do merchant e do revendedor.

```json
{ "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}
```

--------------------------------

### User Summary Response Schema

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/summary

The response returns a JSON object containing financial totals and transaction counts.

```json
{
  "totalIn": 154200,
  "totalOut": 50000,
  "net": 104200,
  "depositsCount": 37,
  "withdrawsCount": 4
}
```

--------------------------------

### Estrutura da resposta da cobrança

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix/get/v1/pix

Exemplo do objeto JSON retornado ao consultar com sucesso o status de uma cobrança.

```json
{
  "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-08-28T21:17:56.589Z",
  "paidAt": "2026-08-28T21:17:56.589Z"
}
```

--------------------------------

### Estrutura da resposta de transações

Source: https://payerpix.apidocumentation.com/api-reference/tag/usu%C3%A1rio/get/v1/user/transactions

Exemplo do formato JSON retornado pelo endpoint de transações.

```json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "DEPOSIT",
    "status": "PENDING",
    "amount": 1990,
    "endToEndId": "string",
    "createdAt": "2026-08-28T21:17:59.848Z",
    "paidAt": "2026-08-28T21:17:59.848Z"
  }
]
```

--------------------------------

### Resposta de sucesso da criação de cobrança

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix/post/v1/pix

Estrutura do objeto JSON retornado após a criação bem-sucedida de uma cobrança Pix.

```json
{
  "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-08-28T21:17:56.748Z",
  "paidAt": "2026-08-28T21:17:56.748Z"
}
```

--------------------------------

### Criar saque Pix via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/saques/post/v1/withdraw

Exemplo de requisição POST para o endpoint de saque, incluindo cabeçalhos de autenticação e idempotência.

```shell
curl https://api.betpaympix.com/v1/withdraw \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "amount": 10000,
  "pixKey": "12345678909",
  "pixType": "CPF",
  "pin": "",
  "description": "",
  "callbackUrl": ""
}'
```

--------------------------------

### POST Evento de cobrança (pagamento)

Source: https://payerpix.apidocumentation.com/api-reference/tag/webhooks

Webhook event triggered when a payment (cobrança) is processed.

```APIDOC
## POST Evento de cobrança (pagamento)

### Description
This webhook event is sent by PayerPix to your configured callbackUrl when a payment (cobrança) occurs.
```

--------------------------------

### List Merchants

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/merchants

Retrieves all merchants associated with the authenticated API account.

```bash
curl https://api.betpaympix.com/v1/merchants \
  -H "Authorization: Bearer $API_TOKEN"
```

--------------------------------

### Criar cobrança Pix via cURL

Source: https://payerpix.apidocumentation.com/api-reference/tag/cobran%C3%A7as-pix/post/v1/pix

Exemplo de requisição POST para o endpoint de criação de cobranças Pix, incluindo cabeçalhos de autenticação e idempotência.

```shell
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
}'
```

--------------------------------

### POST Evento de saque

Source: https://payerpix.apidocumentation.com/api-reference/tag/webhooks

Webhook event triggered when a withdrawal (saque) is processed.

```APIDOC
## POST Evento de saque

### Description
This webhook event is sent by PayerPix to your configured callbackUrl when a withdrawal (saque) occurs.
```

--------------------------------

### Withdraw Funds Directly from Merchant

Source: https://payerpix.apidocumentation.com/documenta%C3%A7%C3%A3o/merchants

Initiates a Pix withdrawal from a merchant's balance to a specified Pix key.

```bash
curl -X POST https://api.betpaympix.com/v1/merchants/{id}/withdraw \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 10000,
    "pixKey": "12345678909",
    "pixType": "CPF",
    "description": "Repasse loja",
    "callbackUrl": "https://sualoja.com/webhooks/payerpix"
  }'
```
Tokens:
Raw