# Saldo e saques

Consultar o saldo disponível e transferir para uma chave PIX.

Consultar quanto você tem e transferir para uma chave PIX sua, direto pela API.

## Consultar o saldo

`GET /v1/balance`

_Requisição_

```bash
curl https://novexfinance.com.br/api/v1/balance \
  -H "Authorization: Bearer $NOVEX_API_KEY"
```

```php
$balance = $novex->get('/balance');

printf("Disponível: R$ %s\n", number_format($balance['available'] / 100, 2, ',', '.'));
```

```js
const balance = await novex.get('/balance');

console.log((balance.available / 100).toLocaleString('pt-BR', {
  style: 'currency', currency: 'BRL',
}));
```

```python
balance = novex.get('/balance')

print(f'Disponível: R$ {balance["available"] / 100:.2f}')
```

_Resposta 200_

```json
{
  "object": "balance",
  "currency": "BRL",
  "available": 458720,
  "pending": 129900,
  "total": 588620,
  "as_of": "2026-08-07T14:32:10-03:00"
}
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `available` opcional | inteiro | Já liquidado e livre para saque, em centavos. |
| `pending` opcional | inteiro | Pago pelo cliente, mas ainda dentro do prazo de liquidação. Vira `available` na data. |
| `total` opcional | inteiro | Soma dos dois. |
| `as_of` opcional | data | Momento em que o saldo foi calculado. |

### Prazos de liquidação

| Meio | Fica disponível |
| --- | --- |
| **PIX** | Imediatamente após a confirmação. |
| **Boleto** | Imediatamente após a compensação — que já ocorreu antes de o status virar `paid`. |
| **Cartão de crédito** | D+30 corridos a partir da aprovação. |

Cada cobrança traz o campo `available_at` com a data exata em que aquele valor específico entra no disponível.

> ℹ️ O saldo já vem **líquido**: a taxa é descontada no momento do pagamento e congelada na cobrança. Os campos `fee_amount` e `net_amount` de cada cobrança mostram exatamente quanto foi cobrado e quanto entrou.

## Solicitar um saque

`POST /v1/withdrawals`

_Requisição_

```bash
curl -X POST https://novexfinance.com.br/api/v1/withdrawals \
  -H "Authorization: Bearer $NOVEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: saque-2026-08-07-01" \
  -d '{
    "amount": 100000,
    "pix_key_type": "cnpj",
    "pix_key": "11222333000181",
    "reference": "saque-mensal-agosto"
  }'
```

```php
$saque = $novex->post('/withdrawals', [
    'amount'       => 100000, // R$ 1.000,00
    'pix_key_type' => 'cnpj',
    'pix_key'      => '11222333000181',
    'reference'    => 'saque-mensal-agosto',
], 'saque-2026-08-07-01');
```

```js
const saque = await novex.post('/withdrawals', {
  amount: 100000, // R$ 1.000,00
  pix_key_type: 'cnpj',
  pix_key: '11222333000181',
  reference: 'saque-mensal-agosto',
}, { idempotencyKey: 'saque-2026-08-07-01' });
```

```python
saque = novex.post('/withdrawals', {
    'amount': 100000,  # R$ 1.000,00
    'pix_key_type': 'cnpj',
    'pix_key': '11222333000181',
    'reference': 'saque-mensal-agosto',
}, idempotency_key='saque-2026-08-07-01')
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `amount` obrigatório | inteiro | Valor a **receber**, em centavos. Mínimo `500` (R$ 5,00). A taxa é debitada por cima. |
| `pix_key_type` obrigatório | string | `cpf`, `cnpj`, `phone`, `email` ou `evp` (chave aleatória). |
| `pix_key` obrigatório | string | A chave. CPF/CNPJ/telefone: só dígitos (aceitamos com pontuação e normalizamos). |
| `reference` opcional | string | Seu identificador para o saque. |

_Resposta 201_

```json
{
  "object": "withdrawal",
  "id": "wd_1c7fa03e95b846d2f0ba",
  "status": "pending",
  "amount": 100000,
  "fee_amount": 200,
  "total_debited": 100200,
  "currency": "BRL",
  "pix_key": "**********0181",
  "pix_key_type": "cnpj",
  "end_to_end_id": null,
  "processed_at": null,
  "created_at": "2026-08-07T14:32:10-03:00"
}
```

> ℹ️ **O valor pedido é o valor recebido.** A taxa sai por cima: pedindo `100000` com taxa de `200`, chegam R$ 1.000,00 no destino e saem R$ 1.002,00 do seu saldo. É o `total_debited` que precisa caber no `available`.

### Saldo insuficiente

O saldo é conferido **antes** de qualquer transferência ser iniciada:

_Resposta 422_

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "Saldo insuficiente. Necessário R$ 1.002,00 (valor R$ 1.000,00 + taxa R$ 2,00). Disponível: R$ 458,72.",
    "request_id": "a3f1c09b7e42d85610fb2c7d9a4e5b83"
  }
}
```

## Acompanhar o saque

`GET /v1/withdrawals/{id}`

`GET /v1/withdrawals`

| Status | Significa |
| --- | --- |
| `pending` | Solicitado, aguardando processamento. |
| `approved` | Aprovado, ainda não transferido. |
| `processing` | Transferência em andamento. |
| `paid` | Concluído. O valor chegou na conta de destino. |
| `rejected` | Recusado. Verifique a chave PIX. |
| `failed` | Falhou. O valor volta para o seu saldo. |
| `canceled` | Cancelado. O valor volta para o seu saldo. |

Cadastre um [webhook](https://novexfinance.com.br/docs/webhooks) para receber `withdrawal.paid` e `withdrawal.failed` sem precisar consultar.

> ℹ️ Nas consultas, a `pix_key` vem **mascarada** — só os 4 últimos caracteres. A chave completa você já tem: foi você quem enviou. Repeti-la em toda listagem só espalharia dado pessoal sem necessidade.

## Cuidado com automação de saque

> 🚫 **A chave de API pode solicitar saques.** Se ela vazar, o dinheiro sai. Antes de automatizar saque:
> 
> - Use uma chave dedicada, guardada em cofre de segredos, separada da chave que cria cobranças.
> - Rode a rotina de saque num serviço isolado, sem acesso da internet.
> - Sempre com `Idempotency-Key` — sem ela, uma retentativa após timeout faz o saque sair duas vezes.
> - Monitore `withdrawal.paid` e reconcilie com o que você solicitou.


---

Documentação completa: https://novexfinance.com.br/docs/saldo-e-saques
Base da API: https://novexfinance.com.br/api/v1