Devolução Pix

Criar devolução PIX

Cria uma devolução PIX a partir do chargeId da cobrança paga. A devolução pode ser parcial ou total.

POST/v1/wallet/refunds

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

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

⚠️ Atenção: o campo reason (motivo da devolução) é obrigatório.

Valores aceitos para reason:

CUSTOMER_REQUEST — solicitação do cliente
FRAUD — suspeita de fraude
BANK_ERROR — erro bancário
PIX_CHANGE_ERROR — erro na transação

A devolução nasce em geral como PROCESSING. Guarde o refundId retornado e acompanhe a confirmação pela rota Consultar status da devolução PIX (GET /v1/wallet/refunds).

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/write

Body

application/json

Content-Type:application/json

JSON

{
  "chargeId": "cha_1774437468463_4hj927ips",
  "amount": 1.00,
  "reason": "CUSTOMER_REQUEST"
}

Schema

chargeIdstringobrigatório

ID da cobrança Pix a devolver. O endToEndId do pagamento é obtido da própria cobrança.

amountnumberobrigatório

Valor da devolução (parcial ou total).

reasonstringobrigatório

Um de: BANK_ERROR, FRAUD, CUSTOMER_REQUEST, PIX_CHANGE_ERROR.

← Anterior

Listar boletos do DDA

Consultar status da devolução PIX

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

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "chargeId": "cha_1774437468463_4hj927ips",
  "amount": 1.00,
  "reason": "CUSTOMER_REQUEST"
})
};

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

Response Examples

201Sucesso▾

JSON

{
    "refundId": "ref_1774437918293_jm2hen5y7",
    "status": "PROCESSING",
    "amount": 1,
    "reason": "CUSTOMER_REQUEST",
    "endToEndId": "E003603052026032511186a4f4cdf139",
    "chargeId": "cha_1774437468463_4hj927ips",
    "createdAt": "2026-03-25T11:25:18.293Z"
}

400REFUND_AMOUNT_EXCEEDED▾

JSON

{
    "error": {
        "message": "Valor excede o disponível para devolução. Original: R$1, já devolvido: R$0, restante: R$1",
        "code": "REFUND_AMOUNT_EXCEEDED",
        "details": null,
        "timestamp": "2026-09-27T19:24:05.256Z"
    }
}

400CHARGE_WITHOUT_END_TO_END_ID▾

JSON

{
    "error": {
        "message": "Cobrança SANDBOX_cha_1790549943254_iv2glkbjy não possui endToEndId: o pagamento Pix ainda não foi confirmado ou a cobrança não é Pix",
        "code": "CHARGE_WITHOUT_END_TO_END_ID",
        "details": null,
        "timestamp": "2026-09-27T22:59:54.549Z"
    }
}

404CHARGE_NOT_FOUND▾

JSON

{
    "error": {
        "message": "Cobrança não encontrada",
        "code": "CHARGE_NOT_FOUND",
        "details": null,
        "timestamp": "2026-09-27T23:31:36.345Z"
    }
}

← Anterior

Listar boletos do DDA

Consultar status da devolução PIX