# Listar saques

**Área:** Saques

Com esta funcionalidade você pode consultar o histórico e o status dos saques da sua _master account_ ou de uma subconta associada a ela.

`GET /v1/wallet/withdrawals`

**Base URL Produção:** `https://api.validapay.com.br`  
**Base URL Sandbox:** `https://sandbox.validapay.com.br`

**Scopes necessários:** `wallet/read`

Use esta rota para acompanhar um saque que retornou `PROCESSING` no `POST /v1/wallet/withdraw`: localize o `withdrawalId` na lista e confira o `status`. Os saques vêm do mais recente para o mais antigo.

**Status do saque**

- `PROCESSING`: PIX enviado, aguardando a confirmação da liquidação.
- `CONFIRMED`: PIX liquidado na conta de destino.
- `ERROR`: o PIX foi aceito para envio, mas a liquidação falhou.

> ⚠️ **Atenção:** um saque recusado no próprio `POST /v1/wallet/withdraw` (resposta 4xx) não é registrado e não aparece nesta lista. Só aparecem os saques aceitos para envio do PIX.

### Query parameters

| Campo | Obrigatório | Descrição |
|---|---|---|
| `accountId` | não | Número da subconta a consultar. Omitido, consulta a própria conta do token |
| `status` | não | PROCESSING, CONFIRMED ou ERROR |
| `startDate` | não | Data inicial (ISO 8601), comparada com a data de criação do saque |
| `endDate` | não | Data final (ISO 8601), inclusiva. Envie junto com startDate |
| `limit` | não | 1 a 100, padrão 20 |
| `lastKey` | não | Cursor da próxima página (pagination.lastKey da resposta anterior) |

### Resposta 200: Sucesso

```json
{
    "items": [
        {
            "withdrawalId": "wdr_1792851006000_ab12cd34e", 
            "accountId": "258965356", 
            "amount": 150.00, 
            "feeAmount": 0.47, 
            "feeDeduction": { 
                "status": "COMPLETED", 
                "amount": 0.47, 
                "settledFromDebt": false, 
                "timestamp": "2026-10-24T14:16:52.120Z" 
            },
            "status": "CONFIRMED", 
            "pixKey": "12345678000190", 
            "pixKeyType": "CNPJ", 
            "documentNumber": "12345678000190", 
            "endToEndId": "E13935893202610241416abcdef12345", 
            "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", 
            "creditParty": { 
                "bank": "18236120", 
                "key": "12345678000190", 
                "branch": "0001", 
                "account": "1234567", 
                "name": "EMPRESA EXEMPLO LTDA", 
                "accountType": "CACC" 
            },
            "createdAt": "2026-10-24T14:16:46.000Z", 
            "updatedAt": "2026-10-24T14:16:52.120Z" 
        },
        {
            "withdrawalId": "wdr_1792847000000_fg56hi78j",
            "accountId": "258965356",
            "amount": 80.00,
            "feeAmount": 0.47,
            "feeDeduction": null,
            "status": "PROCESSING",
            "pixKey": "11111111-2222-3333-4444-555555555555",
            "pixKeyType": "EVP",
            "documentNumber": "12345678000190",
            "endToEndId": "E13935893202610241310klmnop67890",
            "transactionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "creditParty": {
                "bank": "60701190",
                "key": "11111111-2222-3333-4444-555555555555",
                "branch": "0001",
                "account": "7654321",
                "name": "EMPRESA EXEMPLO LTDA",
                "accountType": "CACC"
            },
            "createdAt": "2026-10-24T13:10:00.000Z",
            "updatedAt": "2026-10-24T13:10:00.000Z"
        }
    ],
    "pagination": {
        "limit": 20, 
        "hasMore": true, 
        "lastKey": "eyJhY2NvdW50SWQiOiIyNTg5NjUzNTYiLCJTSyI6IjIwMjYtMTAtMjRUMTM6MTA6MDAuMDAwWiN3ZHJfMTc5Mjg0NzAwMDAwMF9mZzU2aGk3OGoifQ" 
    }
}
```

#### Campos da resposta

| Campo | Descrição |
|---|---|
| `items.withdrawalId` | Identificador do saque, o mesmo retornado no POST /v1/wallet/withdraw |
| `items.accountId` | Conta de onde o saldo saiu |
| `items.amount` | Valor sacado, em reais |
| `items.feeAmount` | Tarifa do saque, em reais |
| `items.feeDeduction` | Débito da tarifa no saldo. null enquanto o saque não é confirmado |
| `items.feeDeduction.status` | COMPLETED: tarifa debitada. FAILED: saldo insuficiente no momento; a tarifa fica pendente e é cobrada depois |
| `items.feeDeduction.amount` | Valor debitado, em reais |
| `items.feeDeduction.settledFromDebt` | true quando a tarifa pendente foi quitada depois |
| `items.feeDeduction.timestamp` | Momento do débito da tarifa |
| `items.status` | PROCESSING, CONFIRMED ou ERROR |
| `items.pixKey` | Chave Pix de destino |
| `items.pixKeyType` | Tipo da chave Pix |
| `items.documentNumber` | CPF/CNPJ do titular da conta que sacou |
| `items.endToEndId` | Identificador do PIX no arranjo, para conciliação com o banco de destino |
| `items.transactionId` | Identificador da transação do PIX |
| `items.creditParty` | Conta de destino, como consta no DICT |
| `items.creditParty.bank` | ISPB da instituição de destino |
| `items.creditParty.key` | Chave Pix de destino |
| `items.creditParty.branch` | Agência |
| `items.creditParty.account` | Conta |
| `items.creditParty.name` | Titular da conta de destino |
| `items.creditParty.accountType` | Tipo da conta de destino |
| `items.createdAt` | Criação do saque |
| `items.updatedAt` | Última atualização do status |
| `pagination.limit` | Itens por página |
| `pagination.hasMore` | true quando há mais saques |
| `pagination.lastKey` | Envie em lastKey para buscar a próxima página. null na última |

### Resposta 404: Subconta não encontrada

```json
{
    "error": {
        "message": "Subconta 499999999 nao encontrada",
        "code": "SUBACCOUNT_NOT_FOUND",
        "details": null,
        "timestamp": "2026-10-24T14:20:11.512Z"
    }
}
```


### Resposta 401: Subconta de outra master account

```json
{
    "error": {
        "message": "Subconta 499999999 nao pertence a esta conta master",
        "code": "UNAUTHORIZED_SUBACCOUNT",
        "details": null,
        "timestamp": "2026-10-24T14:21:03.877Z"
    }
}
```


### Resposta 401: Credencial de outro ambiente

```json
{
    "error": {
        "message": "Credencial inválida neste ambiente",
        "code": "INVALID_CREDENTIAL",
        "details": null,
        "timestamp": "2026-10-24T14:22:40.004Z"
    }
}
```


---

Página: https://docs.validapay.com.br/referencia/get-listar-saques  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json