Liste MED

Liste les processus MED (Mécanisme Spécial de Restitution) associés au compte.

Le MED est un mécanisme de la Banque Centrale pour la récupération de valeurs en cas de fraude ou de défaillance opérationnelle sur le système PIX.

Endpoint

GET /api/external/med

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)

Permissions

Cet endpoint exige la permission payment:read sur l'API Key. Les clés sans cette permission reçoivent HTTP 403.

Exemple

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

Pas de pagination native

Cet endpoint consulte le provider OnZ/BACEN en temps réel et n'accepte pas de paramètres de pagination (page/per_page/limit). Tous les MED liés à l'entité sont retournés dans une seule réponse. Pour de grands volumes, filtrez localement dans votre système après réception du tableau.

Réponse de succès (200)

{
  "worked": true,
  "meds": [
    {
      "id": "MED20260307001",
      "type": "REFUND_REQUEST",
      "status": "ACKNOWLEDGED",
      "amount": 50000,
      "original_end_to_end_id": "E37839059202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E37839059202603051200000003",
      "created_at": "2026-03-05T14:30:00Z"
    }
  ]
}

Champ	Type	Description
worked	Boolean	true indique le succès de l'opération
meds	Array	Liste des processus MED
meds[].id	String	Identifiant unique du MED
meds[].type	String	Type du MED (voir tableau ci-dessous)
meds[].status	String	Status actuel du processus
meds[].amount	Integer	Valeur en unités de base (÷ 10 000 pour reais). 50000 = R$ 5,00
meds[].original_end_to_end_id	String	E2E de la transaction PIX originale
meds[].created_at	String	Date d'ouverture (ISO 8601)

Types de MED

Type	Description
REFUND_REQUEST	Demande de remboursement (fraude, escroquerie ou accord)
REFUND_CANCELLED	Annulation d'une demande de remboursement précédente

Status du MED

Valeurs retournées par le provider PIX (OnZ/BACEN) en MAJUSCULES. L'API transmet la valeur telle que reçue — il n'y a pas de normalisation.

Status	Description	Décision finale
ACKNOWLEDGED	MED reçu et reconnu par le participant, en analyse	Non — en attente de défense ou du délai
CLOSED	MED finalisé par le participant	Oui — voir analysisResult dans med-detail pour distinguer AGREED (remboursement exécuté) de DISAGREED (défense acceptée, sans remboursement)
CANCELLED	MED annulé par le demandeur avant analyse	Oui — aucune valeur n'a été bloquée ni remboursée

Status en uppercase

Les status MED sont toujours retournés en MAJUSCULES. Si votre filtre attend des minuscules (pending/accepted/closed), il ne trouvera aucune ligne. C'est une différence consciente par rapport aux status de transaction PIX (lowercase) — MED suit la convention BACEN originale.

Corrélation avec transaction originale

Utilisez le champ original_end_to_end_id pour localiser la transaction PIX originale qui a motivé le MED. Consultez via GET /api/external/transactions/:id ou GET /api/external/transactions/ref/:external_id si vous avez stocké l'external_id.

Retour dans les environnements dev/homologation

Cet endpoint consulte le provider OnZ directement — il ne lit pas depuis une table locale. En dev/homologation il peut retourner un tableau vide si le provider OnZ n'a pas de MEDs de test pour l'entité configurée. En production, il retourne la liste réelle des processus MED de votre compte telle que transmise par OnZ/BACEN.

Les défaillances du provider retournent un tableau vide

En cas d'indisponibilité temporaire du provider OnZ, l'endpoint retourne {"worked": true, "meds": []} (silencieusement, sans 5xx). Si vous recevez un tableau vide de façon persistante alors que vous attendez des MEDs, consultez le support pour vérifier s'il y a indisponibilité du provider.

Réponse de succès -- sans MEDs (200)

{
  "worked": true,
  "meds": []
}

Réponse d'erreur (401)

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

Blocage de valeurs en dispute

Quand une infraction REFUND_REQUEST est enregistrée en ACKNOWLEDGED avec une valeur >R$ 1 000,00 (seuil configurable par compte ou merchant via med_configurations.min_threshold_amount), le backend crée un blocage conservatoire dans TigerBeetle (med_cautelar_blocks row + phantom hold TB code 1032). La valeur contestée :

• Est déduite de l'available retourné par Solde
• S'ajoute à pending
• Est préservée dans le balance (solde sécurisé) jusqu'à la décision finale

Les infractions avec valeur ≤R$ 1 000,00 ou avec e2e_id inexistant dans vos transactions reçoivent un auto-deny automatique (fermeture avec AnalysisResult=DISAGREED) sans créer de blocage conservatoire.

Quand le MED est résolu (CLOSED), le blocage est libéré :

• AnalysisResult=AGREED → valeur transférée au demandeur (remboursement PIX via PACS.004, E2E préfixe D)
• AnalysisResult=DISAGREED → valeur retourne dans l'available du merchant

Abonnez-vous aux webhooks pix.infraction.created, pix.refund.requested et pix.infraction.resolved pour une notification en temps réel de chaque étape. Voir Infractions (flux complet) pour comprendre le cycle end-to-end.

Auto-expiration : le worker Fluxiq.Workers.MedDefenseExpiration (cron */5 * * * *) auto-accepte les blocages dont la deadline est dans les 30 prochaines minutes et dont la défense n'a pas encore été soumise — cela évite une amende réglementaire BACEN pour non-réponse dans les délais. Voir section « Délais » dans Infractions.