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.minhakonta.com/api/external/med \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Pas de pagination native

Cet endpoint consulte le provider PIX/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": "E04838403202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E04838403202603051200000003",
      "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 (PIX/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 PIX directement - il ne lit pas depuis une table locale. En dev/homologation il peut retourner un tableau vide si le provider PIX 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 PIX/BACEN.

Les défaillances du provider retournent un tableau vide

En cas d'indisponibilité temporaire du provider PIX, 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>"
  }
}

Valeurs en dispute

Quand un MED exige une analyse, la valeur contestee peut etre temporairement reservee et apparaitre dans pending jusqu'a la decision finale.

Quand le MED est resolu (CLOSED):

• AnalysisResult=AGREED indique une contestation acceptee et une restitution executee.
• AnalysisResult=DISAGREED indique une contestation rejetee ou une defense acceptee, sans restitution.

Abonnez-vous aux webhooks pix.infraction.created, pix.refund.requested, pix.infraction.defense_submitted et pix.infraction.resolved. Pour repondre a un MED via API, utilisez POST /api/external/med/:id/defense avec payment:write. Voir Infractions.