ADOPAY Developer Platform

Appearance

MED Webhook Notifications ​

1. Overview ​

MED (Mecanismo Especial de Devolução, Special Refund Mechanism) is the Pix fraud refund mechanism regulated by the Brazilian Central Bank. When a MED status or funds freeze status changes, or a refund operation is executed, Adopay sends the corresponding event notification to the merchant via an asynchronous HTTP callback.

MED has eight event types. All event payloads use the full structure: besides the common fields and the event-specific fields, every event carries the exact field set of the data object returned by Query MED Details (the summary fields plus the transaction, payer, payee, infractionReport, funds, analysis, and chargebacks groups) — whatever fields the detail endpoint returns, the webhook payload carries. Webhooks are Adopay-initiated notifications and do not use the standard API status, msg, and data response envelope.

2. Callback URL and Method ​

ItemValue
MethodPOST
URLThe MED webhook callback URL configured by the merchant; must be a full HTTPS URL
Content-Typeapplication/json
PurposeNotify MED status changes, funds freeze status changes, and refund execution results

3. Request Headers ​

Callback requests carry the signature and verification headers following the Adopay platform-wide convention. Common rules (HTTPS transport, timeout, failure handling, idempotency, signature verification) are described in Webhook Specification.

4. Request Body Fields ​

Common Fields (all events) ​

FieldTypeRequiredDescription
eventstringYesEvent type; see the event type mapping below.
occurredAtstringYesTime the event occurred, ISO 8601 UTC time string (yyyy-MM-ddTHH:mm:ssZ).

Full MED Fields (carried by all events) ​

Besides the common fields, all events carry the full field set identical to the data object of Query MED Details: field names, types, and meanings are the same as in the detail endpoint, with values being the latest snapshot of the MED at the moment the event occurred (was delivered).

Field GroupIncluded FieldsDescription
Summary fieldsmedId, status, originSituationType, details, amount, analysisResult, dueTime, createdAt, updatedAtMED summary information, at the top level of the payload.
Transaction informationtransactionThe Pix transaction that triggered the MED (including e2eId, transactionDate, merchantOrderNo, platOrderNo).
PayerpayerPayer information and bank account.
PayeepayeePayee information and bank account.
Infraction reportinfractionReportCentral bank infraction report information.
Funds statusfundsMerchant funds freeze status.
Analysis informationanalysisAnalysis verdict and analysis process information.
Chargeback historychargebacksRefund (chargeback) execution history.

For the type, length limits, and value descriptions of each field, see the response fields of Query MED Details; they are not repeated here.

Event-Specific Fields ​

MED_REFUND_EXECUTED additionally carries the event-specific field chargeback (the record of this refund execution) beyond the full fields; see the per-event descriptions in section 5.

Event Type Mapping ​

Event TypeTriggerMED Status When the Event Fires
MED_CREATEDThe infraction report is received and registeredWAITING
MED_APPROVEDThe platform ruling confirms the MED is upheld and the refund flow startsACCEPTED_BY_PSP
MED_REFUND_EXECUTEDFired once for each refund (chargeback) operation executed; multiple refunds on the same MED are delivered multiple timesDoes not change the MED status (ACCEPTED_BY_PSP when triggered)
MED_REJECTEDThe platform ruling confirms the MED is not upheldREJECTED_BY_PSP
MED_CANCELLEDThe MED is cancelled before a ruling is made (originator withdrawal or platform termination)CANCELLED_BY_USER / CANCELLED_BY_PSP
MED_ANALYSIS_REJECTEDThe platform returns the merchant's submitted dispute analysis (e.g. insufficient evidence)EVIDENCE_REQUIRED
MED_FUNDS_FROZENThe merchant's disputed transaction funds are frozenTriggered independently of status events; does not change the MED status
MED_FUNDS_UNFROZENThe merchant's disputed transaction funds are unfrozenTriggered independently of status events; does not change the MED status

5. Event-Specific Fields and Examples ​

The following subsections describe only each event's trigger logic and event-specific fields (all events carry the full MED fields, which are not listed per event); the examples are complete payloads and can be used directly as integration references.

5.1 MED_CREATED (infraction report registered) ​

Fired when the MED is created. No event-specific fields; in the full fields, status is WAITING, analysisResult is null, and chargebacks is an empty array.

json
{
  "event": "MED_CREATED",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-15T14:30:00Z",
  "status": "WAITING",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": null,
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-15T14:30:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "RECEIVED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "FROZEN",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": null
  },
  "analysis": {
    "analysisResult": null,
    "analysisDetailsUser": null,
    "analysisDetailsPsp": null
  },
  "chargebacks": []
}

5.2 MED_APPROVED (MED upheld) ​

Fired when the platform ruling confirms the MED is upheld and the refund flow starts. No event-specific fields; in the full fields, status is ACCEPTED_BY_PSP and analysisResult is ACCEPTED. This event only marks the start of the refund flow; after it, every refund operation executed is delivered separately as a MED_REFUND_EXECUTED (see 5.3).

json
{
  "event": "MED_APPROVED",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-16T10:30:00Z",
  "status": "ACCEPTED_BY_PSP",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": "ACCEPTED",
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-16T10:30:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "ANALYZED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "FULLY_REFUNDED",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": "2026-01-16T10:30:00Z"
  },
  "analysis": {
    "analysisResult": "ACCEPTED",
    "analysisDetailsUser": "User analysis details",
    "analysisDetailsPsp": "PSP confirmed fraudulent transaction"
  },
  "chargebacks": []
}

5.3 MED_REFUND_EXECUTED (refund executed) ​

Adopay delivers this event once for each refund (chargeback) operation executed for the MED; if multiple refunds are executed for the same MED (e.g. supplementary deductions, partial refunds), each execution is delivered as a separate notification and is never merged.

FieldTypeRequiredDescription
chargebackobjectYesThe refund record executed this time, with the same structure as a data.chargebacks[] element in the detail endpoint.
chargeback.statusstringYesResult of this refund execution, always SUCCESS (this event is delivered only when the refund is executed successfully).
chargeback.infoTextstringYesAdditional information about this refund, maximum length 255 characters.
chargeback.errorDescriptorstringNoError description when this refund execution fails; always null in this event.
chargeback.amountdecimalYesRefund amount executed this time.
chargeback.createdAtstringYesCreation time of this refund, ISO 8601 UTC time string (yyyy-MM-ddTHH:mm:ssZ).
chargeback.updatedAtstringYesCompletion time of this refund, ISO 8601 UTC time string (yyyy-MM-ddTHH:mm:ssZ).

The chargebacks in the payload is the full refund history up to this execution (including the record of this execution). If the refund execution result changes afterwards, the chargebacks history and Query MED Details are authoritative.

json
{
  "event": "MED_REFUND_EXECUTED",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-16T10:35:00Z",
  "status": "ACCEPTED_BY_PSP",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": "ACCEPTED",
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-16T10:35:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "ANALYZED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "FULLY_REFUNDED",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": "2026-01-16T10:30:00Z"
  },
  "analysis": {
    "analysisResult": "ACCEPTED",
    "analysisDetailsUser": "User analysis details",
    "analysisDetailsPsp": "PSP confirmed fraudulent transaction"
  },
  "chargebacks": [
    {
      "status": "SUCCESS",
      "infoText": "Chargeback successful",
      "errorDescriptor": null,
      "amount": 1000.50,
      "createdAt": "2026-01-16T09:20:00Z",
      "updatedAt": "2026-01-16T10:35:00Z"
    }
  ],
  "chargeback": {
    "status": "SUCCESS",
    "infoText": "Chargeback successful",
    "errorDescriptor": null,
    "amount": 1000.50,
    "createdAt": "2026-01-16T09:20:00Z",
    "updatedAt": "2026-01-16T10:35:00Z"
  }
}

5.4 MED_REJECTED (MED not upheld) ​

Fired when the platform ruling confirms the MED is not upheld. No event-specific fields; in the full fields, status is REJECTED_BY_PSP and analysisResult is REJECTED; the funds unfreeze is delivered separately as MED_FUNDS_UNFROZEN (see 5.8).

json
{
  "event": "MED_REJECTED",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-16T09:20:00Z",
  "status": "REJECTED_BY_PSP",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": "REJECTED",
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-16T09:20:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "ANALYZED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "UNFROZEN",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": "2026-01-16T09:20:00Z"
  },
  "analysis": {
    "analysisResult": "REJECTED",
    "analysisDetailsUser": "User analysis details",
    "analysisDetailsPsp": "PSP confirmed fraudulent transaction"
  },
  "chargebacks": []
}

5.5 MED_CANCELLED (MED cancelled) ​

Fired when the originator cancels the MED before a ruling is made. No event-specific fields; in the full fields, status is CANCELLED_BY_USER and analysisResult is null; the funds unfreeze is delivered separately as MED_FUNDS_UNFROZEN (see 5.8).

json
{
  "event": "MED_CANCELLED",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-17T12:00:00Z",
  "status": "CANCELLED_BY_USER",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": null,
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-17T12:00:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "CANCELLED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "UNFROZEN",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": "2026-01-17T12:00:00Z"
  },
  "analysis": {
    "analysisResult": null,
    "analysisDetailsUser": null,
    "analysisDetailsPsp": null
  },
  "chargebacks": []
}

5.6 MED_ANALYSIS_REJECTED (dispute analysis returned by the platform) ​

Fired when a dispute analysis (REJECTED) submitted via Submit Analysis Result is returned by the platform (e.g. insufficient evidence; the merchant must supplement it and resubmit). The returned analysis does not take effect, and the MED status changes to EVIDENCE_REQUIRED (in the full fields, status is EVIDENCE_REQUIRED, analysisResult is null, and the funds remain frozen); the merchant can resubmit the analysis after providing the additional evidence. This event has no event-specific fields; the specific reason for the return is not delivered with the event — check the merchant portal or contact the platform if you need it.

json
{
  "event": "MED_ANALYSIS_REJECTED",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-16T15:00:00Z",
  "status": "EVIDENCE_REQUIRED",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": null,
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-16T15:00:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "RECEIVED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "FROZEN",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": null
  },
  "analysis": {
    "analysisResult": null,
    "analysisDetailsUser": "User analysis details",
    "analysisDetailsPsp": null
  },
  "chargebacks": []
}

5.7 MED_FUNDS_FROZEN (funds frozen) ​

Fired when the platform freezes the merchant's disputed transaction funds (before a ruling is made, or as a supplementary freeze after the MED is upheld); meant for finance-side reconciliation and delivered independently of MED_CREATED. No event-specific fields; in the full fields, funds.status is the funds status at delivery time (FROZEN when the frozen amount has reached the disputed amount, PARTIALLY_FROZEN when it has not, and PARTIALLY_REFUNDED if a refund has already occurred; see the funds.status enum in Query MED Details), and funds.frozenAt is the time of this freeze.

json
{
  "event": "MED_FUNDS_FROZEN",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-15T14:30:05Z",
  "status": "WAITING",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": null,
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-15T14:30:05Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "RECEIVED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "FROZEN",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": null
  },
  "analysis": {
    "analysisResult": null,
    "analysisDetailsUser": null,
    "analysisDetailsPsp": null
  },
  "chargebacks": []
}

5.8 MED_FUNDS_UNFROZEN (funds unfrozen) ​

Fired when the merchant's disputed transaction funds are unfrozen after the ruling takes effect or the MED is cancelled; meant for finance-side reconciliation and delivered independently of MED_APPROVED / MED_REJECTED / MED_CANCELLED. No event-specific fields; in the full fields, funds.status is the funds status at delivery time (UNFROZEN when fully unfrozen, PARTIALLY_UNFROZEN when some funds remain frozen, and PARTIALLY_REFUNDED if a refund has already occurred), and funds.unfrozenAt is the time of this unfreeze.

json
{
  "event": "MED_FUNDS_UNFROZEN",
  "medId": "medc2874510938274639021",
  "occurredAt": "2026-01-16T10:30:00Z",
  "status": "ACCEPTED_BY_PSP",
  "originSituationType": "SCAM_FRAUD",
  "details": "Detailed description of the dispute",
  "amount": 1000.50,
  "analysisResult": "ACCEPTED",
  "dueTime": "2026-01-31T23:59:59Z",
  "createdAt": "2026-01-15T14:30:00Z",
  "updatedAt": "2026-01-16T10:30:00Z",
  "transaction": {
    "e2eId": "E1234567820240115143000123",
    "transactionDate": "2026-01-15T14:30:12Z",
    "merchantOrderNo": "PIX20260816000001",
    "platOrderNo": "P5nosqyWAQsQZNtYa5OW"
  },
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "email": "user@example.com",
    "phone": "+5511999999999",
    "bankAccount": {
      "ispb": "12345678",
      "bank": "Banco Example",
      "agency": "1234",
      "account": "567890",
      "document": "12345678901",
      "name": "João Silva"
    }
  },
  "payee": {
    "name": "John Doe",
    "document": "12345678000195",
    "bankAccount": null
  },
  "infractionReport": {
    "id": "report-456",
    "status": "ANALYZED",
    "createdAt": "2026-01-15T14:30:00Z",
    "creatorPsp": "12345678"
  },
  "funds": {
    "status": "UNFROZEN",
    "amount": 1000.50,
    "frozenAt": "2026-01-15T14:30:05Z",
    "unfrozenAt": "2026-01-16T10:30:00Z"
  },
  "analysis": {
    "analysisResult": "ACCEPTED",
    "analysisDetailsUser": "User analysis details",
    "analysisDetailsPsp": "PSP confirmed fraudulent transaction"
  },
  "chargebacks": []
}

6. Merchant Response Requirements ​

The merchant should respond within 3 seconds with HTTP 200–299; timeouts or non-success responses are treated as delivery failures. The same event may be delivered multiple times due to retries, and merchants must be able to handle duplicate deliveries safely (idempotency).

Common rules (transport, timeout, failure handling, idempotency, signature verification) are described in Webhook Specification.

7. Integration Notes ​

  1. It is recommended to implement idempotency using medId + event or an equivalent unique key; for MED_REFUND_EXECUTED, it is recommended to additionally combine the refund record of this execution (e.g. chargeback.createdAt) into the idempotency key, so as to distinguish multiple refund executions and duplicate deliveries for the same MED.
  2. All time fields (occurredAt, dueTime, createdAt, updatedAt, transactionDate, funds.frozenAt / funds.unfrozenAt, refund record times, etc.) are ISO 8601 UTC time strings (yyyy-MM-ddTHH:mm:ssZ), represented as JSON strings; nullable time fields are returned as null.
  3. All event payloads use the full structure, with fields identical to the data of Query MED Details; the full information can be taken directly from the payload. The payload reflects the snapshot at the moment the event occurred; at key points (e.g. after receiving MED_APPROVED or MED_REFUND_EXECUTED), it is still recommended to call the detail endpoint to re-verify.
  4. Receiving MED_APPROVED only means the refund flow has started; the refund execution result is subject to the MED_REFUND_EXECUTED event and the chargebacks in the full fields.
  5. Funds events, refund execution events, and status events are delivered independently and may arrive out of order; do not infer the MED final status from funds events or refund execution events.

Back to MED API Overview