PIX Refund

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

Endpoint

POST /api/external/pix/refund

Headers

Header	Type	Required	Description
Authorization	String	Yes	ApiKey {client_id}:{client_secret}
Content-Type	String	Yes	application/json
hmac	String	Yes	HMAC-SHA512 signature of the body (learn more)
Idempotency-Key	String	No	Unique key to prevent duplicate processing (max 256 chars)

Request Body

Field	Type	Required	Description	Example
original_transaction_id	String	Yes	ID of the original received PIX transaction	"7popu57v6us7p6pcicgq12345"
amount	Integer	No	Amount to refund in centavos. If omitted, refunds the full amount.	3000 (R$ 30.00)
reason	String	Yes	BACEN refund code (see table below)	"MD06"

Accepted aliases

The following fields are also accepted as aliases for original_transaction_id: original_e2e_id, transaction_id, end_to_end_id.

Monetary values

The request amount is in centavos (R$ 30.00 = 3000). The response amount is in base units (R$ 30.00 = 300000). Never use floating point.

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='{"original_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"

Success Response (200)

{
  "worked": true,
  "refund_id": "PIXRET20260307a1b2c3d4e5f6",
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "amount": 300000,
  "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 base units (/ 10,000 for BRL). 300000 = R$ 30.00
status	String	Initial status: processing

Error Response (404)

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

Error Response (422)

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

Error Response (422) -- Amount exceeded

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

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.