Devolucao PIX

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

Endpoint

POST /api/external/pix/refund

Headers

Header	Tipo	Obrigatorio	Descricao
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
Content-Type	String	Sim	application/json
hmac	String	Sim	Assinatura HMAC-SHA512 do body (saiba mais)
Idempotency-Key	String	Nao	Chave unica para evitar processamento duplicado (max 256 chars)

Request Body

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

Aliases aceitos

Os seguintes campos tambem sao aceitos como alias para original_transaction_id: original_e2e_id, transaction_id, end_to_end_id.

Valores monetarios

O amount da requisicao e em centavos (R$ 30,00 = 3000). O amount da resposta e em unidades base (R$ 30,00 = 300000). Nunca use ponto flutuante.

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

Resposta de Sucesso (200)

{
  "worked": true,
  "refund_id": "PIXRET20260307a1b2c3d4e5f6",
  "transaction_id": "7popu57v6us7p6pcicgq12345",
  "amount": 300000,
  "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 unidades base (÷ 10.000 para reais). 300000 = R$ 30,00
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.