> For the complete documentation index, see [llms.txt](https://docs.pagou.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagou.com.br/integracao-com-a-api/consultando-saldo.md).

# Consultando saldo

## Consultando o Saldo

A consulta de saldo na API do Pagou permite obter o saldo disponível do cliente associado à chave de API utilizada.

### Visão Geral Técnica

O endpoint <mark style="color:purple;">`GET`</mark>` ``/v1/customers/balance` retorna o saldo disponível do cliente em reais, identificado pela chave de API fornecida no cabeçalho `X-API-KEY`. A operação é síncrona, retornando `200 OK` com um corpo JSON contendo o campo balance.

**Especificações**:

* **Método**: GET
* **URL**:
  * Produção: `https://api.pagou.com.br/v1/customers/balance`
  * Sandbox: `https://sandbox-api.pagou.com.br/v1/customers/balance`
* **Autenticação**: Cabeçalho `X-API-KEY` com chave do painel.
* **Content-Type**: `application/json`
* **Resposta**: Status `200 OK` com corpo JSON contendo o saldo do cliente.
* **Erros**: `400 Bad Request`, `401 Unauthorized`, `404 Not Found`, `500 Internal Server Error`.

### Cabeçalhos

| Cabeçalho      | Valor                    | Descrição                                        |
| -------------- | ------------------------ | ------------------------------------------------ |
| `X-API-KEY`    | `sua_chave_api`          | Chave de autenticação.                           |
| `Content-Type` | `application/json`       | Formato JSON para a requisição.                  |
| `User-Agent`   | `NomeDaSuaAplicacao/1.0` | Identificador da aplicação (ex.: MinhaLoja/1.0). |

### Resposta

* **Status**: `200 OK`
* **Corpo**: JSON com o saldo disponível do cliente.

**Exemplo de Resposta**:

```json
{
  "balance": 1000.50
}
```

**Campos da Resposta**:

| Campo     | Tipo   | Descrição                                                             |
| --------- | ------ | --------------------------------------------------------------------- |
| `balance` | number | Saldo disponível do cliente em reais (ex.: 1000.50 para R$ 1.000,50). |

### Exemplos de Código

{% tabs %}
{% tab title="cURL" %}

```ruby
curl -X GET https://sandbox-api.pagou.com.br/v1/customers/balance \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaLoja/1.0"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const fetch = require('node-fetch');

// Configuração
const url = 'https://sandbox-api.pagou.com.br/v1/customers/balance';
const headers = {
    'X-API-KEY': 'sua_chave_api',
    'Content-Type': 'application/json',
    'User-Agent': 'MinhaLoja/1.0'
};

fetch(url, {
    method: 'GET',
    headers: headers
})
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); });
        }
        return response.json();
    })
    .then(data => {
        console.log(`Saldo disponível: R$ ${data.balance.toFixed(2)}`);
    })
    .catch(error => console.error('Erro na requisição:', error));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

# Configuração
url = "https://sandbox-api.pagou.com.br/v1/customers/balance"
headers = {
    "X-API-KEY": "sua_chave_api",
    "Content-Type": "application/json",
    "User-Agent": "MinhaLoja/1.0"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    print(f"Saldo disponível: R$ {data['balance']:.2f}")
except requests.RequestException as e:
    print(f"Erro na requisição: {e}")
    if e.response:
        print(f"Detalhes: {e.response.json()}")
```

{% endtab %}
{% endtabs %}

### Tratamento de Erros

| Código HTTP | Descrição             | Possível Causa                                     | Solução                                             |
| ----------- | --------------------- | -------------------------------------------------- | --------------------------------------------------- |
| 400         | Bad Request           | Requisição malformada (ex.: cabeçalhos inválidos). | Verificar formato dos cabeçalhos.                   |
| 401         | Unauthorized          | `X-API-KEY` inválido ou ausente.                   | Verificar chave.                                    |
| 500         | Internal Server Error | Erro interno da API.                               | Tentar novamente e contatar <contato@pagou.com.br>. |

**Exemplo de Resposta de Erro**:

```json
{
  "error": "Customer not found"
}
```

### Boas Práticas Técnicas

* **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições.
* **Monitoramento**: Registre todas as requisições e respostas (incluindo o valor de balance e código de status HTTP) em logs para auditoria e depuração.
* **Testes no Sandbox**: Use <https://sandbox-api.pagou.com.br/v1/customers/balance> para simular consultas de saldo sem impacto em produção.