Devolucion PIX

Inicia una devolucion (total o parcial) de una transaccion PIX recibida.

Endpoint

POST /api/external/pix/refund

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret}
Content-Type	String	Si	application/json
hmac	String	Si	Firma HMAC-SHA512 del body (mas informacion)
Idempotency-Key	String	No	Clave unica para evitar procesamiento duplicado (max 256 chars)

Request Body

Campo	Tipo	Obligatorio	Descripcion	Ejemplo
transaction_id	String	Si	ID de la transaccion PIX original recibida	"7popu57v6us7p6pcicgq12345"
amount	Integer	No	Valor a devolver en centavos. Si se omite, se devuelve el valor total.	3000 (R$ 30,00)
reason	String	Si	Codigo de devolucion BACEN (ver tabla a continuacion)	"MD06"

Valores monetarios

El amount de la solicitud es en centavos (R$ 30,00 = 3000). El amount de la respuesta es en unidades base (R$ 30,00 = 300000). Nunca use punto flotante.

Devolucion parcial

Para devolucion parcial, informe un amount menor que el valor original. El valor total de las devoluciones de una misma transaccion no puede exceder el valor original recibido.

Codigos de Devolucion

Codigo	Descripcion
MD06	Devolucion por acuerdo entre las partes
BE08	Fraude
AM09	Valor incorrecto
SL02	Error de liquidacion
RR04	Transaccion no reconocida

Ejemplo

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"

Respuesta de Exito (200)

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

Campo	Tipo	Descripcion
worked	Boolean	true indica exito en la operacion
refund_id	String	Identificador unico de la devolucion
transaction_id	String	ID de la transaccion original
amount	Integer	Valor de la devolucion en unidades base (/ 10.000 para reales). 300000 = R$ 30,00
status	String	Estado inicial: processing

Respuesta de Error (404)

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

Respuesta de Error (422)

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

Respuesta de Error (422) -- Valor excedido

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

Plazo para devolucion

Las devoluciones con codigo MD06 (acuerdo) pueden realizarse en un plazo de hasta 90 dias despues de la recepcion. Las devoluciones por fraude (BE08) siguen los plazos del MED definidos por el BACEN.