MedCreated

Overview

The MedCreated event is sent when a new MED (Special Refund Mechanism) is registered against a PIX transaction received by your account. This means the payer's bank is requesting the amount to be refunded.

This event requires immediate attention. The MED has regulatory deadlines defined by the Central Bank of Brazil for analysis and response.

Field	Value
`event`	`MedCreated`
Meaning	New MED opened — refund request received
Recommended action	Alert the risk team, evaluate the original transaction

Full Payload

{
  "event": "MedCreated",
  "medId": 42,
  "idSolicitacaoDevolucao": "MED-2026041012345",
  "endToEndId": "E12345678202604101030abcdef123456",
  "status": "RECEIVED",
  "reason": "REFUND_REQUEST",
  "cause": "UNAUTHORIZED_TRANSACTION",
  "description": "Customer claims not to have performed the transaction",
  "analysisResult": null,
  "analysisDetails": null,
  "originalTransaction": {
    "transactionId": 78432,
    "amount": 1500.00,
    "endToEndId": "E12345678202604101030abcdef123456",
    "externalId": "ORDER-78432"
  },
  "blockStatus": null,
  "blockedAmount": null,
  "defenseStatus": null,
  "requestingBank": {
    "ispb": "00000000",
    "name": "BCO DO BRASIL S.A."
  },
  "contestedBank": {
    "ispb": "13140088",
    "name": "ACESSO SOLUÇÕES DE PAGAMENTO"
  },
  "statusHistory": [
    { "status": "OPEN", "date": "2026-04-10T09:55:12.000Z" },
    { "status": "RECEIVED", "date": "2026-04-10T10:00:00.000Z" }
  ],
  "createdAt": "2026-04-10T10:00:00.000Z",
  "updatedAt": "2026-04-10T10:00:00.000Z"
}

Fields

Field	Type	Description
`event`	string	Event type: `"MedCreated"`
`medId`	number	Unique MED identifier in the system
`idSolicitacaoDevolucao`	string	Unique refund request identifier
`endToEndId`	string	End-to-end ID of the original PIX transaction
`status`	string	Current status: `"RECEIVED"`
`reason`	string	Reason: `"REFUND_REQUEST"` or `"REFUND_CANCELLATION"`
`cause`	string \| null	Cause code when available (`UNAUTHORIZED_TRANSACTION`, `FRAUDULENT_ACCESS`, `SOCIAL_ENGINEERING`, `OPERATIONAL_FAILURE`) or `null`. If `null`, see `description`.
`description`	string \| null	Descriptive text (payer's report, formal bank notification, etc.)
`analysisResult`	string \| null	Analysis result (null at this stage)
`analysisDetails`	string \| null	Analysis details (null at this stage)
`originalTransaction`	object \| null	Data about the original PIX transaction (if reconciled)
`originalTransaction.transactionId`	number	Internal platform transaction ID
`originalTransaction.amount`	number	Original amount in BRL
`originalTransaction.endToEndId`	string	E2E ID of the original transaction
`originalTransaction.externalId`	string \| null	External ID you provided when creating the transaction
`blockStatus`	string \| null	Balance block status: `null`, `"BLOCKED"`, `"UNBLOCKED"`, `"APPROVED"`
`blockedAmount`	number \| null	Blocked amount in BRL
`defenseStatus`	string \| null	Defense status: `null`, `"PENDING"`, `"SUBMITTED"`
`requestingBank`	object	Bank that opened the MED (payer's bank)
`requestingBank.ispb`	string	Requesting bank ISPB code
`requestingBank.name`	string	Requesting bank name
`contestedBank`	object	Contested bank (your institution)
`contestedBank.ispb`	string	Contested bank ISPB code
`contestedBank.name`	string	Contested bank name
`statusHistory`	array	History of MED status transitions
`statusHistory[].status`	string	Status at that moment (same values as `status`)
`statusHistory[].date`	string	Transition date (ISO 8601)
`createdAt`	string	MED creation date (ISO 8601)
`updatedAt`	string	Last update date (ISO 8601)

Next Steps

MedAccepted

Event when the refund is approved

MedRejected

Event when the refund is rejected

MED Integration

Practical guide with code examples