WaterPay

https://waterpag.com/docs
Admin
WaterPay is a payment gateway API that enables businesses to integrate Pix charges, withdrawals,...
Tokens:10,371
Snippets:77
Trust Score:2.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /fees

Source: https://waterpag.com/docs

Consulta as taxas efetivas da conta. Requer a permissão balance.read.

```APIDOC
## GET /fees

### Description
Consulta as taxas efetivas da conta.

### Method
GET

### Endpoint
/fees

### Response
#### Success Response (200)
- **fees** (array) - Lista de taxas.

#### Response Example
{
  "fees": []
}

```

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

### GET /balance

Source: https://waterpag.com/docs

Consulta saldo disponível, bloqueado e a receber. Requer a permissão balance.read.

```APIDOC
## GET /balance

### Description
Consulta saldo disponível, bloqueado e a receber.

### Method
GET

### Endpoint
/balance

### Response
#### Success Response (200)
- **available** (number) - Saldo disponível.
- **blocked** (number) - Saldo bloqueado.
- **receivable** (number) - Saldo a receber.

#### Response Example
{
  "available": 100.00,
  "blocked": 0.00,
  "receivable": 50.00
}

```

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

### GET /payments

Source: https://waterpag.com/docs

Lista cobranças Pix com filtros. Requer a permissão payments.read.

```APIDOC
## GET /payments

### Description
Lista cobranças Pix com filtros.

### Method
GET

### Endpoint
/payments

### Parameters
#### Query Parameters
- **status** (string) - Opcional - Filtro por status.
- **reference_id** (string) - Opcional - Filtro por referência.

### Response
#### Success Response (200)
- **payments** (array) - Lista de cobranças.

#### Response Example
{
  "payments": []
}

```

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

### GET /transactions

Source: https://waterpag.com/docs

Extrato unificado da conta. Requer a permissão balance.read.

```APIDOC
## GET /transactions

### Description
Extrato unificado da conta.

### Method
GET

### Endpoint
/transactions

### Response
#### Success Response (200)
- **transactions** (array) - Lista de transações.

#### Response Example
{
  "transactions": []
}

```

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

### GET /schema

Source: https://waterpag.com/docs

Retorna o contrato OpenAPI para importar na sua ferramenta. Endpoint público.

```APIDOC
## GET /schema

### Description
Retorna o contrato OpenAPI para importar na sua ferramenta.

### Method
GET

### Endpoint
/schema

### Response
#### Success Response (200)
- **schema** (object) - Contrato OpenAPI.

#### Response Example
{
  "openapi": "3.0.0"
}

```

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

### GET /withdrawals

Source: https://waterpag.com/docs

Lista saques com filtros. Requer a permissão withdrawals.read.

```APIDOC
## GET /withdrawals

### Description
Lista saques com filtros.

### Method
GET

### Endpoint
/withdrawals

### Parameters
#### Query Parameters
- **status** (string) - Opcional - Filtro por status.
- **reference_id** (string) - Opcional - Filtro por referência.

### Response
#### Success Response (200)
- **withdrawals** (array) - Lista de saques.

#### Response Example
{
  "withdrawals": []
}

```

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

### GET /balance

Source: https://waterpag.com/docs

Retrieves the current account balance. Requires an API key for authentication.

```APIDOC
## GET /balance

### Description
Retrieves the current account balance.

### Method
GET

### Endpoint
/balance

### Request Example
```bash
curl "https://waterpag.com/api/v1/balance" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
No response schema provided in the source.

```

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

### Authenticate with X-API-Key

Source: https://waterpag.com/docs

Example of a POST request to the payments endpoint using an API key and an idempotency key for safe transaction processing.

```bash
curl -X POST "https://waterpag.com/api/v1/payments" \
  -H "X-API-Key: zpk_live_sua_chave_privada" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: pedido-1001" \
  -d '{"amount": 100.00, "customer": {"name": "Cliente Demo", "document": "12345678909"}}'
```

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

### GET /webhooks/deliveries

Source: https://waterpag.com/docs

Consulta entregas de webhook. Requer a permissão webhooks.manage.

```APIDOC
## GET /webhooks/deliveries

### Description
Consulta entregas de webhook.

### Method
GET

### Endpoint
/webhooks/deliveries

### Response
#### Success Response (200)
- **deliveries** (array) - Lista de entregas.

#### Response Example
{
  "deliveries": []
}

```

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

### Consultar Saldo com curl

Source: https://waterpag.com/docs

Exemplo de requisição GET para o endpoint /balance, retornando o saldo da conta. Requer chave de API privada (X-API-Key).

```bash
curl "https://waterpag.com/api/v1/balance" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### GET /payments/{reference_id}

Source: https://waterpag.com/docs

Busca uma cobrança pela sua referência. Requer a permissão payments.read.

```APIDOC
## GET /payments/{reference_id}

### Description
Busca uma cobrança pela sua referência.

### Method
GET

### Endpoint
/payments/{reference_id}

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - Referência da cobrança.

### Response
#### Success Response (200)
- **id** (string) - Identificador da cobrança.
- **status** (string) - Status da cobrança.

#### Response Example
{
  "id": "pay_123",
  "status": "PENDING"
}

```

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

### GET /withdrawals/{reference_id}

Source: https://waterpag.com/docs

Busca um saque pela sua referência. Requer a permissão withdrawals.read.

```APIDOC
## GET /withdrawals/{reference_id}

### Description
Busca um saque pela sua referência.

### Method
GET

### Endpoint
/withdrawals/{reference_id}

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - Referência do saque.

### Response
#### Success Response (200)
- **id** (string) - Identificador do saque.
- **status** (string) - Status do saque.

#### Response Example
{
  "id": "wd_123",
  "status": "PENDING"
}

```

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

### GET /fees

Source: https://waterpag.com/docs

Consult the fee rates for the account. Requires the balance.read scope. Returns deposit_fixed, deposit_percent, withdrawal_fixed, withdrawal_percent, currency, and mode (global or custom).

```APIDOC
## GET /fees

### Description
Consult the fee rates for the account. Requires the balance.read scope.

### Method
GET

### Endpoint
/fees

### Parameters
#### Query Parameters
- **scope** (string) - Required - Must be balance.read.

### Response
#### Success Response (200)
Returns fee configuration fields: deposit_fixed, deposit_percent, withdrawal_fixed, withdrawal_percent, currency, and mode.

```

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

### Obter Extrato com curl

Source: https://waterpag.com/docs

Exemplo de requisição GET para o endpoint /transactions, com limite de 100 transações por página e página 1. Requer chave de API privada (X-API-Key).

```bash
curl "https://waterpag.com/api/v1/transactions?limit=100&page=1" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### GET /health

Source: https://waterpag.com/docs

Verifica se a API está online. Endpoint público, sem autenticação necessária.

```APIDOC
## GET /health

### Description
Verifica se a API está online.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Status da API.

#### Response Example
{
  "status": "ok"
}

```

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

### GET /payments/{reference_id}

Source: https://waterpag.com/docs

Search for a payment by its reference ID. Returns the payment details for the specified reference.

```APIDOC
## GET /payments/{reference_id}

### Description
Search for a payment by its reference ID.

### Method
GET

### Endpoint
/payments/{reference_id}

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - The reference ID of the payment.

### Request Example
```bash
curl "https://waterpag.com/api/v1/payments/pedido-1001" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
Returns the payment details.

```

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

### GET /transactions

Source: https://waterpag.com/docs

Retrieves the account transaction history (statement) with pagination. Requires an API key for authentication.

```APIDOC
## GET /transactions

### Description
Retrieves the account transaction history (statement) with pagination.

### Method
GET

### Endpoint
/transactions

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of results per page
- **page** (integer) - Optional - Page number

### Request Example
```bash
curl "https://waterpag.com/api/v1/transactions?limit=100&page=1" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
No response schema provided in the source.

```

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

### GET /withdrawals/{reference_id}

Source: https://waterpag.com/docs

Search for a withdrawal by its reference ID. Returns the withdrawal details for the specified reference.

```APIDOC
## GET /withdrawals/{reference_id}

### Description
Search for a withdrawal by its reference ID.

### Method
GET

### Endpoint
/withdrawals/{reference_id}

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - The reference ID of the withdrawal.

### Request Example
```bash
curl "https://waterpag.com/api/v1/withdrawals/saque-1001" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
Returns the withdrawal details.

```

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

### GET /transactions/{reference_id}

Source: https://waterpag.com/docs

Busca qualquer transação da conta por referência. Requer as permissões payments.read ou withdrawals.read.

```APIDOC
## GET /transactions/{reference_id}

### Description
Busca qualquer transação da conta por referência.

### Method
GET

### Endpoint
/transactions/{reference_id}

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - Referência da transação.

### Response
#### Success Response (200)
- **id** (string) - Identificador da transação.
- **type** (string) - Tipo da transação.
- **status** (string) - Status da transação.

#### Response Example
{
  "id": "txn_123",
  "type": "payment",
  "status": "PAID"
}

```

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

### GET /withdrawals/{reference_id}/status

Source: https://waterpag.com/docs

Busca e tenta atualizar o status junto ao provedor. Requer a permissão withdrawals.read.

```APIDOC
## GET /withdrawals/{reference_id}/status

### Description
Busca e tenta atualizar o status junto ao provedor.

### Method
GET

### Endpoint
/withdrawals/{reference_id}/status

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - Referência do saque.

### Response
#### Success Response (200)
- **status** (string) - Status atualizado.

#### Response Example
{
  "status": "PAID"
}

```

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

### GET /payments

Source: https://waterpag.com/docs

List payments with optional filters for status, limit, and page. Returns a paginated list of payments.

```APIDOC
## GET /payments

### Description
List payments with optional filters.

### Method
GET

### Endpoint
/payments

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by payment status (e.g., PENDING).
- **limit** (integer) - Optional - Number of results per page.
- **page** (integer) - Optional - Page number.

### Request Example
```bash
curl "https://waterpag.com/api/v1/payments?status=PENDING&limit=50&page=1" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
Returns a list of payments.

```

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

### GET /withdrawals

Source: https://waterpag.com/docs

Lists withdrawals with optional filters for status, limit, and page. Requires an API key for authentication.

```APIDOC
## GET /withdrawals

### Description
Lists withdrawals with optional filters for status, limit, and page.

### Method
GET

### Endpoint
/withdrawals

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by withdrawal status (e.g., PROCESSING)
- **limit** (integer) - Optional - Number of results per page
- **page** (integer) - Optional - Page number

### Request Example
```bash
curl "https://waterpag.com/api/v1/withdrawals?status=PROCESSING&limit=50&page=1" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
No response schema provided in the source.

```

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

### Listar Saques com curl

Source: https://waterpag.com/docs

Exemplo de requisição GET para o endpoint /withdrawals, filtrando por status PROCESSING, com limite de 50 e página 1. Requer chave de API privada (X-API-Key).

```bash
curl "https://waterpag.com/api/v1/withdrawals?status=PROCESSING&limit=50&page=1" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### GET /payments/{reference_id}/status

Source: https://waterpag.com/docs

Busca e tenta atualizar o status junto ao provedor. Requer a permissão payments.read.

```APIDOC
## GET /payments/{reference_id}/status

### Description
Busca e tenta atualizar o status junto ao provedor.

### Method
GET

### Endpoint
/payments/{reference_id}/status

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - Referência da cobrança.

### Response
#### Success Response (200)
- **status** (string) - Status atualizado.

#### Response Example
{
  "status": "PAID"
}

```

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

### GET /withdrawals/{reference_id}/status

Source: https://waterpag.com/docs

Check the status of a withdrawal by its reference ID. Returns the current status of the specified withdrawal.

```APIDOC
## GET /withdrawals/{reference_id}/status

### Description
Check the status of a withdrawal by its reference ID.

### Method
GET

### Endpoint
/withdrawals/{reference_id}/status

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - The reference ID of the withdrawal.

### Request Example
```bash
curl "https://waterpag.com/api/v1/withdrawals/saque-1001/status" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
Returns the withdrawal status.

```

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

### GET /payments/{reference_id}/status

Source: https://waterpag.com/docs

Check the status of a payment by its reference ID. Returns the current status of the specified payment.

```APIDOC
## GET /payments/{reference_id}/status

### Description
Check the status of a payment by its reference ID.

### Method
GET

### Endpoint
/payments/{reference_id}/status

### Parameters
#### Path Parameters
- **reference_id** (string) - Required - The reference ID of the payment.

### Request Example
```bash
curl "https://waterpag.com/api/v1/payments/pedido-1001/status" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

### Response
#### Success Response (200)
Returns the payment status.

```

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

### POST /payments

Source: https://waterpag.com/docs

Cria uma cobrança Pix. Requer a permissão payments.create.

```APIDOC
## POST /payments

### Description
Cria uma cobrança Pix.

### Method
POST

### Endpoint
/payments

### Parameters
#### Request Body
- **amount** (number) - Required - Valor da cobrança.
- **reference_id** (string) - Required - Identificador da cobrança.

### Request Example
{
  "amount": 100.00,
  "reference_id": "ref_123"
}

### Response
#### Success Response (200)
- **id** (string) - Identificador da cobrança.
- **status** (string) - Status da cobrança.

#### Response Example
{
  "id": "pay_123",
  "status": "PENDING"
}

```

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

### POST /webhooks/test

Source: https://waterpag.com/docs

Dispara um evento de teste para sua URL de webhook. Requer a permissão webhooks.manage.

```APIDOC
## POST /webhooks/test

### Description
Dispara um evento de teste para sua URL de webhook.

### Method
POST

### Endpoint
/webhooks/test

### Parameters
#### Request Body
- **event** (string) - Required - O evento de teste a ser disparado.

### Request Example
{
  "event": "payment.test"
}

### Response
#### Success Response (200)
- **status** (string) - Status da operação.

#### Response Example
{
  "status": "ok"
}

### Error Handling
- **429** - Limite de requisições atingido. Inclui o header `Retry-After`.

```

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

### Estrutura de resposta de sucesso

Source: https://waterpag.com/docs

Exemplo de resposta JSON para uma operação bem-sucedida, contendo id, status e amount.

```json
{
  "id": "pedido-1001",
  "status": "PENDING",
  "amount": 120.5
}
```

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

### POST /pix, /charges, /deposits

Source: https://waterpag.com/docs

Aliases para criar cobrança Pix. Requer a permissão payments.create.

```APIDOC
## POST /pix, /charges, /deposits

### Description
Aliases para criar cobrança Pix.

### Method
POST

### Endpoint
/pix, /charges, /deposits

### Parameters
#### Request Body
- **amount** (number) - Required - Valor da cobrança.
- **reference_id** (string) - Required - Identificador da cobrança.

### Request Example
{
  "amount": 100.00,
  "reference_id": "ref_123"
}

### Response
#### Success Response (200)
- **id** (string) - Identificador da cobrança.
- **status** (string) - Status da cobrança.

#### Response Example
{
  "id": "pay_123",
  "status": "PENDING"
}

```

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

### Buscar Pagamento

Source: https://waterpag.com/docs

Retrieves details for a specific payment using its reference ID.

```bash
curl "https://waterpag.com/api/v1/payments/pedido-1001" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### POST /withdrawals

Source: https://waterpag.com/docs

Create a withdrawal request using available balance. The API validates the Pix key, reserves the balance, and processes the transfer. Aliases such as pixKey, value, payout_id, and external_reference are also accepted.

```APIDOC
## POST /withdrawals

### Description
Create a withdrawal request using available balance.

### Method
POST

### Endpoint
/withdrawals

### Parameters
#### Request Body
- **amount** (number) - Required - The amount to withdraw.
- **reference_id** (string) - Required - The reference ID for the withdrawal.
- **pix_key** (string) - Required - The Pix key for the transfer.
- **metadata** (object) - Optional - Additional metadata, e.g., payout_id.

### Request Example
```json
{
  "amount": 80.00,
  "reference_id": "saque-1001",
  "pix_key": "seller@empresa.com",
  "metadata": {
    "payout_id": "1001"
  }
}
```

### Response
#### Success Response (200)
Returns the created withdrawal details.

```

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

### POST /webhooks/retry

Source: https://waterpag.com/docs

Reenvia uma entrega ou eventos de uma transação. Requer a permissão webhooks.manage.

```APIDOC
## POST /webhooks/retry

### Description
Reenvia uma entrega ou eventos de uma transação.

### Method
POST

### Endpoint
/webhooks/retry

### Parameters
#### Request Body
- **delivery_id** (string) - Opcional - Identificador da entrega a ser reenviada.
- **transaction_id** (string) - Opcional - Identificador da transação para reenviar eventos.

### Request Example
{
  "delivery_id": "del_123"
}

### Response
#### Success Response (200)
- **status** (string) - Status da operação.

#### Response Example
{
  "status": "ok"
}

```

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

### POST /withdrawals

Source: https://waterpag.com/docs

Solicita envio Pix para uma chave. Requer a permissão withdrawals.create.

```APIDOC
## POST /withdrawals

### Description
Solicita envio Pix para uma chave.

### Method
POST

### Endpoint
/withdrawals

### Parameters
#### Request Body
- **amount** (number) - Required - Valor do saque.
- **pix_key** (string) - Required - Chave Pix de destino.
- **reference_id** (string) - Required - Identificador do saque.

### Request Example
{
  "amount": 50.00,
  "pix_key": "chave@example.com",
  "reference_id": "ref_456"
}

### Response
#### Success Response (200)
- **id** (string) - Identificador do saque.
- **status** (string) - Status do saque.

#### Response Example
{
  "id": "wd_123",
  "status": "PENDING"
}

```

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

### Criar Pagamento - Resposta da API

Source: https://waterpag.com/docs

Exemplo de resposta da API para a criação de pagamento, incluindo status PENDING, pix_copy_paste, pix_qr_code_url e pix_qr_code_base64.

```json
{
  "id": "pedido-1001",
  "reference_id": "pedido-1001",
  "external_transaction_id": "pedido-1001",
  "type": "DEPOSIT",
  "status": "PENDING",
  "amount": 120.5,
  "fee_amount": 3.3,
  "net_amount": 117.2,
  "pix_copy_paste": "000201010212...",
  "pix_qr_code_url": "https://waterpag.com/api/v1/pix/qrcode/pedido-1001/pubtoken.png",
  "pix_qr_code_base64": "data:image/png;base64,...",
  "expires_at": "2026-09-18T23:10:33.872Z"
}
```

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

### POST /payouts, /cashout

Source: https://waterpag.com/docs

Aliases para criar saque Pix. Requer a permissão withdrawals.create.

```APIDOC
## POST /payouts, /cashout

### Description
Aliases para criar saque Pix.

### Method
POST

### Endpoint
/payouts, /cashout

### Parameters
#### Request Body
- **amount** (number) - Required - Valor do saque.
- **pix_key** (string) - Required - Chave Pix de destino.
- **reference_id** (string) - Required - Identificador do saque.

### Request Example
{
  "amount": 50.00,
  "pix_key": "chave@example.com",
  "reference_id": "ref_456"
}

### Response
#### Success Response (200)
- **id** (string) - Identificador do saque.
- **status** (string) - Status do saque.

#### Response Example
{
  "id": "wd_123",
  "status": "PENDING"
}

```

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

### POST /payments

Source: https://waterpag.com/docs

Cria uma cobrança Pix usando valor, referência própria e dados do pagador. Requer um identificador estável (reference_id ou X-Idempotency-Key) e documento do pagador válido (CPF ou CNPJ).

```APIDOC
## POST /payments

### Description
Cria uma cobrança Pix usando valor, referência própria e dados do pagador. Envie `reference_id` ou `X-Idempotency-Key`; sem um identificador estável a API rejeita a operação. O documento do pagador deve ser CPF ou CNPJ válido; alguns provedores exigem CPF para cobrança Pix.

### Method
POST

### Endpoint
/payments

### Parameters
#### Request Body
- **amount** (number) - Required - Valor da cobrança em reais.
- **description** (string) - Optional - Descrição do pagamento.
- **reference_id** (string) - Required - Identificador estável da cobrança (ou usar X-Idempotency-Key).
- **customer** (object) - Required - Dados do pagador.
  - **name** (string) - Required - Nome do pagador.
  - **document** (string) - Required - CPF ou CNPJ do pagador.
- **metadata** (object) - Optional - Metadados adicionais.
  - **order_id** (string) - Optional - Identificador do pedido.

### Request Example
{
  "amount": 120.50,
  "description": "Pedido #1001",
  "reference_id": "pedido-1001",
  "customer": {
    "name": "Cliente Demo",
    "document": "12345678909"
  },
  "metadata": {
    "order_id": "1001"
  }
}

### Response
#### Success Response (200)
- **id** (string) - Identificador do pagamento.
- **reference_id** (string) - Referência própria enviada.
- **external_transaction_id** (string) - Identificador externo da transação.
- **type** (string) - Tipo da transação (ex: DEPOSIT).
- **status** (string) - Status do pagamento (ex: PENDING).
- **amount** (number) - Valor da cobrança.
- **fee_amount** (number) - Valor da taxa.
- **net_amount** (number) - Valor líquido.
- **pix_copy_paste** (string) - Código Pix copia e cola.
- **pix_qr_code_url** (string) - URL do QR Code (proxy WaterPay).
- **pix_qr_code_base64** (string) - QR Code em base64.
- **expires_at** (string) - Data de expiração.

#### Response Example
{
  "id": "pedido-1001",
  "reference_id": "pedido-1001",
  "external_transaction_id": "pedido-1001",
  "type": "DEPOSIT",
  "status": "PENDING",
  "amount": 120.5,
  "fee_amount": 3.3,
  "net_amount": 117.2,
  "pix_copy_paste": "000201010212...",
  "pix_qr_code_url": "https://waterpag.com/api/v1/pix/qrcode/pedido-1001/pubtoken.png",
  "pix_qr_code_base64": "data:image/png;base64,...",
  "expires_at": "2026-09-18T23:10:33.872Z"
}

### Error Response
#### Error Response (400)
- **detail** (string) - Mensagem de erro, ex: "API key invalida ou sem permissao."

#### Error Response Example
{
  "detail": "API key invalida ou sem permissao."
}
```

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

### Buscar Status de Pagamento

Source: https://waterpag.com/docs

Retrieves the current status of a specific payment.

```bash
curl "https://waterpag.com/api/v1/payments/pedido-1001/status" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### Listar Pagamentos

Source: https://waterpag.com/docs

Retrieves a list of payments filtered by status, with pagination support.

```bash
curl "https://waterpag.com/api/v1/payments?status=PENDING&limit=50&page=1" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### Criar Pagamento - Requisição POST /payments

Source: https://waterpag.com/docs

Exemplo de requisição para criar uma cobrança Pix. Envie reference_id ou X-Idempotency-Key; sem um identificador estável a API rejeita a operação. O documento do pagador deve ser CPF ou CNPJ válido.

```json
{
  "amount": 120.50,
  "description": "Pedido #1001",
  "reference_id": "pedido-1001",
  "customer": {
    "name": "Cliente Demo",
    "document": "12345678909"
  },
  "metadata": {
    "order_id": "1001"
  }
}
```

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

### Estrutura de resposta de erro

Source: https://waterpag.com/docs

Exemplo de resposta JSON para erro, com mensagem sobre API key inválida ou sem permissão.

```json
{
  "detail": "API key invalida ou sem permissao."
}
```

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

### Buscar Saque

Source: https://waterpag.com/docs

Retrieves details for a specific withdrawal request.

```bash
curl "https://waterpag.com/api/v1/withdrawals/saque-1001" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### POST /payments - Criar cobrança PIX

Source: https://waterpag.com/docs

Cria uma cobrança PIX imediata com copia e cola, QR Code e expiração controlada pela WaterPay. Requer autenticação via X-API-Key e suporta idempotência via X-Idempotency-Key.

```APIDOC
## POST /payments

### Description
Cria uma cobrança PIX imediata. A resposta inclui copia e cola, QR Code e expiração controlada pela WaterPay.

### Method
POST

### Endpoint
https://waterpag.com/api/v1/payments

### Headers
- **X-API-Key** (string) - Required - Chave privada de API.
- **Content-Type** (string) - Required - application/json.
- **X-Idempotency-Key** (string) - Required - Identificador único para idempotência.

### Request Body
- **amount** (number) - Required - Valor em reais com até duas casas decimais (ex: 100.00).
- **customer** (object) - Required - Dados do cliente.
  - **name** (string) - Required - Nome do cliente.
  - **document** (string) - Required - Documento do cliente (CPF/CNPJ).

### Request Example
{
  "amount": 100.00,
  "customer": {
    "name": "Cliente Demo",
    "document": "12345678909"
  }
}

### Response
#### Success Response (201)
HTTP 201 indica criação bem-sucedida.

### Error Handling
Após timeout ou erro 502, consulte a mesma referência antes de repetir. Nunca crie outra referência para contornar uma resposta incerta.
```

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

### Validar Assinatura HMAC de Webhook

Source: https://waterpag.com/docs

Função TypeScript que verifica a assinatura HMAC-SHA256 de um webhook. Valida o formato da assinatura, o timestamp (tolerância de 5 minutos) e usa timingSafeEqual para comparação segura.

```typescript
import crypto from 'node:crypto'

export function verifyWebhook(rawBody, signature, timestamp, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const time = Date.parse(timestamp)
  if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/.test(signature) || !Number.isFinite(time) || Math.abs(Date.now() - time) > 5 * 60 * 1000) {
    return false
  }

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  )
}
```

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

### Test Webhook with curl

Source: https://waterpag.com/docs

Sends a test webhook event to the WaterPay API using curl. Requires a private API key (X-API-Key) and sends a JSON payload with event 'payment.test'.

```bash
curl -X POST "https://waterpag.com/api/v1/webhooks/test" \
  -H "X-API-Key: zpk_live_sua_chave_privada" \
  -H "Content-Type: application/json" \
  -d '{"event":"payment.test"}'
```

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

### Buscar Status de Saque

Source: https://waterpag.com/docs

Retrieves the current status of a specific withdrawal request.

```bash
curl "https://waterpag.com/api/v1/withdrawals/saque-1001/status" \
  -H "X-API-Key: zpk_live_sua_chave_privada"
```

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

### Webhooks

Source: https://waterpag.com/docs

Configure a public HTTPS URL on the credential to receive events. Each delivery includes headers for event type, delivery ID, timestamp, and HMAC signature. The signature is HMAC-SHA256 over timestamp.raw_body.

```APIDOC
## Webhooks

### Description
Configure a public HTTPS URL on the credential to receive events. Each delivery includes headers for event type, delivery ID, timestamp, and HMAC signature. The signature is HMAC-SHA256 over timestamp.raw_body.

### Headers
- **X-Zennith-Event** - Event type
- **X-Zennith-Delivery** - Delivery identifier
- **X-Zennith-Timestamp** - Timestamp of the event
- **X-Zennith-Signature** - HMAC signature

### Payload Example
```json
{
  "id": "whd_20260918224033_ab12cd34",
  "event": "payment.paid",
  "created_at": "2026-09-18T22:40:33.872Z",
  "livemode": true,
  "data": {
    "reference_id": "pedido-1001",
    "external_transaction_id": "pedido-1001",
    "status": "PAID",
    "amount": 120.5,
    "net_amount": 117.2
  }
}
```

### HMAC Validation
```ts
import crypto from 'node:crypto'

export function verifyWebhook(rawBody, signature, timestamp, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const time = Date.parse(timestamp)
  if (typeof signature !== 'string' || !/^[a-f0-9]{64}$/.test(signature) || !Number.isFinite(time) || Math.abs(Date.now() - time) > 5 * 60 * 1000) {
    return false
  }

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  )
}
```

```

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

### Payload de Webhook de Pagamento

Source: https://waterpag.com/docs

Exemplo de payload JSON enviado para o endpoint de webhook configurado. Inclui campos como id, event, created_at, livemode e data com detalhes da transação.

```json
{
  "id": "whd_20260918224033_ab12cd34",
  "event": "payment.paid",
  "created_at": "2026-09-18T22:40:33.872Z",
  "livemode": true,
  "data": {
    "reference_id": "pedido-1001",
    "external_transaction_id": "pedido-1001",
    "status": "PAID",
    "amount": 120.5,
    "net_amount": 117.2
  }
}
```

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

### Criar Saque

Source: https://waterpag.com/docs

Submits a Pix withdrawal request using available balance. Requires a valid Pix key and reference ID.

```json
{
  "amount": 80.00,
  "reference_id": "saque-1001",
  "pix_key": "seller@empresa.com",
  "metadata": {
    "payout_id": "1001"
  }
}
```
Tokens:
Raw