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

# Criar saque da subconta

> A conta master solicita um saque (payout) do saldo de uma subconta, pago por Pix na chave CNPJ da própria subconta.

Esta rota cria uma solicitação de saque (payout) para uma subconta (SubMerchant) do [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md). Quem chama é a conta master, com a própria chave secreta. O valor sai do saldo disponível da subconta e é enviado por **Pix**, em reais, para a **chave Pix CNPJ da subconta**. A solicitação nasce `pending` e sempre passa por aprovação manual da operação Finvia.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| O vendedor pede para sacar o saldo pelo seu sistema | Informe o `merchantId` da subconta e o `amount` em reais |
| Repasse periódico para os vendedores | Chame a rota para cada subconta no ciclo que a sua operação definir |
| Saque do saldo da própria conta master | Passe o `id` da própria master no caminho, ou use [Solicitar saque](https://docs.fastpaybrasil.com/referencia/saques/criar.md) |
| Acompanhar um saque já pedido | Use [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) |

## Antes de chamar

* Use a chave secreta (`sk_`) **da conta master** em Basic. A conta master precisa ter o Connect habilitado pela Finvia; sem isso, a resposta é `403` `Fast Connect not enabled.`.
* 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`. Use a chave padrão da conta (do proprietário) ou uma gerada por Owner ou Manager.
* Não existe saque no Modo Teste: com a chave de teste (`sk_test_`), a resposta é `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`.
* A subconta precisa estar **ativa** (`active`), com **CNPJ** cadastrado, saques habilitados e **taxa de saque** configurada.
* O CNPJ da subconta precisa estar cadastrado como **chave Pix** em uma conta bancária da empresa. A API não confere isso na criação do saque.

> [!WARNING]
>
> O valor vai em **reais**: `"amount": 100` significa R\$ 100,00, e `100.50` significa R\$ 100,50. O mínimo é `1` (R\$ 1,00). Enviar `10000` pensando em R\$ 100,00 pede um saque de R\$ 10.000,00.

## Parâmetros de caminho

**merchantId** `string` *required*

ID da subconta que vai sacar. A conta master também pode informar o próprio `id` para sacar o próprio saldo. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

## Corpo da requisição

**amount** `number` *required*

Valor do saque em reais. Aceita casas decimais (ex.: `100.50` = R\$ 100,50). Mínimo: `1` (R\$ 1,00). Ex.: `100`.

Não há outros campos. A moeda é sempre `BRL` e o destino é sempre Pix na chave CNPJ da subconta: não é possível informar outra conta de destino.

## Respostas

**id** `string`

Identificador da solicitação de saque criada. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`. Guarde este valor: ele chega no campo `id` dos webhooks de saque e identifica o saque na listagem.

| HTTP | Significado | Exemplo de corpo |
| - | - | - |
| `201` | Solicitação de saque criada | `{"id": "2vorkDcXyvzifL63YX09S9VqcnI"}` |
| `400` | Corpo inválido, com `message` em lista | `{"statusCode": 400, "message": ["amount must not be less than 1"], "error": "Bad Request"}` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Connect não habilitado, chave de teste (`WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`) ou usuário sem permissão de saque (`Acesso negado`) | `{"statusCode": 403, "message": "Fast Connect not enabled."}` |
| `404` | Subconta inexistente ou de outra conta master | `{"statusCode": 404, "message": "SubMerchant 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. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.

### Validação do valor (`400`)

| `amount` enviado | `message` |
| - | - |
| `0` | `["amount must be a positive number", "amount must not be less than 1"]` |
| `0.5` | `["amount must not be less than 1"]` |

### Mensagens do `422`

| `message` | Causa | Como resolver |
| - | - | - |
| `SubMerchant account is not active` | A subconta não está `active` | Confira o status em [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md) |
| `SubMerchant is blocked. Withdrawals are not allowed.` | A subconta está bloqueada | Fale com o suporte da Finvia |
| `Withdrawals are disabled for this submerchant` | Saques desabilitados para a subconta | Fale com o suporte da Finvia |
| `SubMerchant CNPJ not configured` | A subconta não tem CNPJ cadastrado | Fale com o suporte da Finvia para completar o cadastro |
| `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 BRL` | O valor passa do limite máximo por saque configurado para a conta | Divida em saques menores, um de cada vez |
| `You already have a pending withdrawal request for this currency` | Já existe um saque `pending` dessa conta | Aguarde a decisão do saque anterior |
| `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 |

## Taxa e valor líquido

A taxa de saque tem uma parte fixa e uma parte percentual sobre o valor, e é descontada do valor pedido:

```text theme={null}
payoutFee = taxa fixa + (amount × taxa percentual / 100)
netAmount = amount − payoutFee
```

Com `amount` `100` e taxa de R\$ 1,00, chegam R\$ 99,00 no Pix. Na listagem e nos webhooks de saque, os valores chegam como texto decimal com 8 casas (ex.: `"99.00000000"`).

## Status e acompanhamento

**1. Solicitação criada**

A resposta `201` traz o `id`. O valor bruto sai do saldo disponível da subconta e o saque fica `pending`.

**2. Aprovação ou recusa**

A operação Finvia aprova (`approved`) ou recusa (`rejected`). Na aprovação, o Pix do valor líquido é enviado. Na recusa, o valor volta ao saldo disponível.

**3. Aviso por webhook**

Os eventos `payout.approved` e `payout.rejected` vão para os endpoints de webhook cadastrados na subconta e para os endpoints da master cadastrados com a opção de incluir subcontas. Veja [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md).

`approved` significa aprovado e enviado para pagamento. Ele não confirma que o dinheiro já chegou à conta de destino.

> [!NOTE]
>
> O Pix vai para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). A API não consulta se essa chave existe. Se o CNPJ não estiver cadastrado como chave Pix, o Pix não é concluído e o status do saque na API não mostra essa falha. 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 vendedor não receber um saque `approved`, abra um chamado com o `id` do saque.

> [!NOTE]
>
> **Para o negócio:** o vendedor precisa ter o CNPJ da empresa cadastrado como chave Pix antes do primeiro saque. A taxa de saque é descontada do valor pedido. Como todo saque de subconta passa por aprovação manual, combine com os vendedores que o dinheiro não cai na hora do pedido.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| Saque 100 vezes maior que o esperado | `amount` enviado em centavos | Envie em reais: `100` = R\$ 100,00 |
| `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chamada com chave de teste | Saques só existem em produção |
| `403` `Acesso negado` | Chave gerada por usuário com perfil Desenvolvedor | Use a chave padrão da conta master |
| `403` `Fast Connect not enabled.` | Connect não habilitado na conta master | Peça a habilitação à Finvia |
| `404` `SubMerchant not found` | `merchantId` inexistente ou de outra conta master | Confira o `id` em [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md) |
| `422` `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a aprovação ou a recusa |
| Saque `approved` e o vendedor não recebeu | O CNPJ da subconta não está cadastrado como chave Pix | Fale com o suporte da Finvia |

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

{
  "amount": 100
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/payout-requests" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100 }'
```

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

const response = await fetch(
  `https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/payout-requests`,
  {
    method: 'POST',
    headers: {
      Authorization: `Basic ${auth}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount: 100 }), // R$ 100,00
  },
);

const result = await response.json();

if (response.status === 201) {
  console.log('Saque criado:', result.id); // guarde para conciliar com payout.approved / payout.rejected
} else {
  console.error(response.status, result.message);
}
```

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

import requests

payload = {
    "amount": 100,
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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 = [
    'amount' => 100,
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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 = """
            {
              "amount": 100
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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 = """
{
  "amount": 100
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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(`{
	  "amount": 100
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/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({
  "amount" => 100,
})

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

puts response.code
puts response.body
```

```json 201 theme={null}
{ "id": "2vorkDcXyvzifL63YX09S9VqcnI" }
```

```json 400 theme={null}
{
  "statusCode": 400,
  "message": ["amount must be a positive number", "amount must not be less than 1"],
  "error": "Bad Request"
}
```

```json 403 theme={null}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
```

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

```json 422 Subconta inativa theme={null}
{ "statusCode": 422, "message": "SubMerchant account is not active", "error": "Unprocessable Entity" }
```

```json 422 Taxa não configurada theme={null}
{ "statusCode": 422, "message": "Payout fees not configured", "error": "Unprocessable Entity" }
```

## Veja também

> [card] [Saques no Connect](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
>
> Fluxo completo de saque das subcontas.

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

> [card] [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
>
> Eventos `payout.approved` e `payout.rejected`.

> [card] [Homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
>
> Cenário FC-07: saque da subconta.


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