Devolução Pix

Consultar status da devolução PIX

Consulta se uma devolução PIX foi confirmada.

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 refundId (ou returnIdentification) para o detalhe/polling de uma devolução específica.
  • Informe endToEndId do PIX original para consultar as devoluções daquele pagamento.
  • MasterAccounts podem consultar uma subconta informando accountId.

Precedência: refundId > returnIdentification > endToEndId > chargeId.

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

GET/v1/wallet/refunds
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Authorizations

bearer

Authorization

string · header · required

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

Escopos requeridos

wallet/read

Query Parameters

NameTypeValueRequiredDescription
refundId-ref_1774531490865_bq4e8v12xOptional- Detalhe/polling de uma devolução específica
const url = 'https://sandbox.validapay.com.br/v1/wallet/refunds?refundId=ref_1774531490865_bq4e8v12x?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

200Item único (por refundId)
{
    "refundId": "ref_1774531490865_bq4e8v12x",
    "accountId": "429131212",
    "status": "CONFIRMED",
    "success": true,
    "amount": 100.00,
    "reason": "CUSTOMER_REQUEST",
    "chargeId": "cha_1774530966959_frgj3ptax",
    "originalEndToEndId": "E0036030520260326132336e2f8787c4",
    "returnIdentification": "D13935893202603261324C5jA3zE3V6J",
    "providerChargeId": null,
    "paymentType": null,
    "splitReversals": [],
    "error": null,
    "createdAt": "2026-03-26T13:24:52.106Z",
    "updatedAt": "2026-03-26T13:24:57.553Z"
}
404404 REFUND_NOT_FOUND
{
    "error": {
        "message": "Refund não encontrado",
        "code": "REFUND_NOT_FOUND",
        "details": null,
        "timestamp": "2026-08-05T12:00:00.000Z"
    }
}

← Anterior

Criar devolução PIX

Próximo →

Criar estorno de cartão