Webhooks
MedCreated
Visión General
El evento MedCreated se envía cuando se registra un nuevo MED (Mecanismo Especial de Devolución) contra una transacción PIX recibida por su cuenta. Esto significa que el banco del pagador está solicitando la devolución del monto.
El evento solo se envía cuando el MED está asociado a una transacción de su cuenta, por lo que originalTransaction viene completado.
Este evento requiere atención inmediata. El MED tiene plazos regulatorios definidos por el Banco Central de Brasil para el análisis y la respuesta.
| Campo | Valor |
|---|---|
event | MedCreated |
| Significado | Nuevo MED abierto — solicitud de devolución recibida |
| Acción recomendada | Alertar al equipo de riesgo, evaluar la transacción original |
Payload Completo
{
"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"
}Los eventos MED no tienen transactionId en el nivel raíz. Para la idempotencia, use la combinación medId + event. Al igual que los eventos de transacción, los webhooks MED se firman con X-Avista-Signature (cuando se generó la clave) y siguen las mismas reglas de timeout y reintentos.
Campos
| Campo | Tipo | Descripción |
|---|---|---|
event | string | Tipo de evento: "MedCreated" |
medId | number | Identificador único del MED en el sistema |
idSolicitacaoDevolucao | string | Identificador único de la solicitud de devolución |
endToEndId | string | End-to-end ID de la transacción PIX original |
status | string | Estado del MED, normalizado: OPEN, RECEIVED, CANCELLED o ANALYZED. En la apertura, normalmente OPEN o RECEIVED |
reason | string | Motivo: "REFUND_REQUEST" o "REFUND_CANCELLATION" |
cause | string | null | Código de causa cuando está disponible (UNAUTHORIZED_TRANSACTION, FRAUDULENT_ACCESS, SOCIAL_ENGINEERING, OPERATIONAL_FAILURE) o null. Si es null, consulte description. Trate los valores desconocidos como texto genérico |
description | string | null | Texto descriptivo (relato del pagador, notificación formal del banco, etc.) |
analysisResult | string | null | Resultado del análisis: APPROVED, REJECTED o null (null en esta etapa) |
analysisDetails | string | null | Detalles del análisis (null en esta etapa) |
originalTransaction | object | null | Datos de la transacción PIX original |
originalTransaction.transactionId | number | ID interno de la transacción en la plataforma |
originalTransaction.amount | number | Monto original en BRL |
originalTransaction.endToEndId | string | E2E ID de la transacción original |
originalTransaction.externalId | string | null | ID externo proporcionado por usted al crear la transacción |
blockStatus | string | null | Estado del bloqueo de saldo: null, "BLOCKED", "UNBLOCKED", "APPROVED". En la apertura, normalmente null |
blockedAmount | number | null | Monto bloqueado en BRL, o null si no hubo bloqueo |
defenseStatus | string | null | Estado de la defensa: null, "PENDING", "SUBMITTED" |
requestingBank | object | Banco que abrió el MED (banco del pagador) |
requestingBank.ispb | string | null | Código ISPB del banco solicitante |
requestingBank.name | string | null | Nombre del banco solicitante |
contestedBank | object | Banco contestado (su institución) |
contestedBank.ispb | string | null | Código ISPB del banco contestado |
contestedBank.name | string | null | Nombre del banco contestado |
statusHistory | array | Historial de transiciones de estado del MED |
statusHistory[].status | string | Estado en ese momento (mismos valores que status) |
statusHistory[].date | string | Fecha de la transición (ISO 8601) |
createdAt | string | Fecha de creación del MED (ISO 8601) |
updatedAt | string | Fecha de la última actualización (ISO 8601) |