Devolucao PIX

Inicia uma devolucao (total ou parcial) de uma transacao PIX recebida.

Endpoint

POST /api/v2/external/pix/refund

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	Bearer {access_token}
Content-Type	String	Sim	application/json
hmac	String	Sim	Assinatura HMAC-SHA512 do body (saiba mais)

Request Body

Campo	Tipo	Obrigatorio	Descricao	Exemplo
transaction_id	String	Sim	ID da transacao PIX original recebida	"PIXIN20260307a1b2c3d4e5f6"
amount	Integer	Nao	Valor a devolver em centavos. Se omitido, devolve o valor total.	5000 (R$ 50,00)
reason	String	Sim	Codigo de devolucao BACEN (veja tabela abaixo)	"MD06"

Devolucao parcial

Para devolucao parcial, informe um amount menor que o valor original. O valor total das devolucoes de uma mesma transacao nao pode exceder o valor original recebido.

Codigos de Devolucao

Codigo	Descricao
MD06	Devolucao por acordo entre as partes
BE08	Fraude
AM09	Valor incorreto
SL02	Erro de liquidacao
RR04	Transacao nao reconhecida

Exemplo

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"

Resposta de Sucesso (200)

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

Campo	Tipo	Descricao
worked	Boolean	true indica sucesso na operacao
refund_id	String	Identificador unico da devolucao
transaction_id	String	ID da transacao original
amount	Integer	Valor da devolucao em centavos
status	String	Status inicial: processing

Resposta de Erro (404)

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

Resposta de Erro (422)

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

Resposta de Erro (422) -- Valor excedido

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

Prazo para devolucao

Devolucoes com codigo MD06 (acordo) podem ser realizadas em ate 90 dias apos o recebimento. Devolucoes por fraude (BE08) seguem os prazos do MED definidos pelo BACEN.