请求退还已收付款（Refund-In）
POST /api/pix/refund-in/{id}
POST https://<api-host>/api/pix/refund-in/{id}需要在 Authorization 头中提供 Bearer token。请参阅 生成令牌 获取。
请求退还已收到的 PIX 付款。退款可以是部分退款或全额退款，但必须在 89 天期限内。
认证
需要在 Authorization 头中提供 Bearer 令牌。
路径参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
id | string | 是 | 需要退款的原始交易 ID |
请求体
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
refundValue | number | 是 | 退款金额（巴西雷亚尔，可部分退款）。最小值：0.01 |
reason | string | 否 | 退款原因（最多 140 个字符） |
externalId | string | 否 | 退款的外部 ID（每个账户唯一，最多 100 个字符）。在 BACEN API 中，对应 id URL 参数 |
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
}代码示例
curl -X POST "https://<api-host>/api/pix/refund-in/12345" \
-H "Authorization: Bearer $PIX_API_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-host>/api/pix/refund-in/12345',
{
"refundValue": 50.00,
"reason": "Cliente solicitou devolução",
"externalId": "D123456789"
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);响应 (201)
| 字段 | 类型 | 描述 |
|---|---|---|
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 | 原始交易未找到 |
| 409 | PIX_DUPLICATE_EXTERNAL_ID — 该账户下退款的 externalId 已被使用 |
| 500 | 处理退款请求时出错 |