Remboursement PIX

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

Endpoint

POST /api/v2/external/pix/refund

En-tetes

En-tete	Type	Obligatoire	Description
Authorization	String	Oui	Bearer {access_token}
Content-Type	String	Oui	application/json
hmac	String	Oui	Signature HMAC-SHA512 du body (en savoir plus)

Request Body

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

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":"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"

Reponse de Succes (200)

{
  "worked": true,
  "refund_id": "PIXRET20260307a1b2c3d4e5f6",
  "transaction_id": "PIXIN20260307a1b2c3d4e5f6",
  "amount": 10000,
  "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 centimes
status	String	Statut initial : processing

Reponse d'Erreur (404)

{
  "worked": false,
  "detail": "Transaction originale introuvable"
}

Reponse d'Erreur (422)

{
  "worked": false,
  "detail": "Solde insuffisant pour le remboursement"
}

Reponse d'Erreur (422) -- Montant depasse

{
  "worked": false,
  "detail": "Le montant du remboursement depasse le montant original de la transaction"
}

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.