Devolução Pix

Criar devolução PIX

Cria uma devolução PIX a partir do endToEndId da transação original. A devolução pode ser parcial ou total.

⚠️ 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).

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

Body

application/json

Content-Type:application/json

{
  "accountId": "459013777",
  "endToEndId": "E003603052026032511186a4f4cdf139",
  "amount": 1.00,
  "reason": "CUSTOMER_REQUEST",
  "chargeId": "cha_1774437468463_4hj927ips"
}

Schema

endToEndIdstringRequired

EndToEndId da transação PIX original.

amountnumberRequired

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

reasonstringRequired

Um de: BANK_ERROR, FRAUD, CUSTOMER_REQUEST, PIX_CHANGE_ERROR.

accountIdstringOptional

Número da subconta. Se omitido, opera na conta principal.

chargeIdstringOptional

ID da charge associada.

← Anterior

Extrato conta master

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({
  "accountId": "459013777",
  "endToEndId": "E003603052026032511186a4f4cdf139",
  "amount": 1.00,
  "reason": "CUSTOMER_REQUEST",
  "chargeId": "cha_1774437468463_4hj927ips"
})
};

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

Response Examples

201Sucesso

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

401Não autorizado

{
    "error": {
        "message": "Subconta nao pertence a esta conta",
        "code": "OWNERSHIP_MISMATCH",
        "details": null,
        "timestamp": "2026-03-25T11:28:25.397Z"
    }
}

← Anterior

Extrato conta master

Consultar status da devolução PIX