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

# Saques da subconta

> A conta master solicita o saque do saldo de cada subconta, enviado por Pix para a chave CNPJ dela, com taxa calculada na criação e aviso de aprovação ou recusa.

Com o Connect, a conta master solicita o saque (payout) do saldo disponível de cada subconta. O dinheiro vai por Pix para a **chave Pix CNPJ da própria subconta**, sempre em reais. A taxa de saque é calculada na criação do pedido, todo saque de subconta passa por aprovação manual da operação Finvia, e o resultado chega por webhook e pela listagem.

## Quando usar

* **Vendedor de marketplace** que quer retirar o que vendeu: a sua plataforma oferece um botão "sacar" e cria o pedido pela API.
* **Repasse periódico** a lojistas de um PSP: a sua aplicação cria pedidos de saque conforme a regra combinada com cada lojista.
* **Painel financeiro do vendedor**: a sua plataforma lista os saques com status, taxa e [valor líquido](https://docs.fastpaybrasil.com/glossario.md) (o valor do saque menos a taxa).

Esta página trata do saque de **subconta**. O saque do saldo da própria conta (master ou não) usa [`POST /v1/payout-requests`](https://docs.fastpaybrasil.com/referencia/saques/criar) e está em [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md). A master também pode sacar o próprio saldo pela rota de subconta, passando o próprio `id` no caminho.

## Como funciona

O desenho abaixo mostra um saque de subconta do pedido ao aviso, com os dois resultados possíveis.

```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}}}%%
sequenceDiagram
    autonumber
    box rgb(243,245,248) Sua aplicação
        participant APP as Seu servidor (master)
        participant WH as Seu receptor de webhooks
    end
    box rgb(234,243,255) Finvia
        participant API as Finvia API
        participant OP as Operação Finvia
    end
    box rgb(244,240,255) Fora da Finvia
        participant BCO as Banco da subconta (chave Pix CNPJ)
    end
    APP->>API: POST /v1/submerchants/{merchantId}/payout-requests · amount 1500 (em reais)
    Note over API: Confere subconta, saldo e limite · calcula a taxa · valor bruto sai do saldo
    API-->>APP: 201 · só o id do pedido (nasce pending)
    API->>OP: Pedido aguarda decisão manual
    alt aprovado
        OP->>API: approved
        API->>BCO: Pix do valor líquido (amount menos payoutFee)
        API-)WH: Webhook payout.approved · netAmount
    else recusado
        OP->>API: rejected
        Note over API: Valor volta ao saldo disponível
        API-)WH: Webhook payout.rejected · rejectionReason
    end
    WH->>API: GET /v1/payout-requests · filtro merchantId
    API-->>WH: status approved ou rejected
```

O webhook de saque não tem assinatura: confirme o status pela listagem antes de agir, como no último passo do desenho.

**1. Pedido de saque**

Sua aplicação chama `POST /v1/submerchants/{merchantId}/payout-requests` com a chave secreta da conta master e o valor em reais.

**2. Validação e reserva do valor**

A Finvia confere a subconta (ativa, sem bloqueio, com CNPJ e saques habilitados), o saldo disponível e o limite por saque, calcula a taxa de saque (fixa mais percentual) e cria o pedido com status `pending`. O valor bruto sai do saldo disponível nesse momento. A resposta traz o `id` do pedido.

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

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

**4. Aviso**

Os webhooks `payout.approved` e `payout.rejected` vão para os endpoints cadastrados na subconta e para os endpoints da master cadastrados com a opção de incluir subcontas.

## Pré-requisitos

| O que precisa estar pronto | Como você percebe se faltar |
| - | - |
| Módulo Connect habilitado pela Finvia na conta master | `403` com `Fast Connect not enabled.` |
| Chave da master gerada por usuário com permissão de saque (a chave padrão da conta serve) | `403` com `Acesso negado` (ex.: perfil Desenvolvedor) |
| Chave de produção | `403` com `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` com a chave de teste |
| Subconta vinculada à sua conta master | `404` com `SubMerchant not found` |
| Subconta com status `active` e sem bloqueio | `422` com `SubMerchant account is not active` ou `SubMerchant is blocked. Withdrawals are not allowed.` |
| CNPJ cadastrado na subconta | `422` com `SubMerchant CNPJ not configured` |
| Taxa de saque configurada pela Finvia | `422` com `Payout fees not configured` |
| CNPJ da subconta cadastrado como **chave Pix** em uma conta bancária da empresa | A API não confere. Sem a chave, o Pix não é concluído |
| Endpoints de webhook na subconta, ou na master com a opção de incluir subcontas | Nenhum aviso chega |

> [!NOTE]
>
> **Para o negócio:** o saque é enviado por Pix para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). Antes de liberar o saque, cada vendedor precisa cadastrar esse CNPJ como chave Pix em uma conta bancária da empresa; não é possível escolher outra chave. A taxa de saque é uma condição comercial definida com a Finvia: mostre ao vendedor quanto ele vai receber já descontada a taxa.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Valor | Em **reais**, com casas decimais: `100` = R\$ 100,00 e `100.50` = R\$ 100,50 |
| Mínimo | R\$ 1,00 por saque (`amount` mínimo `1`) |
| Máximo | Limite máximo por saque configurado para a conta (`422` `Maximum withdrawal amount is X BRL`) |
| Moeda | Sempre `BRL` |
| Destino | Sempre Pix, na chave CNPJ da subconta |
| Saldo | O saldo disponível precisa cobrir o valor. O valor bruto sai do saldo na criação |
| Pendentes | Só um saque `pending` por vez, por moeda (`422` `You already have a pending withdrawal request for this currency`) |
| Taxa | Calculada na criação: taxa fixa mais percentual sobre o valor pedido |
| Aprovação | Sempre manual, pela operação Finvia |
| Modo Teste | Não existe saque com a chave de teste (`403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`) |
| Aviso | Webhook para os endpoints da subconta e para os da master com a opção de incluir subcontas |

> [!WARNING]
>
> O valor vai em **reais**. Enviar `10000` pensando em R\$ 100,00 cria um pedido de saque de R\$ 10.000,00.

## Cálculo da taxa

A taxa é calculada automaticamente quando o pedido é criado:

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

Exemplo com uma taxa ilustrativa de R\$ 2,00 fixa mais 0,5%, em um saque de R\$ 1.500,00:

| Etapa | Conta | Resultado |
| - | - | - |
| Parte percentual | 1.500 × 0,5 ÷ 100 | R\$ 7,50 |
| Taxa total | 2,00 + 7,50 | R\$ 9,50 |
| Valor líquido | 1.500,00 − 9,50 | R\$ 1.490,50 |

Na listagem e nos webhooks, os valores chegam como **texto decimal com 8 casas**, em reais: `amount` `"1500.00000000"`, `payoutFee` `"9.50000000"` e, no webhook, `netAmount` `"1490.50000000"`. Converta para número antes de calcular e não divida por 100.

## Status do saque

| Status | Significado |
| - | - |
| `pending` | Pedido criado. 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. `processedAt` é preenchido |
| `rejected` | Recusado. O valor volta ao saldo disponível. `rejectionReason` e `processedAt` são preenchidos |

`approved` significa aprovado e enviado para pagamento. O dinheiro pode ainda não ter chegado à conta de destino.

O desenho abaixo mostra o ciclo de status do pedido de saque e o que acontece com o saldo em cada etapa.

```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
    INI(["Pedido de saque<br/>amount em reais"]):::lojista
    VAL{"Passou nas<br/>validações?"}:::decisao
    ERR["Erro 400, 403, 404 ou 422<br/>nenhum saque é criado"]:::erro
    PEN["pending<br/>pendente<br/>valor bruto sai do saldo"]:::alerta
    APR["approved<br/>aprovado"]:::ok
    REJ["rejected<br/>recusado"]:::erro
    PIX["Pix do valor líquido<br/>para a chave CNPJ"]:::externo
    VOLTA["Valor volta ao<br/>saldo disponível"]:::neutro
    EVA[["payout.approved"]]:::evento
    EVR[["payout.rejected<br/>com rejectionReason"]]:::evento
    INI --> VAL
    VAL -->|"não"| ERR
    VAL -->|"sim · 201 com id"| PEN
    PEN -->|"operação Finvia aprova"| APR
    PEN -->|"operação Finvia recusa"| REJ
    APR ==> PIX
    REJ --> VOLTA
    APR -.->|"webhook"| EVA
    REJ -.->|"webhook"| EVR
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    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
```

Os webhooks só existem para saques de subconta. O saque da própria conta (master ou não) não gera webhook: acompanhe pela listagem.

## Passo a passo

### 1. Crie o pedido de saque

```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": 1500
}
```

```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": 1500 }'
```

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

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

const result = await response.json();
if (response.status === 201) {
  console.log('Saque criado:', result.id); // guarde o id para conciliar com o webhook
} else {
  console.error(response.status, result.message); // ex.: "SubMerchant account is not active"
}
```

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

import requests

payload = {
    "amount": 1500,
}

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' => 1500,
];

$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": 1500
            }
            """;

        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": 1500
}
""";

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": 1500
	}`)

	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" => 1500,
})

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

puts response.code
puts response.body
```

Resposta `201`:

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

### 2. Acompanhe pela listagem

`GET /v1/payout-requests` lista os pedidos, do mais recente para o mais antigo. Para a conta master, a lista inclui os saques das subcontas; filtre por `merchantId` para ver uma conta só.

| Filtro | Uso |
| - | - |
| `merchantId` | Pedidos de uma conta (sua ou de uma subconta) |
| `status` | `pending`, `approved` ou `rejected` |
| `currency` | Moeda (ex.: `BRL`) |
| `createdAtStart`, `createdAtEnd` | Período de criação, datas inclusivas no formato `AAAA-MM-DD` |
| `page`, `size` | Página (padrão `1`) e itens por página (padrão `10`) |

A API ignora parâmetros desconhecidos sem erro: filtros como `createdAt` ou `processedAt` não existem e não filtram nada.

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/payout-requests?merchantId=36OO3bcGjhPjjF3tzrqOGcmQuKo&status=pending&page=1&size=20" \
  -u "$FINVIA_API_KEY:"
```

```json 200 theme={null}
{
  "data": [
    {
      "id": "2vorkDcXyvzifL63YX09S9VqcnI",
      "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
      "amount": "1500.00000000",
      "currency": "BRL",
      "status": "pending",
      "payoutFee": "9.50000000",
      "externalAccountDetails": {
        "type": "pix",
        "pix_key": "11222333000181"
      },
      "processedAt": null,
      "createdAt": "2026-10-20T18:45:52.988Z",
      "merchantLegalName": "LOJA EXEMPLO LTDA",
      "merchantEmail": "financeiro@lojaexemplo.com.br"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1,
  "pendingCount": 1
}
```

`pendingCount` traz o total de pedidos `pending` com os mesmos filtros (sem considerar o filtro `status`), útil para um indicador de "saques aguardando" no seu painel. A listagem não traz `netAmount` nem `rejectionReason`: o líquido é `amount` menos `payoutFee`, e o motivo da recusa chega no webhook `payout.rejected`. A listagem é a única forma de consultar saques: não há consulta individual para contas merchant.

### 3. Receba o aviso de aprovação ou recusa

Quando o pedido é aprovado ou recusado, a Finvia envia um webhook:

| Evento | Quando |
| - | - |
| `payout.approved` | O saque foi aprovado e o Pix do valor líquido foi enviado para pagamento |
| `payout.rejected` | O saque foi recusado. O motivo vem em `data.rejectionReason` |

Não há evento de criação de saque.

```json payout.rejected theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "event": "payout.rejected",
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "amount": "100.00000000",
    "currency": "BRL",
    "status": "rejected",
    "payoutFee": "1.00000000",
    "netAmount": "99.00000000",
    "rejectionReason": "Documentação incompleta"
  }
}
```

O `id` da raiz é o `id` do saque, igual a `data.id`, e se repete nos eventos do mesmo saque: use `id` + `event` para descartar avisos repetidos. Os webhooks de saque usam camelCase e não têm `livemode`.

> [!WARNING]
>
> Os avisos de saque vão para os endpoints de webhook cadastrados na subconta e também para os endpoints da master cadastrados com a opção de incluir subcontas (no painel, em **Configurações** > **Webhooks** da conta selecionada). O webhook de saque não tem cabeçalho de assinatura: confirme o status pela listagem antes de agir. Saque da própria conta (master ou não) não gera webhook.

**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; se não estiver, o Pix não é concluído e o status do saque não mostra a falha (ele pode continuar `pending` ou aparecer como `approved`). Enquanto isso, se o vendedor não receber, abra um chamado com o `id` do saque.

Formato completo e exemplo de implementação em [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md).

## Erros comuns

| HTTP | Mensagem | Causa | Como resolver |
| - | - | - | - |
| `400` | `["amount must be a positive number", "amount must not be less than 1"]` | Valor ausente, zero ou abaixo de R\$ 1,00 | Envie `amount` a partir de `1` |
| `401` | `Unauthorized` | Chave ausente ou inválida | Confira a chave e o formato do Basic |
| `403` | `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` | Chave de teste | Saques só existem em produção |
| `403` | `Acesso negado` | Chave de usuário sem permissão de saque (ex.: Desenvolvedor) | Use a chave padrão da conta master |
| `403` | `Fast Connect not enabled.` | Módulo não habilitado na conta master | Peça a liberação à Finvia |
| `404` | `SubMerchant not found` | Subconta inexistente ou de outra conta master | Confira o `merchantId` |
| `422` | `SubMerchant account is not active` | Subconta não está `active` | Aguarde a aprovação ou verifique o status |
| `422` | `SubMerchant is blocked. Withdrawals are not allowed.` | Subconta bloqueada | Fale com a Finvia |
| `422` | `Withdrawals are disabled for this submerchant` | Saques desabilitados para a subconta | Fale com a Finvia |
| `422` | `SubMerchant CNPJ not configured` | Subconta sem CNPJ cadastrado | Fale com a Finvia para completar o cadastro |
| `422` | `Insufficient balance. Required: X, Available: Y` | Saldo disponível menor que o valor | Peça um valor menor |
| `422` | `Maximum withdrawal amount is X BRL` | Valor acima do limite por saque | Divida em saques menores, um de cada vez |
| `422` | `You already have a pending withdrawal request for this currency` | Saque anterior ainda pendente | Aguarde a decisão |
| `422` | `Merchant settings are not configured correctly` | Configuração da conta incompleta | Fale com a Finvia |
| `422` | `Payout fees not configured` | Taxa de saque não configurada | Peça à Finvia a configuração da taxa de saque |
| Saque muito maior que o pretendido | | Valor enviado em centavos | Envie em reais |

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

## Perguntas frequentes

> [accordion] Posso escolher outra chave Pix ou uma conta bancária?
>
> Não. O destino é sempre a chave Pix CNPJ da subconta. Na listagem, isso aparece em `externalAccountDetails` como `{ "type": "pix", "pix_key": "<CNPJ>" }`.

> [accordion] Qual é o valor mínimo de saque?
>
> R\$ 1,00. O campo `amount` aceita casas decimais, como `100.50` para R\$ 100,50.

> [accordion] Quanto tempo leva para o dinheiro cair?
>
> O saque de subconta passa por aprovação manual da operação Finvia. O Pix é enviado quando o pedido é aprovado. Combine com os vendedores que o dinheiro não cai no momento do pedido.

> [accordion] Como mostro ao vendedor quanto ele vai receber?
>
> Depois de criar o pedido, consulte a listagem filtrando por `merchantId`. Cada pedido traz `amount` e `payoutFee`; o líquido é a diferença. O webhook de aprovação traz também `netAmount`.

> [accordion] A conta master é avisada dos saques das subcontas?
>
> Sim, se tiver um endpoint de webhook cadastrado com a opção de incluir subcontas. Sem isso, os avisos vão só para os endpoints da subconta. A master também acompanha todos os saques pela listagem `GET /v1/payout-requests`, que traz `merchantLegalName` e `merchantEmail` de cada pedido.

> [accordion] Consigo testar o saque no Modo Teste?
>
> Não. Com a chave de teste, a criação responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE`, e a listagem só traz registros de teste (na prática, vazia).

## Como testar

No [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md), o cenário **FC-07** confere o saque da subconta com valor em **reais**: a requisição montada, o tratamento da resposta `{ "id" }` e dos erros documentados. Como não existe saque com a chave de teste, o cenário não é executado no Modo Teste.

## Veja também

> [card] [Webhooks de saque](https://docs.fastpaybrasil.com/guias/webhooks/saque.md)
>
> Envelope, campos e implementação.

> [card] [Criar saque da subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/criar-saque.md)
>
> Referência da rota de criação.

> [card] [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md)
>
> Referência da listagem e dos filtros.

> [card] [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md)
>
> Saldo por moeda e saque da própria conta.


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