Remboursement PIX

Initie un remboursement (total ou partiel) d'une transaction PIX recue.

Endpoint

POST /api/external/pix/refund

En-tetes

En-tete	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
Content-Type	String	Oui	application/json
hmac	String	Oui	Signature HMAC-SHA512 du body (en savoir plus)
Idempotency-Key	String	Non	Cle unique pour eviter le traitement en double (max 256 chars)

Request Body

Champ	Type	Obligatoire	Description	Exemple
transaction_id	String	Oui	ID de la transaction PIX originale recue	"7popu57v6us7p6pcicgq12345"
amount	Integer	Non	Montant a rembourser en centavos. Si omis, rembourse le montant total.	3000 (R$ 30,00)
reason	String	Oui	Code de remboursement BACEN (voir tableau ci-dessous)	"MD06"

Valeurs monetaires

Le amount de la requete est en centavos (R$ 30,00 = 3000). Le amount de la reponse est en unites de base (R$ 30,00 = 300000). N'utilisez jamais de virgule flottante.

Remboursement partiel

Pour un remboursement partiel, indiquez un amount inferieur au montant original. Le montant total des remboursements d'une meme transaction ne peut pas depasser le montant original recu.

Codes de Remboursement

Code	Description
MD06	Remboursement par accord entre les parties
BE08	Fraude
AM09	Montant incorrect
SL02	Erreur de liquidation
RR04	Transaction non reconnue

Exemple

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"

Reponse de Succes (200)

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

Champ	Type	Description
worked	Boolean	true indique le succes de l'operation
refund_id	String	Identifiant unique du remboursement
transaction_id	String	ID de la transaction originale
amount	Integer	Montant du remboursement en unites de base (/ 10 000 pour reais). 300000 = R$ 30,00
status	String	Statut initial : processing

Reponse d'Erreur (404)

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

Reponse d'Erreur (422)

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

Reponse d'Erreur (422) -- Montant depasse

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

Delai de remboursement

Les remboursements avec le code MD06 (accord) peuvent etre effectues dans un delai de 90 jours apres la reception. Les remboursements pour fraude (BE08) suivent les delais MED definis par le BACEN.