> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultar saldos (carteiras)

> Devolve as carteiras de um merchant, uma por moeda, com saldo disponível, pendente e reservado e o equivalente em dólar.

Cada merchant tem uma carteira (wallet) por moeda. Esta rota devolve essas carteiras com três saldos: disponível (`available`), pendente (`pending`) e reservado (`reserved`). Ela também informa se o saque está habilitado em cada moeda e traz os mesmos saldos convertidos para dólar.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Mostrar o saldo no seu painel | Consulte com o `merchantId` da conta |
| Conferir se há saldo antes de pedir um saque | Leia `balance.available` e `isWithdrawalEnabled` da moeda desejada |
| Acompanhar o saldo de cada subconta em um marketplace | Consulte com o `merchantId` de cada subconta |
| Ver só uma moeda | Envie `currency`, por exemplo `BRL` |
| Ver o valor de cada venda | Use [`GET /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/listar). Esta rota mostra só os totais |

## Antes de chamar

* Use a chave secreta (`sk_`) em Basic, como no resto da API ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* A chave age com as permissões do usuário que a gerou. A chave padrão da conta pertence ao proprietário e funciona aqui. Uma chave gerada por um usuário com o perfil **Desenvolvedor** recebe `403` `Acesso negado` nesta rota.
* Tenha o `merchantId` da conta que você quer consultar: a sua própria conta ou, para a conta master do Connect, uma subconta.

## Parâmetros de consulta

**merchantId** `string` *required*

ID do merchant cujas carteiras você quer consultar. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**currency** `string`

Filtra pela moeda da carteira (código ISO 4217). Ex.: `BRL`.

## Respostas

A resposta `200` é um **array** de carteiras, sem paginação. Cada item tem os campos abaixo.

**currency** `string`

Moeda da carteira. Ex.: `BRL`.

**isWithdrawalEnabled** `boolean`

Indica se o saque está habilitado nesta moeda. Ex.: `true`.

**balance** `object`

Saldos na moeda da carteira.

**propriedades**

**available** `number`

Saldo disponível. Ex.: `1000.5`.

**pending** `number`

Saldo pendente. Ex.: `250`.

**reserved** `number`

Saldo reservado. Ex.: `100`.

**usdBalance** `object`

Os mesmos saldos convertidos para dólar (USD).

**propriedades**

**available** `number`

Saldo disponível em USD. Ex.: `200.1`.

**pending** `number`

Saldo pendente em USD. Ex.: `50`.

**reserved** `number`

Saldo reservado em USD. Ex.: `20`.

> [!NOTE]
>
> O contrato não detalha as regras que movem o valor de `pending` para `available` nem o que leva um valor a `reserved`. Para essas regras, consulte o guia de [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md) e o seu contato comercial.

> [!NOTE]
>
> **Para o negócio:** os valores estão em **reais** (na unidade da moeda): `1000.5` significa R\$ 1.000,50. Antes de pedir um saque, confira duas coisas na carteira da moeda: se `isWithdrawalEnabled` é `true` e se `balance.available` cobre o valor.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Carteiras obtidas | Array de carteiras |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Usuário dono da chave sem permissão de saldo (ex.: perfil Desenvolvedor) | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` |
| `404` | Merchant inexistente ou fora do acesso da credencial | `{"statusCode": 404, "message": "Merchant not found", "error": "Not Found"}` |

Trate o erro pelo código HTTP, não pelo texto da mensagem.

## Exemplos por caso de uso

> [tab] Saldo em reais
>
> Consulta só a carteira em BRL, para mostrar no painel.
>
> ```bash theme={null}
> curl -X GET "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL" \
>   -u "$FINVIA_API_KEY:"
> ```

> [tab] Checar antes do saque
>
> ```javascript theme={null}
> const wallets = await consultarCarteiras(merchantId, 'BRL');
> const brl = wallets.find((w) => w.currency === 'BRL');
>
> const valorDoSaque = 500; // R$ 500,00
> const podeSacar = brl && brl.isWithdrawalEnabled && brl.balance.available >= valorDoSaque;
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` `Acesso negado` | A chave foi gerada por um usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com usuário Owner ou Manager |
| `404` | `merchantId` inexistente ou fora do seu acesso | Confira o ID do merchant |
| Esperava paginação | A rota devolve um array simples | Leia a resposta como lista, sem `page` |
| Lista vazia ao filtrar por moeda | Não há carteira nessa moeda | Consulte sem `currency` para ver todas as carteiras |

## Como testar

O cenário **PAY-01** do [Roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md) pede a consulta do saldo disponível por moeda antes do saque. A consulta funciona com a chave de teste, mas o saque não: não existe saque no Modo Teste.

```http REST (JSON) theme={null}
GET /v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const params = new URLSearchParams({ merchantId: '2vorkDcXyvzifL63YX09S9VqcnI', currency: 'BRL' });

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/wallets?${params}`, {
  headers: { Authorization: `Basic ${auth}` },
});

const wallets = await response.json();
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2vorkDcXyvzifL63YX09S9VqcnI&currency=BRL")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
[
  {
    "currency": "BRL",
    "isWithdrawalEnabled": true,
    "balance": { "available": 1000.5, "pending": 250, "reserved": 100 },
    "usdBalance": { "available": 200.1, "pending": 50, "reserved": 20 }
  }
]
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Merchant not found",
  "error": "Not Found"
}
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Veja também

> [card] [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md)
>
> Como acompanhar saldo e sacar.

> [card] [Solicitar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md)
>
> Saque do saldo da própria conta, por Pix.

> [card] [Meios de pagamento](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar.md)
>
> Formas de pagamento disponíveis na conta.

> [card] [Criar saque da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md)
>
> Saque de subconta pela conta master.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.