Devolução Pix

Consultar status da devolução PIX

Consulta se uma devolução PIX foi confirmada.

GET/v1/wallet/refunds

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

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

Não use o status da cobrança (REFUNDED / PARTIALLY_REFUNDED) para saber se o estorno foi confirmado — use o refund:

status === "CONFIRMED" (ou success === true): estorno confirmado
status === "PROCESSING": ainda aguardando
status === "ERROR": falhou (error pode vir preenchido)

Modos de uso: informe um identificador na query string (não há body):

?refundId=ref_...: detalhe/polling de uma devolução específica.
?endToEndId=E...: devoluções do PIX original.
?chargeId=cha_...: devoluções da cobrança.

MasterAccounts podem consultar uma subconta acrescentando accountId à query (ex.: ?chargeId=cha_...&accountId=429131213).

Se vier mais de um identificador, só o de maior precedência é usado: refundId > endToEndId > chargeId.

A resposta é sempre uma lista em items, mesmo na consulta por refundId. Se não houver devolução, items vem vazio.

ℹ️ Polling sugerido: 2–5s com timeout (60–120s).

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

Query Parameters

refundIdopcional

Detalhe/polling de uma devolução específica

ref_1774531490865_bq4e8v12x

endToEndIdopcional

Lista as devoluções do PIX original

E0036030520260326132336e2f8787c4

chargeIdopcional

Lista as devoluções da cobrança

cha_1774530966959_frgj3ptax

accountIdopcional

(M2M) Filtra pela subconta

429131213

← Anterior

Criar devolução PIX

Criar estorno de cartão

const url = 'https://sandbox.validapay.com.br/v1/wallet/refunds?refundId=ref_1774531490865_bq4e8v12x';

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

{
    "items": [
        {
            "refundId": "ref_1790546300126_b16nwgz21",
            "accountId": "SANDBOX_0438f4c8-0031-7051-16d4-5a23704756b6",
            "status": "CONFIRMED",
            "success": true,
            "amount": 1,
            "reason": "MD06", 
            "chargeId": "SANDBOX_cha_1790534100343_osf6bm91p",
            "endToEndId": "E4564832420260927190425s3559c518ec83414f",
            "paymentType": null,
            "splitReversals": [],
            "error": null,
            "createdAt": "2026-09-27T21:58:20.126Z"
        }
    ]
}

Campos da resposta

itemsarray[1]

200Nenhuma devolução encontrada▾

JSON

{
    "items": []
}

← Anterior

Criar devolução PIX

Criar estorno de cartão