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

# Webhooks de saque

> Avisos de aprovação e rejeição dos saques das subcontas do Connect: quem recebe, formato e como tratar os valores.

Quando uma subconta do [Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md) tem um saque (payout) solicitado, a solicitação fica pendente até ser aprovada ou rejeitada. Os webhooks de saque avisam o resultado: `payout.approved` quando o saque foi aprovado e enviado para pagamento, e `payout.rejected` quando a solicitação foi recusada, com o motivo.

> [!NOTE]
>
> **Para o negócio:** em um marketplace, o vendedor quer saber quando o saque sai. Com estes eventos, a sua plataforma mostra ao vendedor o status do saque e o valor líquido, sem que ninguém precise conferir o painel. Se o saque for rejeitado, o motivo chega junto, e o seu time de suporte pode orientar o vendedor.

## Quando usar

| Situação | Evento |
| - | - |
| Mostrar ao vendedor que o saque foi aprovado e enviado para pagamento, com valor líquido e taxa | `payout.approved` |
| Avisar o vendedor que o saque não foi feito e por quê | `payout.rejected` |
| Saque da própria conta (conta master ou conta sem Connect) | Não há webhook. Acompanhe pela [listagem de saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) |

## Como funciona

O desenho abaixo mostra o caminho de um saque de subconta, do pedido ao webhook.

```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 P as Sua plataforma
        participant W as Seu receptor de webhooks
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
        participant O as Operação Finvia
    end
    box rgb(244,240,255) Fora da Finvia
        participant X as Provedor de pagamento
    end
    P->>F: POST /v1/submerchants/{merchantId}/payout-requests · chave da master
    F-->>P: 201 · id do saque
    Note over F,O: Saque nasce pending e o valor bruto sai do saldo disponível da subconta. A subconta também pode pedir com a chave dela, em POST /v1/payout-requests
    F->>O: Solicitação aguarda decisão
    alt Aprovado
        O->>X: Pix do valor líquido para a chave CNPJ da subconta
        F-)W: payout.approved · amount · payoutFee · netAmount
    else Rejeitado
        Note over F,O: O valor reservado volta ao saldo disponível
        F-)W: payout.rejected · rejectionReason
    end
    Note over W,F: Vai aos endpoints da subconta e aos da master com include_submerchants
    W->>W: Deduplica por id + event e converte os valores de texto
    W->>P: Atualiza o saque e avisa o vendedor
```

**1. O saque da subconta é solicitado**

A conta master solicita em `POST /v1/submerchants/{merchantId}/payout-requests`, ou a própria subconta solicita com a chave dela. Em qualquer caso, a solicitação nasce com status `pending` e o valor bruto sai do saldo disponível.

**2. A Finvia decide**

A solicitação é aprovada ou rejeitada pela operação da Finvia. Na aprovação, o Pix do valor líquido é enviado ao provedor de pagamento. Na rejeição, o valor reservado volta ao saldo disponível.

**3. A Finvia escolhe os destinos**

O aviso vai para os endpoints de webhook cadastrados na subconta e para os endpoints da conta master cadastrados com a opção de incluir subcontas (`include_submerchants: true`). Em cada endpoint, vale o filtro de eventos (`enabled_events`); lista vazia recebe todos.

**4. O webhook é enviado**

O aviso é enviado depois que os dados foram gravados, então uma consulta feita ao receber o webhook já mostra o resultado. Uma falha de entrega não interrompe a aprovação nem a rejeição.

## Eventos disponíveis

| Evento | Quando é enviado |
| - | - |
| `payout.approved` | A solicitação de saque é aprovada e o pagamento é enviado |
| `payout.rejected` | A solicitação de saque é rejeitada |

Não há evento de criação do saque. Para saber que um saque foi solicitado, use a resposta da criação ou a [listagem de saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md).

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Quais saques geram webhook | Só os saques de subconta, qualquer que seja a rota usada para criar. O saque da própria conta não gera webhook |
| Quem recebe | Endpoints da subconta e endpoints da conta master com `include_submerchants: true`. Veja [Quem recebe cada evento](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#quem-recebe-cada-evento) |
| Destino do dinheiro | Pix para a chave CNPJ da subconta (o mesmo CNPJ do cadastro). Detalhes em [Saques do Connect](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) |
| Moeda | `BRL` |
| Valores | `amount`, `payoutFee` e `netAmount` chegam como **texto decimal com 8 casas**, em reais (ex.: `"100.00000000"`). Converta antes de calcular ou exibir |
| Assinatura | As mensagens não têm cabeçalho de assinatura. Confirme o status pela listagem de saques antes de agir |
| Teste | Os eventos de saque não têm marcação de teste. Saques não existem no Modo Teste: com `sk_test_`, a criação responde `403` `WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE` |
| Entrega | Veja [Entrega e retentativas](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#entrega-e-retentativas) |

> [!WARNING]
>
> Mantenha uma rotina que consulte a [listagem de saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md) para conciliar os saques ainda marcados como pendentes no seu sistema. Filtre por `merchantId` para ver uma subconta só e use `status=pending` para achar os que aguardam decisão.

## Status do saque

| Valor | Significado |
| - | - |
| `pending` | Solicitação criada. O valor bruto já saiu do saldo disponível e aguarda a decisão |
| `approved` | Aprovado e enviado para pagamento |
| `rejected` | Rejeitado. O valor reservado volta ao saldo disponível e o motivo fica em `rejectionReason` |

O webhook só chega com `approved` ou `rejected`. `approved` significa que o Pix do valor líquido foi enviado ao provedor no momento da aprovação. Não trate esse status como confirmação de crédito na conta bancária do vendedor.

## Envelope (camelCase)

O envelope do saque é mais simples que o de cobrança: o `id` da raiz é o **id da solicitação de saque**, igual a `data.id`, e se repete nos eventos do mesmo saque. Não há id de evento próprio, `livemode`, `processedAt` nem `createdAt`.

```json theme={null}
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "event": "payout.approved",
  "data": {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
    "amount": "100.00000000",
    "currency": "BRL",
    "status": "approved",
    "payoutFee": "1.00000000",
    "netAmount": "99.00000000"
  }
}
```

**Em validação (V-16):** há uma mudança em desenvolvimento no webhook de saque: id de evento próprio na raiz, campo `livemode`, registro de entrega e envio também para os saques da conta master. Esta página descreve o formato atual. Escreva o parser aceitando campos adicionais sem erro.

### Campos do objeto `data`

| Campo | Tipo | Descrição |
| - | - | - |
| `id` | string | ID da solicitação de saque |
| `merchantId` | string | ID da subconta que fez o saque |
| `amount` | string | Valor bruto solicitado, em reais, como texto decimal com 8 casas |
| `currency` | string | Código ISO da moeda (`BRL`) |
| `status` | string | `approved` ou `rejected` |
| `payoutFee` | string | Taxa de saque, em reais, como texto decimal com 8 casas |
| `netAmount` | string | Valor líquido depois da taxa (`amount` menos `payoutFee`), em reais, como texto decimal com 8 casas |
| `rejectionReason` | string | Motivo da rejeição. **Presente apenas em** `payout.rejected` |

### Valores em texto decimal

Os valores chegam como texto: `"100.00000000"` é R\$ 100,00. Converta antes de usar. Em JavaScript, `data.netAmount.toFixed(2)` dá erro, porque `toFixed` não existe em texto.

```javascript theme={null}
const netAmount = Number(data.netAmount); // 99
const formatado = new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' }).format(netAmount); // "R$ 99,00"
```

Para somar ou guardar valores financeiros, prefira um tipo decimal do seu banco ou uma biblioteca de decimais, partindo do texto recebido.

## Payloads por evento

> [tab] payout.approved
>
> Enviado depois da aprovação da solicitação e do envio do pagamento.
>
> ```json theme={null}
> {
>   "id": "2vorkDcXyvzifL63YX09S9VqcnI",
>   "event": "payout.approved",
>   "data": {
>     "id": "2vorkDcXyvzifL63YX09S9VqcnI",
>     "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
>     "amount": "100.00000000",
>     "currency": "BRL",
>     "status": "approved",
>     "payoutFee": "1.00000000",
>     "netAmount": "99.00000000"
>   }
> }
> ```

> [tab] payout.rejected
>
> Enviado quando a solicitação é rejeitada. O motivo vem em `rejectionReason`.
>
> ```json 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"
>   }
> }
> ```

## Configuração

> [tab] Pelo painel
>
> No [painel da Finvia](https://app.finvia.com.br), selecione a conta e vá em **Configurações** > **Webhooks**. Há dois caminhos:
>
> * Na conta master, cadastre um endpoint com a opção de incluir subcontas. Ele recebe os saques de todas as subcontas.
> * Com a subconta selecionada, cadastre um endpoint só para ela.
>
> O endpoint cadastrado pelo painel recebe todos os eventos (cobrança, assinatura e saque).

> [tab] Pela API
>
> Use [`POST /v1/webhook-endpoints`](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint). Para receber só os eventos de saque de todas as subcontas, cadastre na master:
>
> ```bash cURL theme={null}
> curl -X POST "https://api-global.fastpaybrasil.com/v1/webhook-endpoints?merchantId=3Fq9TzL2mWc8VbN1xR7pK4hJ6sD" \
>   -u "$FINVIA_API_KEY:" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "url": "https://meusite.com.br/webhooks/finvia/saques",
>     "enabled_events": ["payout.approved", "payout.rejected"],
>     "include_submerchants": true
>   }'
> ```
>
> Para cadastrar o endpoint numa subconta, a master usa a própria chave secreta com `merchantId` igual ao id da subconta.

## Passo a passo

```javascript Node.js theme={null}
// webhook-saque.mjs (Node.js 18+, ESM)
import express from 'express';

// Exemplo em memória. Em produção, grave as chaves no seu banco.
const seen = new Set();

// Troque pelas regras do seu sistema
const payouts = { update: async (id, info) => console.log('saque', id, info) };
async function notifySeller(merchantId, text) { console.log(merchantId, text); }

const brl = new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' });

const app = express();
app.use(express.json());

app.post('/webhooks/finvia/saques', async (req, res) => {
  const { id, event, data } = req.body;
  res.status(200).send('OK');

  // Deduplicação pelo corpo: id da raiz (id do saque) + event
  const key = `payout:${id}:${event}`;
  if (seen.has(key)) return;
  seen.add(key);

  switch (event) {
    case 'payout.approved':
      // Valores chegam como texto decimal: guarde o texto e converta só para exibir
      await payouts.update(data.id, {
        status: 'approved',
        netAmount: data.netAmount,
        fee: data.payoutFee,
      });
      await notifySeller(data.merchantId, `Saque de ${brl.format(Number(data.netAmount))} aprovado.`);
      break;

    case 'payout.rejected':
      await payouts.update(data.id, { status: 'rejected', reason: data.rejectionReason });
      await notifySeller(data.merchantId, `Saque rejeitado: ${data.rejectionReason}`);
      break;

    default:
      console.log(`Evento não tratado: ${event}`);
  }
});

app.listen(3000);
```

> [!TIP]
>
> **Para o desenvolvedor:** o `id` da raiz é o id do saque, por isso a chave pelo corpo é `id` + `event`, conforme a [receita de deduplicação](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md#como-descartar-eventos-repetidos). Eventos diferentes do mesmo saque não se confundem.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| A conta master não recebe os avisos de saque | O endpoint da master não tem a opção de incluir subcontas | Ative a opção no endpoint da master ou cadastre um endpoint na subconta |
| Nenhum aviso chega | Nenhum endpoint na subconta nem na master com a opção ligada, ou evento fora de `enabled_events` | Revise os endpoints e os eventos habilitados (lista vazia recebe todos) |
| `TypeError` ao formatar o valor | Os valores chegam como texto | Converta com `Number()` ou com um tipo decimal antes de calcular |
| `rejectionReason` indefinido | Leitura do campo em `payout.approved` | O campo só existe em `payout.rejected` |
| Esperando webhook no saque da própria conta | Só saques de subconta geram webhook | Acompanhe pela listagem de saques |

## Perguntas frequentes

> [accordion] Sou a conta master. Como acompanho os saques dos meus vendedores?
>
> Cadastre um endpoint na conta master com a opção de incluir subcontas (`include_submerchants: true`). Ele recebe os eventos de saque de todas as subcontas, e `data.merchantId` indica de qual subconta é o saque. Para conciliar, consulte a [listagem de saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md).

> [accordion] O saque da minha própria conta gera webhook?
>
> Não. Só os saques de subconta geram webhook. O saque da própria conta é acompanhado pela listagem, que traz os saques do mais recente para o mais antigo.

> [accordion] Para onde vai o dinheiro do saque?
>
> Para a chave Pix do tipo CNPJ igual ao CNPJ cadastrado na subconta. A moeda é `BRL`.

> [accordion] Como a taxa de saque aparece?
>
> Em `payoutFee`, em reais, como texto decimal. O valor que o vendedor recebe é `netAmount`, que é `amount` menos a taxa. O cálculo está em [Saques do Connect](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md).

> [accordion] approved quer dizer que o dinheiro caiu na conta do vendedor?
>
> Significa que o saque foi aprovado e que o Pix do valor líquido foi enviado para pagamento. Se o vendedor não receber, acione o suporte da Finvia com o id do saque.

## Como testar

Saques não existem no Modo Teste, então o webhook de saque só pode ser observado com um saque real de subconta, em produção, de valor baixo.

| Código | Cenário | O que comprovar |
| - | - | - |
| FC-07 | Saque da subconta | Solicitação criada com status `pending` |
| PAY-06 | Acompanhar o status pela listagem | Status `pending`, `approved` ou `rejected` visível na listagem de saques |

Guarde o registro do webhook `payout.approved` ou `payout.rejected` recebido e a resposta HTTP que o seu endpoint devolveu.

## Veja também

> [card] [Saques do Connect](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
>
> Como a subconta solicita e acompanha saques.

> [card] [Listar saques](https://docs.fastpaybrasil.com/referencia/saques/listar.md)
>
> Consulta de solicitações com filtros.

> [card] [Criar endpoint de webhook](https://docs.fastpaybrasil.com/referencia/webhooks/criar-endpoint.md)
>
> Cadastro com include\_submerchants e filtro de eventos.

> [card] [Webhooks: visão geral](https://docs.fastpaybrasil.com/guias/webhooks/visao-geral.md)
>
> Destinos, formatos, entrega e deduplicação.


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