Devolucion PIX

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

Endpoint

POST /api/v2/external/pix/refund

Encabezados

Encabezado	Tipo	Obligatorio	Descripcion
Authorization	String	Si	Bearer {access_token}
Content-Type	String	Si	application/json
hmac	String	Si	Firma HMAC-SHA512 del body (mas informacion)

Request Body

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

Devolucion parcial

Para devolucion parcial, indique 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":"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"

Respuesta Exitosa (200)

{
  "worked": true,
  "refund_id": "PIXRET20260307a1b2c3d4e5f6",
  "transaction_id": "PIXIN20260307a1b2c3d4e5f6",
  "amount": 10000,
  "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 centavos
status	String	Estado inicial: processing

Respuesta de Error (404)

{
  "worked": false,
  "detail": "Transaccion original no encontrada"
}

Respuesta de Error (422)

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

Respuesta de Error (422) -- Valor excedido

{
  "worked": false,
  "detail": "El valor de la devolucion excede el valor original de la transaccion"
}

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.