Webhooks
MedCreated
Visão Geral
O evento MedCreated é enviado quando um novo MED (Mecanismo Especial de Devolução) é registrado contra uma transação PIX recebida pela sua conta. Isso significa que o banco do pagador está solicitando a devolução do valor.
O evento só é enviado quando o MED é associado a uma transação da sua conta, então originalTransaction vem preenchido.
Este evento requer atenção imediata. O MED tem prazos regulatórios definidos pelo Banco Central para análise e resposta.
| Campo | Valor |
|---|---|
event | MedCreated |
| Significado | Novo MED aberto — solicitação de devolução recebida |
| Ação recomendada | Alertar equipe de risco, avaliar a transação original |
Payload Completo
{
"event": "MedCreated",
"medId": 42,
"idSolicitacaoDevolucao": "MED-2026041012345",
"endToEndId": "E12345678202604101030abcdef123456",
"status": "RECEIVED",
"reason": "REFUND_REQUEST",
"cause": "UNAUTHORIZED_TRANSACTION",
"description": "Cliente alega não ter realizado a transação",
"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"
}Os eventos MED não têm transactionId no nível raiz. Para idempotência, use a combinação medId + event. Assim como nos eventos de transação, os webhooks MED são assinados com X-Avista-Signature (quando a chave foi gerada) e seguem as mesmas regras de timeout e retentativas.
Campos
| Campo | Tipo | Descrição |
|---|---|---|
event | string | Tipo do evento: "MedCreated" |
medId | number | Identificador único do MED no sistema |
idSolicitacaoDevolucao | string | Identificador único da solicitação de devolução |
endToEndId | string | End-to-end ID da transação PIX original |
status | string | Status do MED, normalizado: OPEN, RECEIVED, CANCELLED ou ANALYZED. Na abertura, normalmente OPEN ou RECEIVED |
reason | string | Motivo: "REFUND_REQUEST" ou "REFUND_CANCELLATION" |
cause | string | null | Código da causa quando disponível (UNAUTHORIZED_TRANSACTION, FRAUDULENT_ACCESS, SOCIAL_ENGINEERING, OPERATIONAL_FAILURE) ou null. Se null, consulte description. Trate valores desconhecidos como texto genérico |
description | string | null | Texto descritivo da solicitação (relato do pagador, notificação formal do banco, etc.) |
analysisResult | string | null | Resultado da análise: APPROVED, REJECTED ou null (null neste estágio) |
analysisDetails | string | null | Detalhes da análise (null neste estágio) |
originalTransaction | object | null | Dados da transação PIX original |
originalTransaction.transactionId | number | ID interno da transação na plataforma |
originalTransaction.amount | number | Valor original em reais |
originalTransaction.endToEndId | string | E2E ID da transação original |
originalTransaction.externalId | string | null | ID externo que você forneceu na criação da transação |
blockStatus | string | null | Status de bloqueio de saldo: null, "BLOCKED", "UNBLOCKED", "APPROVED". Na abertura, normalmente null |
blockedAmount | number | null | Valor bloqueado em reais, ou null se não houve bloqueio |
defenseStatus | string | null | Status da defesa: null, "PENDING", "SUBMITTED" |
requestingBank | object | Banco que abriu o MED (banco do pagador) |
requestingBank.ispb | string | null | Código ISPB do banco solicitante |
requestingBank.name | string | null | Nome do banco solicitante |
contestedBank | object | Banco contestado (sua instituição) |
contestedBank.ispb | string | null | Código ISPB do banco contestado |
contestedBank.name | string | null | Nome do banco contestado |
statusHistory | array | Histórico de transições de status do MED |
statusHistory[].status | string | Status naquele momento (mesmos valores de status) |
statusHistory[].date | string | Data da transição (ISO 8601) |
createdAt | string | Data de criação do MED (ISO 8601) |
updatedAt | string | Data da última atualização (ISO 8601) |