Devoluções

Devolução

Com esta funcionalidade você pode criar u_ma devolução._

⚠️ Atenção: O código de motivo da devolução é obrigatório. Os códigos possiveis são:
BANK_ERROR -> Erro bancário
FRAUD -> Suspeita de fraude
CUSTOMER_REQUEST -> Solicitalão do cliente
PIX_CHANGE_ERROR -> Erro na transação

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": "chg_abc123" 
}

Schema

Field	Type	Required	Description
accountId	string	Optional	Número da subconta. Se omitido, opera na conta principal.
endToEndId	string	Required	EndToEndId da transação PIX original.
amount	number	Required	Valor da devolução (parcial ou total).
reason	string	Required	Um de: BANK_ERROR, FRAUD, CUSTOMER_REQUEST, PIX_CHANGE_ERROR.
chargeId	string	Optional	ID da charge associada.

← Anterior

Extrato conta master

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": "chg_abc123" 
})
};

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