请求退还已收付款（Refund-In）
POST https://api.avista.global/api/pix/refund-in/{id}
需要在 Authorization 头中提供 Bearer token。请参阅 生成令牌 获取。
请求退还已收到的 PIX 付款。退款可以是部分退款或全额退款，但必须在 89 天期限内。
需要在 Authorization 头中提供 Bearer 令牌。
| 参数 | 类型 | 必填 | 描述 |
|---|
id | string | 是 | 需要退款的原始交易 ID |
| 字段 | 类型 | 必填 | 描述 |
|---|
refundValue | number | 是 | 退款金额（巴西雷亚尔，可部分退款）。最小值：0.01 |
reason | string | 否 | 退款原因 |
externalId | string | 否 | 退款识别的外部 ID。在 BACEN API 中，对应 id URL 参数 |
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}
curl -X POST "https://api.avista.global/api/pix/refund-in/12345" \
-H "Authorization: Bearer $AVISTA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}'
const axios = require('axios');
const response = await axios.post('https://api.avista.global/api/pix/refund-in/12345',
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
},
{
headers: {
'Authorization': `Bearer ${process.env.AVISTA_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);
import os, requests
response = requests.post(
'https://api.avista.global/api/pix/refund-in/12345',
headers={
'Authorization': f'Bearer {os.environ["AVISTA_TOKEN"]}',
'Content-Type': 'application/json',
},
json={
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
},
)
print(response.json())
$ch = curl_init('https://api.avista.global/api/pix/refund-in/12345');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('AVISTA_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => '{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}',
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
String body = """
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.avista.global/api/pix/refund-in/12345"))
.header("Authorization", "Bearer " + System.getenv("AVISTA_TOKEN"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
| 字段 | 类型 | 描述 |
|---|
transactionId | string | 生成的退款交易 ID |
externalId | string | 退款交易的外部 ID |
status | string | 当前退款交易状态（PENDING、CONFIRMED、ERROR） |
refundValue | number | 退款金额（巴西雷亚尔） |
providerTransactionId | string | 提供商交易 ID（用于与 webhooks 关联） |
generateTime | string | 退款交易生成日期/时间（ISO 8601） |
{
"transactionId": "789",
"externalId": "D123456789",
"status": "PENDING",
"refundValue": 50.00,
"providerTransactionId": "7ef4fc3f-a187-495e-857c-e84d70612761",
"generateTime": "2024-01-15T10:30:00.000Z"
}
| 状态码 | 描述 |
|---|
| 400 | 数据无效、交易未找到、超过期限或金额无效 |
| 401 | 令牌缺失或无效 |
| 404 | 原始交易未找到 |
| 500 | 处理退款请求时出错 |
