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.

The event is only sent when the MED is linked to a transaction on your account, so originalTransaction is filled in.

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"
}

MED events have no root-level transactionId. For idempotency, use the combination medId + event. As with transaction events, MED webhooks are signed with X-Avista-Signature (once the key has been generated) and follow the same timeout and retry rules.

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	MED status, normalized: `OPEN`, `RECEIVED`, `CANCELLED` or `ANALYZED`. At opening, usually `OPEN` or `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`. Treat unknown values as generic text
`description`	string \| null	Descriptive text (payer's report, formal bank notification, etc.)
`analysisResult`	string \| null	Analysis result: `APPROVED`, `REJECTED` or `null` (`null` at this stage)
`analysisDetails`	string \| null	Analysis details (null at this stage)
`originalTransaction`	object \| null	Data about the original PIX transaction
`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"`. At opening, usually `null`
`blockedAmount`	number \| null	Blocked amount in BRL, or `null` if there was no block
`defenseStatus`	string \| null	Defense status: `null`, `"PENDING"`, `"SUBMITTED"`
`requestingBank`	object	Bank that opened the MED (payer's bank)
`requestingBank.ispb`	string \| null	Requesting bank ISPB code
`requestingBank.name`	string \| null	Requesting bank name
`contestedBank`	object	Contested bank (your institution)
`contestedBank.ispb`	string \| null	Contested bank ISPB code
`contestedBank.name`	string \| null	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)

MedCreated

Overview

Full Payload

Fields

Next Steps

MedAccepted

MedRejected

MED Integration

On this page