Skip to main content

​
What is a MED?

MED (Mecanismo Especial de Devolução / Special Return Mechanism) is a Central Bank resource that allows value returns in cases of:
  • Fraud - Transaction not recognized by the payer
  • Operational failure - Processing error
  • Dispute - Payer claims non-receipt of product/service
When a MED is opened against you, you have limited time to present your defense.
MEDs have strict deadlines. Configure webhooks for med:received and respond quickly.

​
MED Flow

​
Receive MED Notification

Configure a webhook for med:received: 
{
  "webhookId": "wh_abc123",
  "event": "med:received",
  "object": {
    "endToEndId": "E123456789...",
    "medId": "med_12345678...",
    "details": "Transaction disputed by payer",
    "dtHrCreationReason": "2025-12-24T12:00:00.000Z",
    "entryId": "abc123def..."
  }
}

​
Query MEDs

List all received MEDs: 
curl -X GET "https://api.owem.com.br/v4/i/meds?status=under_analysis" \
  -u "API_KEY:API_SECRET"

​
Important Fields

FieldDescription
medIdUnique MED identifier
endToEndIdE2E of original transaction
statusunder_analysis, accepted, rejected
detailsDispute reason
deadlines.defenseDeadLineDefense deadline (timestamp)
grossAmountDisputed amount

​
Submit Defense

Defense must be submitted before the deadline indicated in defenseDeadLine. After the deadline, you cannot contest.
curl -X POST "https://api.owem.com.br/v4/i/meds/{medId}/defense" \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Customer made the purchase and received the product as per attached proof.",
    "files": [
      "https://storage.mysite.com/invoice-12345.pdf",
      "https://storage.mysite.com/delivery-proof.pdf",
      "https://storage.mysite.com/customer-chat.pdf"
    ]
  }'

​
What to Include in Defense?

Proves the sale and customer data.
Tracking, delivery photo, recipient signature.
WhatsApp prints, email, chat proving negotiation.
If applicable, policies accepted by customer.
Records proving digital service delivery.

​
MED Status

StatusDescriptionAction
under_analysisMED under analysisSubmit defense if not yet sent
acceptedMED accepted, value returnedValue already debited
rejectedMED rejected, value keptNo action required

​
Example: MED Monitoring

// Check pending MEDs daily
async function checkPendingMeds() {
  const response = await fetch(
    "https://api.owem.com.br/v4/i/meds?status=under_analysis",
    {
      headers: {
        Authorization: `Basic ${btoa("API_KEY:API_SECRET")}`,
      },
    }
  )

  const { data } = await response.json()

  for (const med of data) {
    const deadline = new Date(med.deadlines.defenseDeadLine)
    const now = new Date()
    const hoursLeft = (deadline - now) / (1000 * 60 * 60)

    if (hoursLeft < 24 && !med.defense) {
      // ALERT: MED without defense with less than 24h to deadline
      await sendAlert({
        medId: med.medId,
        endToEndId: med.endToEndId,
        hoursLeft: hoursLeft.toFixed(1),
        amount: med.grossAmount,
      })
    }
  }
}

​
Best Practices

Being notified immediately is crucial to not miss the deadline.
The sooner you submit defense, the better. Don’t wait until the last day.
Keep records of all transactions (invoices, deliveries, conversations).
Check pending MEDs every day to not miss deadlines.
If you receive many MEDs, investigate the cause (fraud, dissatisfaction, etc).

​
Next Steps

API Reference

Complete endpoint documentation

Webhooks

Configure notifications