Infractions PIX et MED

Cette page explique comment suivre et repondre aux contestations PIX liees au MED via l'API Minha Konta.

Resume

Une infraction PIX est une contestation ouverte par l'institution du payeur. Quand elle exige une analyse, vous recevez des webhooks, pouvez consulter le MED et pouvez envoyer une defense avec contexte et preuves dans le delai indique.

---

1. Concepts Principaux

Concept	Description
Infraction PIX	Contestation formelle liee a un PIX recu
MED	Flux reglementaire utilise pour l'analyse et une eventuelle restitution
Blocage conservatoire	Reservation temporaire de la valeur contestee pendant l'analyse
Defense	Justification envoyee par le client, accompagnee de preuves si disponibles
Decision	Resultat final du cas, avec restitution ou liberation de la valeur

Le MED fait partie du cycle reglementaire de contestation. Il peut affecter le solde disponible pendant l'analyse.

---

2. Comment Suivre

Utilisez les webhooks pour recevoir les mises a jour en temps reel:

Evenement	Quand l'utiliser
pix.infraction.created	Une contestation a ete enregistree et demande un suivi
pix.refund.requested	Une valeur est entree dans le flux MED
pix.infraction.defense_submitted	Une defense a ete enregistree
pix.infraction.resolved	La contestation a ete finalisee
pix.refund.completed	La restitution a ete executee
pix.payout.returned	L'ecriture de restitution a ete confirmee

Voir les exemples dans Payloads Webhook.

---

3. Consultation via API

GET /api/external/med
GET /api/external/med/{id}

Permission requise: payment:read.

Utilisez le id retourne par les webhooks ou par la liste pour consulter le cas et le correler avec le original_end_to_end_id du PIX conteste.

---

4. Envoyer une Defense via API

POST /api/external/med/{id}/defense
Content-Type: application/json
Authorization: ApiKey {client_id}:{client_secret}
hmac: {signature_hmac_sha512}

Permission requise: payment:write.

Le body doit etre JSON et signe avec le meme standard HMAC utilise par les autres endpoints POST de l'API externe.

{
  "defense_text": "Le client a confirme l'operation et envoye une preuve du service.",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://votre-domaine.example/preuves/med-123.png",
      "description": "Capture de conversation avec confirmation du titulaire",
      "source": "whatsapp",
      "filename": "conversation-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}

Champ	Type	Obligatoire	Description
defense_text	string	Oui	Texte de defense et contexte de la contestation
evidence	array	Non	Liste de preuves referencees par URL ou description
evidence[].type	string	Non	url, document, image, screenshot, email, whatsapp ou other
evidence[].url	string	Conditionnel	URL https ou http d'une preuve hebergee par le client
evidence[].description	string	Conditionnel	Resume de la preuve lorsqu'il n'y a pas d'URL

Chaque item de evidence doit contenir au moins url ou description. L'API accepte jusqu'a 10 preuves par soumission.

Preuves

L'API externe enregistre le texte et les references de preuve. L'upload binaire d'annexes reste disponible dans les portails Minha Konta, ou les fichiers sont valides et stockes pour analyse et audit.

---

5. Portails et Preuves Externes

Les defenses peuvent aussi etre traitees dans les portails Minha Konta. Ce chemin permet d'attacher directement des fichiers comme PDFs, images, captures, contrats et historiques de support.

Lorsque des preuves arrivent par e-mail, WhatsApp, support ou un autre canal hors API, l'operation Minha Konta peut les enregistrer dans le cas. Elles restent archivees pour consultation, verification future et audit.

---

6. Delais

Le delai de reponse arrive dans defense_deadline dans les webhooks lies a l'infraction. Repondez avant ce delai pour que la defense puisse etre analysee et envoyee correctement.

Recommandations:

• Surveillez pix.infraction.created et pix.refund.requested.
• Consultez le MED par le id recu.
• Envoyez la defense par API ou portail des que vous avez les donnees du client.
• Conservez e2e_id, med_id et l'heure de soumission.

---

7. Reconciliation

Utilisez e2e_id comme cle de correlation entre le PIX original, les webhooks d'infraction, le registre MED et une eventuelle restitution.

analysis_result	Interpretation
AGREED	Contestation acceptee et restitution executee
DISAGREED	Defense acceptee ou contestation rejetee, sans restitution
null	Cas annule ou sans decision applicable