Détails MED

Consultez les détails complets d'un processus MED (Mécanisme Spécial de Restitution) spécifique.

Endpoint

GET /api/external/med/:id

Headers

Header	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Non	Définissez à camelCase pour recevoir les champs de la réponse en camelCase (par défaut snake_case)

Path Parameters

Paramètre	Type	Obligatoire	Description
id	String	Oui	Identifiant du processus MED

Exemple

curl -X GET https://api.owem.com.br/api/external/med/MED20260307001 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Réponse de succès (200)

{
  "worked": true,
  "med": {
    "id": "MED20260307001",
    "type": "REFUND_REQUEST",
    "status": "ACKNOWLEDGED",
    "amount": 50000,
    "original_end_to_end_id": "E37839059202603071530000001",
    "reason": "Fraude signalée par le payeur",
    "created_at": "2026-03-07T18:00:00Z"
  }
}

Status en UPPERCASE

Valeurs possibles : ACKNOWLEDGED, CLOSED, CANCELLED. Transmises telles que reçues du provider PIX (OnZ/BACEN) — sans normalisation. Voir med-list pour les détails.

Champ	Type	Description
worked	Boolean	true indique le succès de l'opération
med.id	String	Identifiant unique du MED
med.type	String	Type : REFUND_REQUEST ou REFUND_CANCELLED
med.status	String	Status actuel du processus (ACKNOWLEDGED, CLOSED, CANCELLED)
med.amount	Integer	Valeur en unités de base (÷ 10 000 pour reais). 50000 = R$ 5,00
med.original_end_to_end_id	String	E2E de la transaction PIX originale. Utilisez pour croiser avec GET /transactions/ref/:external_id
med.reason	String	Motif indiqué par le demandeur (texte libre). null si non disponible
med.created_at	String	Date d'ouverture (ISO 8601 UTC)

Champs additionnels non exposés via External API

Le provider OnZ/BACEN retourne plus de champs que ceux exposés par cet endpoint. Les champs filtrés délibérément dans le serializer incluent :

Champ (OnZ)	Description	Où l'obtenir aujourd'hui
analysisResult	Décision finale : AGREED ou DISAGREED	Webhook pix.infraction.resolved
analysisDetails	Justification de la décision	Webhook pix.infraction.resolved
infractionType	REFUND_REQUEST ou REFUND_CANCELLED	Déjà exposé dans med.type
fraudType	SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER	Webhook pix.refund.requested (champ fraud_category)
situationType	Type de situation impliquée (taxonomie BACEN)	Merchant portal (/compliance) — non disponible via External API
defenseDeadline	Délai BACEN pour soumission de défense	Webhook pix.infraction.created

Cette omission est délibérée (gap connu). Si vous devez consommer ces champs programmatiquement, contactez compliance@owem.com.br — ou utilisez les webhooks listés, qui apportent toujours les champs pertinents au moment de l'événement.

Voir Infractions (flux complet) pour comprendre la relation entre MED et Infractions.

Valeur en subcentavos, pas en BRL

Le champ amount est en subcentavos (1 BRL = 10 000 subcentavos). Valeur 50000 = R$ 5,00 — pas R$ 50 000. Ne multipliez jamais par 100 ni n'utilisez de float.

Réponse d'erreur (404)

{
  "worked": false,
  "errors": {
    "not_found": "MED não encontrado"
  }
}

404 peut indiquer une erreur transitoire

Si le MED existe dans un autre canal (webhook, listing précédent) mais retourne 404 dans cette consultation, il peut s'agir d'une défaillance transitoire du provider OnZ. Réessayez dans quelques secondes. Si cela persiste après 5 min, contactez le support.

Le backend convertit toutes les erreurs du provider (y compris timeouts et erreurs réseau) en HTTP 404 avec detail: "MED nao encontrado". Pour distinguer « n'existe pas » de « défaillance transitoire », consultez d'abord l'endpoint Liste MED — si l'ID apparaît dans la liste mais le detail retourne 404, c'est transitoire.

Réponse d'erreur (401)

{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}

Suivi en temps réel (webhooks)

Les événements webhook pix.refund.requested et pix.refund.completed SONT déclenchés automatiquement par le backend depuis avril/2026. Il est recommandé de s'abonner à ces webhooks pour ne pas dépendre du polling. Le polling sur GET /med/:id ou GET /med continue à fonctionner comme alternative.