PIX Refund

Initiates a refund (total or partial) of a received PIX transaction.

Endpoint

POST /api/v2/external/pix/refund

Headers

Header	Type	Required	Description
Authorization	String	Yes	Bearer {access_token}
Content-Type	String	Yes	application/json
hmac	String	Yes	HMAC-SHA512 signature of the body (learn more)

Request Body

Field	Type	Required	Description	Example
transaction_id	String	Yes	ID of the original received PIX transaction	"PIXIN20260307a1b2c3d4e5f6"
amount	Integer	No	Amount to refund in cents. If omitted, refunds the full amount.	5000 (BRL 50.00)
reason	String	Yes	BACEN refund code (see table below)	"MD06"

Partial refund

For partial refunds, provide an amount less than the original value. The total of all refunds for a single transaction cannot exceed the original amount received.

Refund Codes

Code	Description
MD06	Refund by agreement between parties
BE08	Fraud
AM09	Incorrect amount
SL02	Settlement error
RR04	Unrecognized transaction

Example

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"

Success Response (200)

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

Field	Type	Description
worked	Boolean	true indicates operation success
refund_id	String	Unique refund identifier
transaction_id	String	Original transaction ID
amount	Integer	Refund amount in cents
status	String	Initial status: processing

Error Response (404)

{
  "worked": false,
  "detail": "Original transaction not found"
}

Error Response (422)

{
  "worked": false,
  "detail": "Insufficient balance for refund"
}

Error Response (422) -- Amount exceeded

{
  "worked": false,
  "detail": "Refund amount exceeds the original transaction amount"
}

Refund deadline

Refunds with code MD06 (agreement) can be made up to 90 days after receipt. Fraud refunds (BE08) follow the MED deadlines defined by BACEN.