Saques

Consultar saque

Com esta funcionalidade você consulta o status de um saque específico pelo withdrawalId, da sua master account ou de uma subconta associada a ela.

GET/v1/wallet/withdrawals/:withdrawalId

Base URL Produção:https://api.validapay.com.br

Base URL Sandbox:https://sandbox.validapay.com.br

Use esta rota para acompanhar um saque que retornou PROCESSING no POST /v1/wallet/withdraw: consulte até o status mudar para CONFIRMED ou ERROR. A resposta tem o mesmo formato de um item de GET /v1/wallet/withdrawals.

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: para consultar o saque de uma subconta, envie o número dela em accountId. Sem accountId, a busca é feita só na conta do token, e um saque de outra conta responde 404 WITHDRAWAL_NOT_FOUND.

Case de uso:

Como integrador, quero consultar um saque pelo seu identificador, para saber se o PIX já foi liquidado sem precisar percorrer o histórico de saques.

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

wallet/read

Path Parameters

withdrawalIdstringobrigatório

Identificador do saque, o mesmo withdrawalId retornado no POST /v1/wallet/withdraw

Query Parameters

accountIdopcional

Número da subconta dona do saque. Omitido, consulta a própria conta do token

258965356

← Anterior

Listar saques

Extrato subconta

const url = 'https://sandbox.validapay.com.br/v1/wallet/withdrawals/:withdrawalId?accountId=258965356';

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer {{token}}'
  },
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200Sucesso▾

JSON

{
    "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" 
}

Campos da resposta

withdrawalIdstring

Identificador do saque, o mesmo retornado no POST /v1/wallet/withdraw

accountIdstring

Conta de onde o saldo saiu

amountnumber

Valor sacado, em reais

feeAmountnumber

Tarifa do saque, em reais

feeDeductionobject

Débito da tarifa no saldo. null enquanto o saque não é confirmado

statusstring

PROCESSING, CONFIRMED ou ERROR

pixKeystring

Chave Pix de destino

pixKeyTypestring

Tipo da chave Pix

Valores aceitos:CPFCNPJEMAILPHONEEVP

documentNumberstring

CPF/CNPJ do titular da conta que sacou

Regra:^(\d{11}|\d{14})$

endToEndIdstring

Identificador do PIX no arranjo, para conciliação com o banco de destino

transactionIdstring

Identificador da transação do PIX

creditPartyobject

Conta de destino, como consta no DICT

createdAtstring

Criação do saque

updatedAtstring

Última atualização do status

404Saque não encontrado▾

JSON

{
    "error": {
        "message": "Saque não encontrado",
        "code": "WITHDRAWAL_NOT_FOUND",
        "details": null,
        "timestamp": "2026-10-24T14:19:02.341Z"
    }
}

404Subconta não encontrada▾

JSON

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

401Subconta 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"
    }
}

← Anterior

Listar saques

Extrato subconta