MED (Special Refund Mechanism)
The MED (Special Refund Mechanism) is a Central Bank procedure that protects Pix users in cases of fraud, scam, or unauthorized transactions.
It works as a "safety net" of the arrangement: when suspicious activity is identified, the payer's institution opens a formal process requesting the refund.
At PayZu, the MED flow is delivered via webhook, reusing the
same callbackUrl of the transaction. The status of the original operation is
updated and the infraction object is inserted into the payload.
Conceptual MED flow
Hover over the boxes to see the technical status. Click to go directly to the section that details each value.
The high-level flow:
- Pix transaction completed successfully.
- Problem identified (fraud, error, unauthorized charge).
- Payer's institution opens the MED in the arrangement, webhook arrives with
status: "OPEN". - Receiving bank is notified and may block the amount during analysis.
- Dispute analysis by the institutions + Bacen rules.
- Result: accepted (
AGREED, amount refunded) or rejected (DISAGREED, transaction remains valid).
Example of webhook with infraction
Real example of the payload received when a Pix transaction is subject to an infraction:
{
"id": "PAYZU20251123104518DF75D20A8F",
"type": "DEPOSIT",
"status": "COMPLETED",
"serviceFeeCharged": 1,
"amount": 30,
"clientReference": "d2b2a5ed-f1a4-477e-81da-9",
"qrCodeText": "00020101021226870014br.gov.bcb.pix...",
"payerName": "João da Silva",
"payerDocument": "12345678901",
"payerInstitutionName": "PAYZU IP",
"receiverName": "PAYZU LTDA",
"receiverDocument": "123456789010110",
"endToEndId": "E18236120202511231046s1235ee7",
"paidAt": "2025-11-23T10:46:26.986Z",
"createdAt": "2025-11-23T10:45:18.403Z",
"updatedAt": "2025-11-23T10:46:27.346Z",
"callbackUrl": "https://seuwebhook.com",
"infraction": {
"id": "cmide759mb9i3s601bhwf6e",
"protocol": "4dd32924-9b53-4408-af4b-6d3b4d7ac",
"status": "OPEN",
"type": "REFUND_REQUEST",
"reportDetails": "Fraud report: transaction formally contested by the payer",
"reportedBy": "DEBITED_PARTICIPANT",
"analysisResult": null,
"analysisDetails": null,
"reportedAt": "2025-11-24T16:52:15.808Z",
"createdAt": "2025-11-24T17:00:00.490Z",
"updatedAt": "2025-11-24T17:00:00.490Z"
}
}Fields of the infraction object
| Field | Type | Description |
|---|---|---|
id | string | Unique infraction identifier |
protocol | string | Payment provider protocol number |
status | InfractionStatus | Current infraction status |
type | InfractionType | Infraction type |
reportDetails | string | Description of the dispute reason |
reportedBy | ReportedBy | Who reported the infraction |
analysisResult | AnalysisResult | null | Final decision (null while pending) |
analysisDetails | string | null | Decision justification |
reportedAt | string | When it was reported |
expiresAt | string | null | Deadline for resolution |
createdAt | string | Creation date |
updatedAt | string | Last update |
status values (InfractionStatus)
| Value | Description |
|---|---|
WAITING_PSP | Awaiting provider response |
OPEN | Active and under analysis |
ACKNOWLEDGED | Acknowledged by the institution |
DEFENDED | Defense has been submitted |
ANSWERED | Additional information has been provided |
WAITING_ADJUSTMENTS | Awaiting documentation |
CLOSED | Resolved with final decision |
CANCELLED | Cancelled before resolution |
type values (InfractionType)
| Value | Description |
|---|---|
REFUND_REQUEST | Standard refund request |
FRAUD | Security-related complaint |
REFUND_CANCELLED | Cancellation of previous refund |
reportedBy values
| Value | Description |
|---|---|
DEBITED_PARTICIPANT | Reported by the payer's institution |
CREDITED_PARTICIPANT | Reported by the receiver's institution |
analysisResult values
| Value | Description |
|---|---|
AGREED | Infraction accepted: refund will be processed |
DISAGREED | Infraction rejected: no refund |
How to react when you receive an infraction
Detect the callback
When the infraction object arrives in the payload, trigger an internal alert immediately. The Bacen deadline is short, typically 72h, and silence is usually interpreted as acceptance.
if (callback.infraction?.status === 'OPEN') {
await alertOperations({
transactionId: callback.id,
infractionId: callback.infraction.id,
expiresAt: callback.infraction.expiresAt,
reportDetails: callback.infraction.reportDetails,
});
}Investigate
Use GET /user/infractions/{id} for full details of the dispute, original transaction, and deadline. Cross-reference with your logs:
- DICT logs before the payment (if a withdrawal)
- Who performed the operation in your system
- Customer IP, device, session
- Transaction history for that
payerDocument
Decide: defend or accept
| Scenario | Recommended decision |
|---|---|
| Legitimate charge, you have evidence of product/service delivery | Defend via POST /user/infractions/{id}/defenses |
| Real suspicion of fraud on your side (compromised customer) | Accept (do not defend). The amount is refunded and the case closes. |
| You have no evidence | Evaluate case by case. Without defense, Bacen tends to accept the contestation. |
Track until CLOSED
The infraction goes through states (OPEN → ACKNOWLEDGED/DEFENDED → ANSWERED/WAITING_ADJUSTMENTS → CLOSED). Each change generates a new callback. The final result comes in analysisResult when status: "CLOSED".
Complete lifecycle
Financial impact
When the infraction is AGREED
When the infraction is DISAGREED
TrueHolder
Trava de segurança que valida a titularidade do documento (CPF/CNPJ) antes de processar a transação. Funciona tanto em cash-in (depósito) quanto em cash-out (saque), bloqueando movimentações fora do titular autorizado.
Tipos de chave Pix
Tipos de chave Pix aceitos pela API PayZu, formato esperado de cada um e regras de validação.