# Como realizar o saque de uma Subconta via API?

> :::info
> Para a utilização desta funcionalidade é necessário possuir a funcionalidade Subconta
> :::

Para realizar o saque integral de uma subconta, você utiliza o _endpoint_ `/api/v1/subaccount/{ID}/withdraw` da API.

Você pode acessar [aqui](/api#tag/subaccount)/paths/~1api~1v1~1subaccount~1%7Bid%7D~1withdraw/post)
a documentação referente a esse _endpoint_.

A chave pix registrada na subconta deve ser passada na url da requisição como parâmetro.

Após efetuar a requisição, se tudo ocorreu bem, o _status code_ da requisição será `2xx` e no `body` da resposta, um objeto com os detalhes da transação efetuada para a chave pix registrada na subconta.

### Exemplos em código

  

**Shell + cURL**

```sh
  curl 'https://api.woovi.com/api/v1/subaccount/chave-pix-subconta/withdraw -X POST \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -H "user-agent: node-fetch" \
      -H "Authorization": "app_id"
```

  
  

**JavaScript + Fetch**

```js
fetch(
  'https://api.woovi.com/v1/subaccount/chave-pix-subconta/withdraw',
  {
    method: 'POST',
    headers: {
      Authorization: 'AUTHORIZATION',
      'Content-Type': 'application/json',
    },
  },
).then((res) => res.json());
```

  

### Exemplos de resposta

```jsx
{
  "transaction": {
    "status": "CREATED",
    "value": 100,
    "correlationID": "TESTING1323",
    "destinationAlias": "pixKeyTest@test.com",
    "comment": "testing-transaction"
  }
}
```

### Tratamento de erros

Quando um saque de subconta falha, o webhook `OPENPIX:MOVEMENT_FAILED` é disparado com o código e a descrição específica do erro no campo `error`:

```json
{
  "event": "OPENPIX:MOVEMENT_FAILED",
  "payment": {
    "value": 100,
    "status": "FAILED",
    "destinationAlias": "pixKeyTest@test.com",
    "correlationID": "TESTING1323"
  },
  "error": {
    "code": "PIX_KEY_INFO_NOT_FOUND",
    "description": "A chave pix não está registrada em uma instituição bancária"
  }
}
```

Os principais códigos de erro para saques de subconta são:

| Código do Erro | Descrição |
| --- | --- |
| `NOT_ENOUGH_BALANCE` | A subconta não possui saldo suficiente para realizar o saque |
| `PIX_KEY_INFO_NOT_FOUND` | A chave pix não está registrada em nenhuma instituição bancária |
| `INVALID_PIX_KEY` | A chave pix informada é inválida |
| `ENTRY_ASSOCIATED_WITH_RESTRICTED_ACCOUNT_OR_USER` | A conta associada à chave pix está restrita por fraude pelo Banco Central |

:::info
Para a lista completa de códigos de erro, consulte a [documentação de erros de pagamento](/docs/payment/payment-failed-errors).

Para erros retornados pelo SPI (Sistema de Pagamentos Instantâneos do Banco Central), consulte os [códigos de erro PIX](/docs/flows/error-codes-payment).
:::

:::caution
Quando a chave pix da subconta é inválida ou está associada a uma conta restrita, o campo `withdrawBlocked` da subconta é marcado como `true` e saques futuros serão bloqueados. Veja mais detalhes em [Por que o saque da subconta foi bloqueado?](/docs/subaccount/subaccount-withdraw-blocked).
:::