PIX 退款

对收到的 PIX 交易发起退款（全额或部分）。

端点

POST /api/v2/external/pix/refund

请求头

请求头	类型	必填	描述
Authorization	String	是	Bearer {access_token}
Content-Type	String	是	application/json
hmac	String	是	请求体的 HMAC-SHA512 签名（了解详情）

请求体

字段	类型	必填	描述	示例
transaction_id	String	是	收到的原始 PIX 交易 ID	"PIXIN20260307a1b2c3d4e5f6"
amount	Integer	否	退款金额（分）。省略则退全额。	5000（R$ 50.00）
reason	String	是	BACEN 退款代码（见下表）	"MD06"

部分退款

进行部分退款时，请填写小于原始金额的 amount。同一笔交易的退款总额不得超过原始收款金额。

退款代码

代码	描述
MD06	双方协议退款
BE08	欺诈
AM09	金额错误
SL02	清算错误
RR04	交易未被识别

示例

BODY='{"transaction_id":"PIXIN20260307a1b2c3d4e5f6","amount":10000,"reason":"MD06"}'
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/v2/external/pix/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

成功响应 (200)

{
  "worked": true,
  "refund_id": "PIXRET20260307a1b2c3d4e5f6",
  "transaction_id": "PIXIN20260307a1b2c3d4e5f6",
  "amount": 10000,
  "status": "processing"
}

字段	类型	描述
worked	Boolean	true 表示操作成功
refund_id	String	退款唯一标识
transaction_id	String	原始交易 ID
amount	Integer	退款金额（分）
status	String	初始状态：processing

错误响应 (404)

{
  "worked": false,
  "detail": "未找到原始交易"
}

错误响应 (422)

{
  "worked": false,
  "detail": "退款余额不足"
}

错误响应 (422) -- 金额超限

{
  "worked": false,
  "detail": "退款金额超过原始交易金额"
}

退款期限

代码 MD06（协议退款）可在收款后 90 天内发起。欺诈退款（BE08）遵循 BACEN 规定的 MED 时限。