> ## 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.

# Saldos e meios de pagamento

> Consulte o saldo da sua conta por moeda, saque o saldo disponível por Pix e descubra quais formas de pagamento estão habilitadas para o checkout.

Três tarefas do dia a dia financeiro ficam nesta página. `GET /v1/wallets` mostra o saldo da conta por moeda: quanto está disponível, quanto ainda vai ser liberado e quanto está reservado. `POST /v1/payout-requests` saca o saldo disponível por Pix para a chave CNPJ da empresa. `GET /v1/payment-methods` lista as formas de pagamento habilitadas para a conta, para montar o checkout com o que está de fato disponível.

> [!NOTE]
>
> **Para o negócio:** com o saldo e o saque pela API, o financeiro acompanha o caixa e pede saques do próprio sistema de gestão, sem entrar no painel. A Finvia oferece cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix; a lista de meios de pagamento mostra o que está habilitado na sua conta.

## Quando usar

| Situação | Rota |
| - | - |
| Mostrar o saldo num dashboard financeiro ou ERP | `GET /v1/wallets` |
| Verificar se há saldo e se o saque está habilitado antes de pedir um saque | `GET /v1/wallets` |
| Sacar o saldo disponível da sua conta | `POST /v1/payout-requests` |
| Acompanhar um saque pedido | `GET /v1/payout-requests` |
| Montar o checkout com as formas de pagamento da conta | `GET /v1/payment-methods` |
| Testar se a chave de API está funcionando | `GET /v1/payment-methods` (resposta `200` confirma a autenticação) |

O saque do saldo de uma **subconta** do Connect é outro fluxo: veja [Saques da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md).

## Como funciona

**1. Consulte o saldo**

`GET /v1/wallets?merchantId=...` devolve uma lista com uma carteira por moeda, com `available` (disponível), `pending` (a liberar) e `reserved` (reservado), e `isWithdrawalEnabled`.

**2. Peça o saque**

`POST /v1/payout-requests` com o valor em reais e `externalAccountDetails` `{ "type": "pix" }`. A resposta `201` não tem corpo.

**3. Acompanhe pela listagem**

`GET /v1/payout-requests` com o `merchantId` da sua conta traz o saque mais recente primeiro, com `status` `pending`, `approved` ou `rejected`. O saque da conta master ou de conta sem Connect não gera webhook (só os saques de subconta geram, qualquer que seja a rota usada para criar).

**4. Consulte os meios de pagamento**

`GET /v1/payment-methods` devolve as formas de pagamento habilitadas, com países e moedas aceitos.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Autenticação | As três rotas usam Basic com a chave secreta (`sk_`), como o resto da API |
| Permissão da chave | A chave age com as permissões do usuário que a gerou. Uma chave de usuário com perfil **Desenvolvedor** recebe `403` `Acesso negado` em saldo (`/v1/wallets`) e em saques (`/v1/payout-requests`). A chave padrão da conta pertence ao proprietário e funciona em todas |
| Saldo por moeda | `GET /v1/wallets` devolve uma carteira por moeda, em array e sem paginação. Exige `merchantId`; `currency` é opcional |
| Valores do saldo | Na unidade da moeda: `1000.5` em BRL é R\$ 1.000,50 |
| Saque | Só por Pix, em BRL, para a chave Pix CNPJ da própria conta |
| Modo Teste | Não existe saque com a chave de teste: `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` |
| Meios de pagamento | `GET /v1/payment-methods` aceita os filtros opcionais `merchantId` e `currency` e devolve um array sem paginação |

## Saldo: GET /v1/wallets

### Campos da resposta

| Campo | Tipo | Descrição |
| - | - | - |
| `currency` | string | Código da moeda da carteira |
| `isWithdrawalEnabled` | boolean | Se o saque está habilitado nessa moeda |
| `balance.available` | number | Saldo disponível |
| `balance.pending` | number | Saldo pendente (ainda não liberado) |
| `balance.reserved` | number | Saldo reservado |
| `usdBalance.available` | number | Saldo disponível convertido para USD |
| `usdBalance.pending` | number | Saldo pendente convertido para USD |
| `usdBalance.reserved` | number | Saldo reservado convertido para USD |

> [!NOTE]
>
> Use `available` como o valor que pode ser sacado. Um saque pedido sai do saldo disponível já na criação, mesmo antes da aprovação; se for recusado, o valor volta.

### Exemplo

```http REST (JSON) theme={null}
GET /v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q&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=2RhQg9M7ZCg3X3nMb9W1kX8Q&currency=BRL" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
// saldo.mjs (Node.js 18+, ESM)
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(
  'https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q&currency=BRL',
  { headers: { Authorization: `Basic ${auth}` } },
);

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

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/wallets?merchantId=2RhQg9M7ZCg3X3nMb9W1kX8Q&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=2RhQg9M7ZCg3X3nMb9W1kX8Q&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=2RhQg9M7ZCg3X3nMb9W1kX8Q&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=2RhQg9M7ZCg3X3nMb9W1kX8Q&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=2RhQg9M7ZCg3X3nMb9W1kX8Q&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=2RhQg9M7ZCg3X3nMb9W1kX8Q&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
```

Resposta `200`:

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

### Caso de uso: saldo num dashboard

Um ERP quer mostrar ao financeiro um cartão com o saldo do dia:

```javascript Node.js theme={null}
// painel-saldo.mjs (Node.js 18+, ESM)
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const formatBRL = (v) => v.toLocaleString('pt-BR', { style: 'currency', currency: 'BRL' });

async function getBalanceCard(merchantId) {
  const res = await fetch(
    `https://api-global.fastpaybrasil.com/v1/wallets?merchantId=${merchantId}&currency=BRL`,
    { headers: { Authorization: `Basic ${auth}` } },
  );
  const [brl] = await res.json();
  if (!brl) return null;

  return {
    disponivel: formatBRL(brl.balance.available), // "R$ 1.000,50"
    aLiberar: formatBRL(brl.balance.pending),      // "R$ 250,00"
    reservado: formatBRL(brl.balance.reserved),    // "R$ 100,00"
    podeSacar: brl.isWithdrawalEnabled && brl.balance.available > 0,
  };
}

console.log(await getBalanceCard('2RhQg9M7ZCg3X3nMb9W1kX8Q'));
```

> [!TIP]
>
> **Para o desenvolvedor:** a resposta é um array. Se a conta não tem carteira na moeda filtrada, o array pode vir vazio. Trate esse caso antes de ler `balance`.

## Saque da própria conta: POST /v1/payout-requests

O saque transfere o saldo disponível da sua conta para a conta bancária da empresa, por **Pix**, na **chave Pix CNPJ** igual ao CNPJ do cadastro. Vale para qualquer conta, com ou sem Connect.

> [!WARNING]
>
> O saque é enviado por Pix para a chave CNPJ da sua conta (o mesmo CNPJ do cadastro). Antes de solicitar saques, cadastre esse CNPJ como chave Pix em uma conta bancária da empresa. Não é possível escolher outra chave. Se a chave não existir, o Pix não é concluído; nesse caso, fale com o suporte.

O desenho abaixo mostra o caminho de um saque da própria conta, do saldo consultado ao Pix na chave CNPJ.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    GW(["GET /v1/wallets<br/>saldo por moeda"]):::lojista
    AV["available<br/>saldo disponível,<br/>é o que pode ser sacado"]:::ok
    PR["pending e reserved<br/>a liberar e reservado,<br/>não podem ser sacados"]:::neutro
    POST["POST /v1/payout-requests<br/>amount em reais, BRL,<br/>externalAccountDetails pix"]:::lojista
    R{"Resposta<br/>da criação"}:::decisao
    E403["403 · não existe<br/>saque no Modo Teste"]:::erro
    E422["422: saldo insuficiente,<br/>acima do limite ou já<br/>há saque pending"]:::erro
    PEN["201 sem corpo · pending<br/>o valor bruto já saiu<br/>do disponível"]:::alerta
    LST["GET /v1/payout-requests<br/>traz o id e o status<br/>webhook só em subconta"]:::lojista
    OP["Operação Finvia decide<br/>ou aprovação automática<br/>do Pix"]:::finvia
    APR["approved<br/>Pix do valor líquido:<br/>amount menos a taxa"]:::ok
    CNPJ[("Chave Pix CNPJ<br/>da própria conta")]:::externo
    REJ["rejected<br/>o valor volta ao<br/>saldo disponível"]:::erro
    GW --> AV
    GW --> PR
    AV -->|"valor a sacar"| POST --> R
    R -->|"chave de teste"| E403
    R -->|"regra violada"| E422
    R -->|"201"| PEN
    PEN -.-> LST
    PEN --> OP
    OP -->|"aprova"| APR --> CNPJ
    OP -->|"recusa"| REJ
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef erro fill:#FDECEC,stroke:#B42318,stroke-width:1.5px,color:#7A1209
    classDef alerta fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

### Regras

| Regra | Detalhe |
| - | - |
| Corpo | `merchantId` (a sua própria conta), `amount` em reais, `currency` `BRL` e `externalAccountDetails` `{ "type": "pix" }` |
| Valor | Em **reais**, maior que zero: `100.50` é R\$ 100,50 |
| Saldo | O saldo disponível precisa ser maior ou igual a `amount`. O valor bruto sai do saldo disponível já na criação |
| Limite | Há um limite máximo por saque configurado para a sua conta (`422` `Maximum withdrawal amount is X`) |
| Pendentes | Por padrão, só um saque `pending` por moeda. A operação Finvia pode liberar mais de um para a conta |
| Taxa | A taxa de saque da conta (fixa + percentual) é descontada: o valor transferido é `amount` menos a taxa |
| Aprovação | O saque nasce `pending` e é aprovado ou recusado pela operação. A conta pode ter aprovação automática do Pix configurada |
| Resposta | `201` **sem corpo**. Para obter o `id`, use a listagem |
| Aviso | Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de conta sem Connect não gera webhook: acompanhe pela listagem |

### Exemplo

```http REST (JSON) theme={null}
POST /v1/payout-requests HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "amount": 500,
  "currency": "BRL",
  "externalAccountDetails": {
    "type": "pix"
  }
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/payout-requests" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "amount": 500,
    "currency": "BRL",
    "externalAccountDetails": { "type": "pix" }
  }'
```

```javascript Node.js theme={null}
// saque.mjs (Node.js 18+, ESM)
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const base = 'https://api-global.fastpaybrasil.com';
const merchantId = '2RhQg9M7ZCg3X3nMb9W1kX8Q';

const response = await fetch(`${base}/v1/payout-requests`, {
  method: 'POST',
  headers: { Authorization: `Basic ${auth}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    merchantId,
    amount: 500, // R$ 500,00
    currency: 'BRL',
    externalAccountDetails: { type: 'pix' },
  }),
});

if (response.status !== 201) {
  const erro = await response.json();
  throw new Error(`${response.status}: ${erro.message}`);
}

// 201 sem corpo: o saque mais recente da conta é o que acabou de ser criado
const lista = await fetch(`${base}/v1/payout-requests?merchantId=${merchantId}&page=1&size=1`, {
  headers: { Authorization: `Basic ${auth}` },
}).then((r) => r.json());

const saque = lista.data[0];
console.log(saque.id, saque.status, Number(saque.amount) - Number(saque.payoutFee)); // valores chegam como texto
```

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

import requests

payload = {
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "amount": 500,
    "currency": "BRL",
    "externalAccountDetails": {
        "type": "pix",
    },
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/payout-requests",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

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

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

$payload = [
    'merchantId' => '2RhQg9M7ZCg3X3nMb9W1kX8Q',
    'amount' => 500,
    'currency' => 'BRL',
    'externalAccountDetails' => [
        'type' => 'pix',
    ],
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/payout-requests');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$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());

        String payload = """
            {
              "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
              "amount": 500,
              "currency": "BRL",
              "externalAccountDetails": {
                "type": "pix"
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payout-requests"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .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 payload = """
{
  "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "amount": 500,
  "currency": "BRL",
  "externalAccountDetails": {
    "type": "pix"
  }
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/payout-requests");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

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"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
	  "amount": 500,
	  "currency": "BRL",
	  "externalAccountDetails": {
	    "type": "pix"
	  }
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/payout-requests", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	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 "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/payout-requests")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "merchantId" => "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "amount" => 500,
  "currency" => "BRL",
  "externalAccountDetails" => {
    "type" => "pix",
  },
})

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

puts response.code
puts response.body
```

### Acompanhe o status

`GET /v1/payout-requests` com o `merchantId` da sua conta mostra cada saque com `status`:

| Status | O que significa |
| - | - |
| `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda decisão |
| `approved` | Aprovado e enviado para pagamento. O Pix do valor líquido é enviado nesse momento |
| `rejected` | Recusado. O valor volta ao saldo disponível |

Na listagem, `amount` e `payoutFee` chegam como texto decimal com 8 casas (ex.: `"500.00000000"`). Converta antes de calcular. Veja todos os filtros em [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md).

> [!WARNING]
>
> Se a criação responder `422` `Payout execution failed: ...` (acontece só com aprovação automática), não repita o pedido de imediato. A solicitação pode ter ficado criada como `pending`. Consulte a listagem antes de tentar de novo.

**Em validação (V-49):** o suporte está definindo o procedimento quando o Pix do saque falha (prazo e como o saldo volta). A API não confere se o CNPJ está cadastrado como chave Pix, e o status do saque não mostra essa falha. Enquanto isso, se o valor de um saque não chegar, abra um chamado com o `id` do saque.

## Meios de pagamento: GET /v1/payment-methods

### Regras

| Regra | Detalhe |
| - | - |
| Parâmetros | Ambos opcionais: `merchantId` e `currency` |
| Formato da resposta | **Array**, sem paginação |
| Autenticação | Basic, com a chave secreta (`sk_`) |

### Campos da resposta

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | Identificador do meio de pagamento |
| `name` | string | Nome técnico |
| `countries` | string\[] | Países em que o meio está disponível (ISO alpha-3, ex.: `BRA`) |
| `currencies` | string\[] | Moedas aceitas |
| `description` | string | Nome para exibir na interface |

### Exemplo

```http REST (JSON) theme={null}
GET /v1/payment-methods?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/payment-methods?currency=BRL" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL', {
  headers: { Authorization: `Basic ${credentials}` },
});

const methods = await response.json();
console.log(methods);
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/payment-methods?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/payment-methods?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/payment-methods?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/payment-methods?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/payment-methods?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/payment-methods?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
```

Resposta `200` (exemplo ilustrativo; os valores dependem da sua conta):

```json theme={null}
[
  {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "name": "pix",
    "countries": ["BRA"],
    "currencies": ["BRL"],
    "description": "Pix"
  }
]
```

### Caso de uso: checkout dinâmico

Neste exemplo, o checkout consulta a lista na abertura da página e mostra só o que a conta aceita para a moeda e o país do pedido:

```javascript Node.js theme={null}
// opcoes-checkout.mjs (Node.js 18+, ESM)
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

async function getCheckoutOptions({ currency, country }) {
  const res = await fetch(
    `https://api-global.fastpaybrasil.com/v1/payment-methods?currency=${currency}`,
    { headers: { Authorization: `Basic ${credentials}` } },
  );
  const methods = await res.json();

  return methods
    .filter((m) => m.countries.includes(country))
    .map((m) => ({ value: m.name, label: m.description }));
}

// Pedido em reais de um cliente no Brasil
const options = await getCheckoutOptions({ currency: 'BRL', country: 'BRA' });
console.log(options);
```

> [!TIP]
>
> **Para o desenvolvedor:** você pode guardar a lista em cache por alguns minutos para não consultar a API a cada visita ao checkout. Defina o tempo de cache conforme a sua operação: a documentação não informa com que frequência a lista muda.

> [!NOTE]
>
> A documentação não fixa o valor de `name` para Pix e cartão de crédito nessa lista. Ao mapear `name` para o `paymentMethod.type` de `POST /v1/charges`, confira os valores que a sua conta devolve.

## Erros comuns

| Rota | Sintoma | Causa | Como resolver |
| - | - | - | - |
| Todas | `401` `Unauthorized` | Chave inválida ou Basic no formato errado | Confira o Basic com a chave secreta e os dois-pontos no fim |
| `wallets`, `payout-requests` | `403` `Acesso negado` | Chave gerada por usuário com perfil Desenvolvedor | Use a chave padrão da conta ou gere uma com usuário Owner ou Manager |
| `payout-requests` (criação) | `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chave de teste | Saques só existem em produção |
| `payout-requests` (criação) | `422` `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que o valor | Consulte o saldo e peça um valor menor |
| `payout-requests` (criação) | `422` `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a decisão do saque anterior |
| `payout-requests` (criação) | `422` `You can only create withdrawal requests for your own account` | `merchantId` de outra conta | Envie o `id` da sua conta |
| `wallets` | `404` `Merchant not found` | `merchantId` inexistente ou fora do acesso da credencial | Confira o ID do merchant |
| `wallets` | Resposta vazia | Sem carteira na moeda filtrada | Remova o filtro `currency` e confira as moedas disponíveis |

Mais mensagens de erro do saque em [Solicitar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md).

## Perguntas frequentes

> [accordion] Qual saldo posso sacar?
>
> O valor de `balance.available`, desde que `isWithdrawalEnabled` seja `true` para a moeda e o valor respeite o limite por saque da conta. `pending` e `reserved` não estão disponíveis para saque.

> [accordion] Posso sacar para outra chave Pix ou por transferência bancária?
>
> Não. O saque publicado nesta documentação é só por Pix, para a chave CNPJ da própria conta.

> [accordion] Como sei o id do saque que pedi?
>
> A criação responde `201` sem corpo. Liste `GET /v1/payout-requests` com o `merchantId` da sua conta: a lista vem do mais recente para o mais antigo.

> [accordion] Por que o saldo vem também em USD?
>
> O objeto `usdBalance` traz os mesmos três valores convertidos para dólar, o que ajuda a ver o total numa base única.

> [accordion] Posso usar a mesma chave secreta nas três rotas?
>
> Sim. As três usam Basic com a chave secreta. Só confirme que a chave não foi gerada por um usuário com perfil Desenvolvedor, que não acessa saldo nem saques.

## Como testar

| Código | Cenário | O que comprovar |
| - | - | - |
| PAY-01 | Consultar o saldo antes do saque | `GET /v1/wallets` com `merchantId` devolve o saldo por moeda e `isWithdrawalEnabled` |
| PAY-02 | Montar o saque via Pix | Corpo com `merchantId`, `amount` em reais, `currency` `BRL` e `externalAccountDetails.type` `pix`; `201` sem corpo tratado, com o `id` buscado na listagem |
| PAY-03 a PAY-05 | Saldo insuficiente, limite e saque pendente | Tratamento dos `422` correspondentes |
| PAY-06 | Acompanhar o status | Leitura de `pending`, `approved` e `rejected` na listagem |
| PAY-07 | Valor em reais | O fluxo envia o valor em reais |

Como não existe saque no Modo Teste, os cenários de saque são conferidos no código e na montagem da requisição. Detalhes no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md). A consulta de meios de pagamento também é a forma mais simples de validar a chave, como mostrado em [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md).

## Veja também

> [card] [Listar carteiras](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md)
>
> Contrato completo de GET /v1/wallets.

> [card] [Solicitar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md)
>
> Contrato completo de POST /v1/payout-requests.

> [card] [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md)
>
> Filtros e status dos saques.

> [card] [Listar meios de pagamento](https://docs.fastpaybrasil.com/referencia/meios-de-pagamento/listar.md)
>
> Contrato completo de GET /v1/payment-methods.


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