PIX 退款

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

端点

POST /api/external/pix/refund

请求头

头	类型	必填	描述
Authorization	String	是	ApiKey {client_id}:{client_secret}
Content-Type	String	是	application/json
hmac	String	是	请求体的 HMAC-SHA512 签名（了解详情）
Idempotency-Key	String	否	避免重复处理的唯一密钥（最大 256 字符）

请求体

字段	类型	必填	描述	示例
transaction_id	String	是	收到的原始 PIX 交易 ID	"7popu57v6us7p6pcicgq12345"
amount	Integer	否	退款金额，以 centavos（分） 为单位。省略则退全额。	3000（R$ 30.00）
reason	String	是	BACEN 退款代码（见下表）	"MD06"

货币金额

请求中的 amount 以 centavos（分） 为单位（R$ 30.00 = 3000）。响应中的 amount 以基本单位为单位（R$ 30.00 = 300000）。切勿使用浮点数。

部分退款

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

退款代码

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

示例

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

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

成功响应 (200)

{
  "worked": true,
  "refund_id": "PIXRET20260307a1b2c3d4e5f6",
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "amount": 300000,
  "status": "processing"
}

字段	类型	描述
worked	Boolean	true 表示操作成功
refund_id	String	退款唯一标识
transaction_id	String	原始交易 ID
amount	Integer	退款金额，以基本单位为单位（/ 10,000 = 雷亚尔）。300000 = R$ 30.00
status	String	初始状态：processing

错误响应 (404)

{
  "worked": false,
  "detail": "Transacao original nao encontrada"
}

错误响应 (422)

{
  "worked": false,
  "detail": "Saldo insuficiente para devolucao"
}

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

{
  "worked": false,
  "detail": "Valor da devolucao excede o valor original da transacao"
}

退款期限

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