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

# Solicitar saque

> Solicita um saque (payout) do saldo disponível da sua própria conta, enviado por Pix para a chave CNPJ da empresa.

Esta rota transfere dinheiro do saldo disponível da sua conta para a conta bancária da empresa. O saque é enviado por **Pix**, em reais, para a **chave Pix CNPJ** igual ao CNPJ cadastrado na sua conta. A solicitação nasce `pending` e depois é aprovada ou recusada. Vale para qualquer conta, com ou sem o Connect. Só os saques de subconta geram webhook, qualquer que seja a rota usada para criar. O saque da conta master ou de uma conta sem Connect não gera webhook.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Sacar o saldo da sua conta pelo seu sistema | Envie `merchantId` da sua conta, `amount`, `currency` `BRL` e `externalAccountDetails` com `type` `pix` |
| Rotina de saque periódico | Consulte o saldo em [Listar carteiras](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md) e peça o saque do valor disponível |
| Saque do saldo de uma subconta do Connect | Use [Criar saque da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md) |
| Acompanhar o saque pedido | Use [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md). Esta rota não devolve o `id` |

## Antes de chamar

* Use a chave secreta (`sk_`) em Basic ([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`.
* Não existe saque no Modo Teste. Com a chave de teste (`sk_test_`), a resposta é `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`.
* A conta precisa estar ativa, com saques habilitados e com taxa de saque configurada.
* Cadastre o CNPJ da sua conta como **chave Pix** em uma conta bancária da empresa. É para essa chave que o Pix vai, e não é possível escolher outra.
* Confira o saldo disponível em [Listar carteiras](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md): o campo `isWithdrawalEnabled` mostra se o saque está liberado na moeda.

> [!WARNING]
>
> O valor vai em **reais**: `"amount": 100` significa R\$ 100,00, e `100.50` significa R\$ 100,50. Enviar `10000` pensando em R\$ 100,00 pede um saque de R\$ 10.000,00. O valor bruto sai do saldo disponível já na criação da solicitação.

## Corpo da requisição

**merchantId** `string` *required*

ID da sua própria conta. A rota não aceita o `id` de outra conta. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

**amount** `number` *required*

Valor do saque em reais, maior que zero. Aceita casas decimais (ex.: `100.50` = R\$ 100,50). Ex.: `100`.

**currency** `string` *required*

Moeda do saque, em código ISO 4217. Use `BRL`. Um código inválido devolve `400`; um código válido que não é aceito para saque devolve `422`.

**externalAccountDetails** `object` *required*

Forma de envio do saque. Envie `{ "type": "pix" }`, sem outros campos.

**propriedades**

**type** `string` *required*

Use `pix`. O Pix vai para a chave CNPJ da sua conta.

## Respostas

A resposta de sucesso é `201` **sem corpo**: a API não devolve o `id` do saque. Para obter o `id` e acompanhar o status, chame [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) filtrando pelo `merchantId` da sua conta. A lista vem do mais recente para o mais antigo, então o saque que você acabou de pedir é o primeiro.

| HTTP | Significado | Exemplo de corpo |
| - | - | - |
| `201` | Solicitação de saque criada | sem corpo |
| `400` | Corpo inválido, com `message` em lista | `{"statusCode": 400, "message": ["..."], "error": "Bad Request"}` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Chave de teste (`WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`) ou usuário sem permissão de saque (`Acesso negado`) | `{"statusCode": 403, "message": "Acesso negado", "error": "Forbidden"}` |
| `404` | Conta não encontrada | `{"statusCode": 404, "message": "Merchant not found", "error": "Not Found"}` |
| `422` | Regra de negócio impediu o saque (mensagens abaixo) | `{"statusCode": 422, "message": "...", "error": "Unprocessable Entity"}` |

As mensagens vêm em inglês, com uma exceção em português. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.

### Mensagens do `422`

| `message` | Causa | Como resolver |
| - | - | - |
| `Insufficient balance. Required: X, Available: Y` | O saldo disponível é menor que `amount` | Consulte o saldo e peça um valor menor |
| `Maximum withdrawal amount is X` | O valor passa do limite máximo por saque configurado para a sua conta | Divida em saques menores, um de cada vez |
| `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` nessa moeda | Aguarde a decisão do saque anterior |
| `Withdrawals are disabled for this merchant` | Saques desabilitados para a conta | Fale com o suporte da Finvia |
| `Saques estão desabilitados para esta conta (saldo retido por configuração administrativa)` | A conta está com saldo retido | Fale com o suporte da Finvia |
| `Merchant account is not active` | A conta não está ativa | Fale com o suporte da Finvia |
| `Merchant settings are not configured correctly` | Configuração da conta incompleta | Fale com o suporte da Finvia |
| `Payout fees not configured` | Taxa de saque não configurada | Peça à Finvia a configuração da taxa de saque |
| `Currency X is not supported for withdrawals` | Moeda não aceita para saque | Use `BRL` |
| `You can only create withdrawal requests for your own account` | `merchantId` de outra conta | Envie o `id` da sua própria conta |
| `Payout execution failed: ...` | Falha ao executar um saque com aprovação automática | Consulte a listagem antes de tentar de novo (veja abaixo) |

> [!WARNING]
>
> Se receber `422` `Payout execution failed: ...`, **não repita o pedido de imediato**. A solicitação pode ter ficado criada como `pending`. Consulte [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) e só peça de novo se o saque não aparecer.

## Regras do saque

| Regra | Detalhe |
| - | - |
| Destino | Sempre Pix na chave CNPJ da própria conta (o mesmo CNPJ do cadastro) |
| Saldo | O saldo disponível precisa ser maior ou igual a `amount`. O valor bruto sai do saldo disponível na criação |
| Limite por saque | Há um limite máximo por saque configurado para a sua conta |
| Saques 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 |
| 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 |

### Status do saque

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

`approved` não confirma que o dinheiro já chegou à conta de destino.

> [!NOTE]
>
> A API não consulta se o CNPJ está cadastrado como chave Pix. A solicitação é criada normalmente e o Pix é enviado na aprovação. Se a chave não existir, o Pix não é concluído, e o status do saque na API não mostra essa falha (ele pode continuar `pending` ou aparecer como `approved`). Nesse caso, fale com o suporte da Finvia.

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

> [!NOTE]
>
> **Para o negócio:** antes do primeiro saque, a empresa precisa cadastrar o próprio CNPJ como chave Pix no banco. A taxa de saque é descontada do valor pedido. Transferência para conta bancária por outro meio e saque em outra moeda não fazem parte desta documentação.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chamada com chave de teste | Saques só existem em produção. Teste com um valor baixo em produção |
| `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 |
| `400` com `message` em lista | Campo ausente ou inválido no corpo (ex.: sem `externalAccountDetails`) | Envie os quatro campos obrigatórios |
| Não sei o `id` do saque | A resposta `201` não tem corpo | Liste com o `merchantId` da sua conta |
| `422` `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a decisão |
| Saque `approved` e o dinheiro não chegou | O CNPJ não está cadastrado como chave Pix | Cadastre a chave e fale com o suporte |

```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": 100,
  "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": 100,
    "currency": "BRL",
    "externalAccountDetails": { "type": "pix" }
  }'
```

```javascript Node.js theme={null}
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: 100, // R$ 100,00
    currency: 'BRL',
    externalAccountDetails: { type: 'pix' },
  }),
});

if (response.status === 201) {
  // A resposta não tem corpo. Busque o saque mais recente da conta.
  const params = new URLSearchParams({ merchantId, page: '1', size: '1' });
  const list = await fetch(`${base}/v1/payout-requests?${params}`, {
    headers: { Authorization: `Basic ${auth}` },
  }).then((r) => r.json());
  console.log('Saque criado:', list.data[0]?.id, list.data[0]?.status);
} else {
  const error = await response.json();
  console.error(response.status, error.message);
}
```

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

import requests

payload = {
    "merchantId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "amount": 100,
    "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' => 100,
    '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": 100,
              "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": 100,
  "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": 100,
	  "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" => 100,
  "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
```

```text 201 theme={null}
(sem corpo)
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Acesso negado", "error": "Forbidden" }
```

```json 422 theme={null}
{ "statusCode": 422, "message": "You already have a pending withdrawal request for this currency", "error": "Unprocessable Entity" }
```

## Veja também

> [card] [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md)
>
> Obtenha o `id` e acompanhe o status.

> [card] [Listar carteiras](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md)
>
> Saldo disponível antes do saque.

> [card] [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md)
>
> Como saldo, saque e taxas se relacionam.

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