> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# Disputes — Special Return Mechanism (MED)

MED is the process through which the payer of a PIX transfer requests the money
back, usually on suspicion of fraud. When a dispute is filed against one of your
accounts, you receive a webhook, have **48 hours** to present the account
holder's defense, and CorpX conducts the review and answers the scheme within
the regulatory deadline.

Three facts shape how this module works, and they are worth knowing before you
integrate:

* **CorpX's review decides, within the rules of the scheme.** There is no
  route to return the PIX, release funds, or refuse the return. What you do
  here is register the account holder's side, with text and attachments, and
  answer requests for clarification.
* **The API shows the status of the review, not the settlement bank's.**
  `reviewStatus` tells you which stage the dispute is at on CorpX's side and
  what you can do in it. The status the settlement bank communicates keeps
  arriving through the `pix.med.updated` webhook, as always.
* **The amount stays held while the dispute runs.** When the dispute arrives,
  CorpX holds the amount in the account up to the available balance;
  `lockStatus` and `lockedAmount` show it. If no return happens, the amount is
  released; if it does, it comes out of that held balance.

## The stages of a MED

```mermaid
flowchart TD
    A["Dispute filed by the payer's bank<br />Webhook <code>pix.med.opened</code><br />Amount held in the account"] --> B["<code>awaiting_defense</code><br />Account holder defends: text + attachments<br /><b>48 h</b> from filing"]
    B -- "POST .../answer" --> C["<code>pending_review</code><br />CorpX reviews<br /><b>up to 7 days from filing</b>"]
    B -- "Deadline passes with no answer" --> C
    C -- "Needs more information" --> D["<code>info_requested</code><br />Account holder replies: message + attachments<br /><b>24 h</b>, never past the review deadline"]
    D -- "POST .../submit" --> C
    C -- "Defense upheld" --> E["<code>refused</code><br />Return refused<br />Amount released in the account"]
    C -- "Return due" --> F["<code>in_execution</code><br />Account blocked, PIX returned<br /><b>up to 96 h after the decision</b>"]
    F -- "Balance covered everything" --> G["<code>refunded</code><br />Account released"]
    F -- "Balance did not cover it" --> H["<code>awaiting_funds</code><br />Remainder held; returned as funds come in"]
    H --> F
    H -- "Closed with partial return" --> G
```

| Stage          | `reviewStatus`          | Who acts                    | Deadline                                                               |
| -------------- | ----------------------- | --------------------------- | ---------------------------------------------------------------------- |
| Defense        | `awaiting_defense`      | Account holder, through you | **48 h** from filing (`clientAnswerDeadline`)                          |
| Review         | `pending_review`        | CorpX                       | Up to **7 days** from filing, the scheme's deadline                    |
| Clarification  | `info_requested`        | Account holder, through you | **24 h** from the request (`infoDueAt`), capped by the review deadline |
| Execution      | `in_execution`          | CorpX                       | Return within **96 h** of the decision                                 |
| Awaiting funds | `awaiting_funds`        | CorpX                       | While there is an amount left to return; new returns as funds come in  |
| Closed         | `refunded` or `refused` | —                           | —                                                                      |

**Nothing is rejected automatically by time.** Missing the defense deadline
neither closes the dispute nor triggers a return on its own: the review goes
on, without the account holder's side. Monitor `clientAnswerDeadline` and
`infoDueAt` — or the panel, which warns when less than 12 hours remain.

## MEDs opened by CorpX (`direction`)

The list carries two kinds of dispute, told apart by `direction`:

* `received` — filed against the account by the payer's bank. It follows the flow above.
* `opened` — filed by CorpX on the holder's behalf, because the disputed PIX
  left this account. There is no defense and no deadline
  (`clientAnswerDeadline` null), no balance is held, and the review stays in
  `awaiting_result` until the settlement bank decides. `answer`, `messages`,
  `submit` and attachments return `409 med_opened_by_us`.

In a PIX between two CorpX accounts, the dispute on the account that received
the money is `received`, with defense and a balance hold like any other.

`partnerStatus` (`OPEN`, `PENDING_DECISION`, `ACCEPTED`, `REJECTED`,
`CANCELED`) is the settlement bank's status from the last webhook, and
`lastUpdatedAt` says when it arrived. For an `opened` MED it is what shows
progress.

## Review status

| `reviewStatus`     | Meaning                                                                                          | What you can do                               |
| ------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| `awaiting_defense` | Dispute open, waiting for the account holder's defense.                                          | Attach evidence and answer (`answer`).        |
| `pending_review`   | Defense received (or deadline passed); CorpX is reviewing.                                       | Follow along.                                 |
| `info_requested`   | CorpX asked for clarification; the question is in `infoRequest.message`.                         | Send messages and attachments, then `submit`. |
| `in_execution`     | Return decided; CorpX blocks the account, returns the PIX, and releases the account.             | Follow the webhook.                           |
| `awaiting_funds`   | The balance did not cover the amount; the remainder stays held and is returned as funds come in. | Follow along.                                 |
| `refunded`         | Return completed. `refundPartial` says whether it was partial.                                   | —                                             |
| `refused`          | Return refused; amount released in the account.                                                  | —                                             |
| `awaiting_result`  | Only with `direction: opened`: CorpX filed the dispute and waits for the settlement bank.        | Follow `partnerStatus`.                       |

| `lockStatus` | Meaning                                                  |
| ------------ | -------------------------------------------------------- |
| `pending`    | Hold not yet in effect.                                  |
| `locked`     | Amount held; `lockedAmount` says how much.               |
| `failed`     | The hold was not possible at the time; CorpX reassesses. |
| `unlocked`   | Amount released.                                         |
| absent       | Dispute predates the automatic hold.                     |

While the account is blocked by the execution (`in_execution`), its financial
operations answer `403 account_blocked`. The return of the disputed PIX is
made by CorpX and does not go through that block.

## Receiving disputes via webhook

Three events. Subscribe to all three.

| Event                    | When                                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `pix.med.opened`         | Dispute filed.                                                                                             |
| `pix.med.updated`        | Each status change the settlement bank communicates.                                                       |
| `pix.med.review.updated` | Each step of CorpX's review: defense received, clarification requested, decision, holds, returns, closure. |

```json
{
  "id": "pix-med-opened-204cc938-da3d-4f04-baf3-0b2e6a2f1283-OPEN",
  "type": "pix.med.opened",
  "occurredAt": "2026-02-18T19:34:14.000000000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "tenantId": "tenant-yourcompany",
    "accountId": "773107de-...",
    "originalEndToEnd": "E303062942026021812490000005QLMv",
    "amount": 1000.00,
    "reasonCode": "unauthorized-transaction",
    "claimMessage": "I do not recognize this transaction",
    "openedAtIso": "2026-02-18T19:34:14.000000000Z",
    "clientAnswerDeadlineIso": "2026-02-20T19:34:14.000000000Z",
    "status": "OPEN"
  }
}
```

The `status` in `pix.med.opened` and `pix.med.updated` is the state at the
settlement bank **at the moment of that event**. Redelivery of the same state
does not produce a new event, and a late event is discarded — you never see the
dispute go back in time.

`reasonCode` is the scheme's code, passed through as it comes
(`unauthorized-transaction`, `fraud`, `scam-or-fraud`, …). We do not normalize
it into an enum of our own.

The report carries the claimant's **bank**, not their name or document. That
information is not made available to the payee.

### `pix.med.review.updated`

```json
{
  "id": "pix-med-review-204cc938-...-info_requested-1771598551000",
  "type": "pix.med.review.updated",
  "occurredAt": "2026-02-20T14:02:31Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-yourcompany",
  "accountId": "773107de-...",
  "data": {
    "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
    "accountId": "773107de-...",
    "reason": "info_requested",
    "reviewStatus": "info_requested",
    "round": null,
    "decision": null,
    "decisionMessage": null,
    "infoRequest": { "message": "Send the delivery receipt with the tracking number." },
    "infoDueAt": "2026-02-21T14:02:31Z",
    "lockStatus": "locked",
    "lockedAmount": 1000.00,
    "refund": null,
    "refundedTotal": 0,
    "remaining": 1000.00,
    "refundPartial": false
  }
}
```

`data` is always the current snapshot of the dispute; `reason` says what just
happened. You do not need to accumulate events to know where it stands.

| `reason`            | What happened                                                                   |
| ------------------- | ------------------------------------------------------------------------------- |
| `submitted`         | Defense (or clarification) received; review in progress.                        |
| `info_requested`    | CorpX asked for clarification. `infoRequest.message` and `infoDueAt` filled in. |
| `decided`           | Decision made. `decision` is `accept` or `refuse`; `decisionMessage` explains.  |
| `balance_locked`    | Amount held in the account.                                                     |
| `account_blocked`   | Account blocked for the return.                                                 |
| `balance_unlocked`  | Held amount released.                                                           |
| `refund_sent`       | Return sent; `refund.amount` and, when available, `refund.endToEndId`.          |
| `refund_completed`  | Return settled. `refundedTotal` and `remaining` updated.                        |
| `refund_failed`     | The return did not complete; CorpX retries.                                     |
| `remainder_locked`  | What was left to return stayed held.                                            |
| `account_unblocked` | Account released.                                                               |
| `closed`            | Dispute closed (`refunded` or `refused`).                                       |

## Querying disputes

```http
GET /v1/accounts/{accountId}/pix/med?limit=50&offset=0
```

Paginated by `limit` (maximum 200) and `offset`. There is no status filter.

The list only has the disputes **this account** is in: a MED is linked to
the account the settlement bank identifies in the webhook, not to the
holder's CPF/CNPJ. A holder with more than one account sees each dispute
only on the account of the disputed PIX; querying the MED through another
account of the same holder answers `404 med_not_found`.

```json
{
  "accountId": "773107de-...",
  "tenantId": "tenant-yourcompany",
  "items": [
    {
      "medId": "204cc938-da3d-4f04-baf3-0b2e6a2f1283",
      "accountId": "773107de-...",
      "tenantId": "tenant-yourcompany",
      "endToEndId": "E303062942026021812490000005QLMv",
      "transactionId": "tx-8f2c...",
      "amount": 1000.00,
      "reasonCode": "unauthorized-transaction",
      "claimMessage": "I do not recognize this transaction",
      "claimantBank": "Claimant's bank",
      "openedAt": "2026-02-18T19:34:14Z",
      "clientAnswerDeadline": "2026-02-20T19:34:14Z",
      "answered": false,
      "reviewStatus": "awaiting_defense",
      "infoDueAt": null,
      "lockStatus": "locked",
      "lockedAmount": 1000.00,
      "refundedTotal": 0,
      "remaining": 1000.00,
      "refundPartial": false,
      "updatedAt": "2026-02-18T19:34:16Z"
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}
```

`transactionId` links the dispute to the PIX entry in your statement, when it
exists on the platform. After you answer, `answered` becomes `true` and
`answeredAt`, `answerResult`, and `answer` (the justification you sent) appear.

### Dispute detail

```http
GET /v1/accounts/{accountId}/pix/med/{medId}
```

Everything from the list plus the timeline, the messages exchanged, the
attachments with `downloadUrl`, and what is enabled right now:

```json
{
  "medId": "204cc938-...",
  "reviewStatus": "info_requested",
  "infoRequest": {
    "message": "Send the delivery receipt with the tracking number.",
    "requestedAt": "2026-02-20T14:02:31Z",
    "dueAt": "2026-02-21T14:02:31Z"
  },
  "canUpload": true,
  "canAnswer": false,
  "canMessage": true,
  "canSubmit": true,
  "events": [
    { "at": "2026-02-18T19:34:14Z", "kind": "opened", "reviewStatus": "awaiting_defense", "message": "Disputa aberta", "round": null, "step": null },
    { "at": "2026-02-19T14:02:31Z", "kind": "submitted", "reviewStatus": "pending_review", "message": "Defesa enviada", "round": null, "step": null },
    { "at": "2026-02-20T14:02:31Z", "kind": "info_requested", "reviewStatus": "info_requested", "message": "Esclarecimento solicitado", "round": null, "step": null }
  ],
  "messages": [
    { "messageId": "medmsg_01...", "authorKind": "staff", "body": "Send the delivery receipt with the tracking number.", "createdAt": "2026-02-20T14:02:31Z", "evidenceIds": [] }
  ],
  "evidences": [
    { "evidenceId": "medev_9f1c...", "filename": "delivery-receipt.pdf", "contentType": "application/pdf", "sizeBytes": 184320, "uploadedAt": "2026-02-19T13:58:00Z", "messageId": null, "scanStatus": "APPROVED", "downloadUrl": "https://..." }
  ],
  "steps": []
}
```

`events` is the timeline visible to the account holder; `message` texts are in
Portuguese. `steps` lists, in text, what CorpX has already executed in the
return (account blocked, amount returned, account released) — it appears from
`in_execution` on. The four `can*` flags say what is enabled at this instant;
use them instead of inferring from the status.

## Attaching evidence

Attachments are accepted while the dispute is in `awaiting_defense` (before
`answer`) or in `info_requested`. Outside that the route answers `409
med_not_writable`: the package has already moved on.

There are three steps. The file goes straight from your side to storage,
without passing through the body of our API.

**1. Request the upload URL**

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/upload-url
```

```json
{
  "filename": "delivery-receipt.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 184320
}
```

```json
{
  "medId": "204cc938-...",
  "evidenceId": "medev_9f1c...",
  "key": "med-evidences/tenant-yourcompany/204cc938-.../medev_9f1c...-delivery-receipt.pdf",
  "uploadUrl": "https://...",
  "method": "PUT",
  "contentType": "application/pdf",
  "sizeBytes": 184320,
  "expiresIn": 900
}
```

`sizeBytes` is the **actual** file size, not an estimate: it goes into the URL
signature. Declaring one number and sending another makes storage refuse the
`PUT`.

**2. Send the file to the signed URL**

`PUT` directly to the `uploadUrl`, with the same `Content-Type` and exactly the
`sizeBytes` you declared. No authentication header of ours — the signature
already authorizes, and one extra header makes storage refuse.

**3. Register the attachment**

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/add
```

```json
{
  "key": "med-evidences/tenant-yourcompany/204cc938-.../medev_9f1c...-delivery-receipt.pdf",
  "evidenceId": "medev_9f1c...",
  "filename": "delivery-receipt.pdf",
  "contentType": "application/pdf",
  "sizeBytes": 184320,
  "messageId": "medmsg_02..."
}
```

Without this step the file sits in storage and is not part of the defense: this
is the record that ties the binary to the dispute. Type and size are checked
again here, with the same limits and the same `errorCode` values from the table
below — the two calls are independent. `messageId` is optional: in
`info_requested`, it ties the attachment to the message that explains it.

Every upload goes through real-type verification, antivirus, and sanitization
before becoming available — a few seconds. `scanStatus` tracks it: `PENDING`
processing, `APPROVED` released, `REJECTED` refused (with `scanReason`). A
refused file does not go with the defense.

### Limits

| Limit             | Value                                                                                |
| ----------------- | ------------------------------------------------------------------------------------ |
| Accepted types    | `application/pdf`, `image/jpeg`, `image/png`, `image/webp`, `text/plain`, `text/csv` |
| Size per file     | 5 MB                                                                                 |
| Total per dispute | 6 MB                                                                                 |
| Files per dispute | 10                                                                                   |

| HTTP | `errorCode`              | When                                                   |
| ---- | ------------------------ | ------------------------------------------------------ |
| 413  | `file_too_large`         | File above 5 MB.                                       |
| 413  | `payload_too_large`      | The dispute's set would exceed 6 MB.                   |
| 422  | `unsupported_media_type` | `contentType` outside the list.                        |
| 422  | `too_many_files`         | Eleventh file in the same dispute.                     |
| 409  | `med_not_writable`       | Dispute outside `awaiting_defense` / `info_requested`. |

### Listing what is attached

```http
GET /v1/accounts/{accountId}/pix/med/{medId}/evidence/download
```

Returns the dispute's attachments with a signed `downloadUrl` (short-lived) for
each one that passed verification. With `?evidenceId=` returns only one. The
same content comes in `evidences` on the detail.

## Answering a dispute

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/answer
```

```json
{
  "result": "DISAGREE",
  "reason": "Legitimate sale: customer registered 14 months ago, product delivered and tracking confirmed on 02/19."
}
```

| Field    | Required      | Description                                                     |
| -------- | ------------- | --------------------------------------------------------------- |
| `result` | yes           | `AGREE` acknowledges the fraud; `DISAGREE` contests the report. |
| `reason` | on `DISAGREE` | The defense, in free text.                                      |

Response `202`:

```json
{
  "medId": "204cc938-...",
  "result": "DISAGREE",
  "answered": true,
  "answeredAt": "2026-02-19T14:02:31Z",
  "reviewStatus": "pending_review",
  "message": "defesa registrada; a disputa segue para análise"
}
```

The defense and the attachments enter the review and `reviewStatus` becomes
`pending_review`. Answering registers the account holder's side; it does not
close the case: the decision comes later, through the webhook.

Errors specific to this route:

| HTTP | `errorCode`       | When                                                           |
| ---- | ----------------- | -------------------------------------------------------------- |
| 400  | `invalid_payload` | `result` outside `AGREE`/`DISAGREE`.                           |
| 409  | `conflict`        | The dispute has already been answered.                         |
| 422  | `invalid_payload` | `DISAGREE` without `reason`.                                   |
| 404  | `med_not_found`   | The dispute does not exist or does not belong to this account. |

## Answering a request for clarification

In `info_requested`, the review's question is in `infoRequest.message` on the
detail and in the webhook. The account holder replies with messages and
attachments and you close the package with `submit`.

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/messages
```

```json
{ "body": "Attached is the delivery receipt with tracking BR123456789BR." }
```

Response `201` with `messageId`. Attachments tied to the message go through
`evidence/add` with that `messageId`. Up to 2,000 characters per message; the
route only accepts in `info_requested` (`409 med_not_writable` otherwise).

```http
POST /v1/accounts/{accountId}/pix/med/{medId}/submit
```

No body. Returns `202` with the detail and `reviewStatus: pending_review`. If
there was no message and no new attachment since the request, it answers `422
med_info_missing` — sending nothing does not help the review.

## Module errors

| HTTP | `errorCode`        | When                                                                                |
| ---- | ------------------ | ----------------------------------------------------------------------------------- |
| 404  | `med_not_found`    | Dispute does not exist or belongs to another account.                               |
| 409  | `med_not_writable` | Message or attachment outside `awaiting_defense` / `info_requested`.                |
| 409  | `med_opened_by_us` | MED filed by CorpX on the holder's behalf (`direction: opened`): nothing to answer. |
| 422  | `med_info_missing` | `submit` with no message and no new attachment.                                     |
| 403  | `account_blocked`  | Financial operation on the account while the return executes.                       |

## MED rate

```http
GET /v1/backoffice/tenants/{tenantId}/med-stats?days=30&accountId={accountId}
```

Returns the deadline counters and the daily rate series:

| Field            | Description                                                                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `total`          | Total disputes recorded.                                                                                                |
| `awaitingAnswer` | Disputes still without your answer.                                                                                     |
| `dueSoon`        | Unanswered with less than 12 hours left.                                                                                |
| `overdue`        | Unanswered with the deadline passed.                                                                                    |
| `openAmount`     | Summed amount of disputes not yet closed.                                                                               |
| `nextDeadline`   | The tightest deadline among pending ones (empty if none pending).                                                       |
| `stats[]`        | Daily series: `date`, `pixInCount`, `pixInAmount`, `medCount`, `medAmount`, `quantityRatePercent`, `amountRatePercent`. |

The equivalent per-tenant list is
`GET /v1/backoffice/tenants/{tenantId}/meds`, with the filters `accountId`,
`limit`, and `offset`.

### Reference bands

Operational reference, used in the panel and in commercial follow-up. No error
or block follows automatically from them — automatic actions by rate are
configured in [Policies and Rules](/baas/guias/autenticacao/politicas).

| Rate        | Situation                      |
| ----------- | ------------------------------ |
| \< 0.4%     | Healthy                        |
| 0.4% – 1.0% | Attention, monitor             |
| > 1.0%      | Elevated, action may be needed |

## MED policies

See [Policies and Rules](/baas/guias/autenticacao/politicas) for:

* **Auto-block**: automatically hold funds on disputes above an amount.
* **Maximum rate** (`med` section): per-account MED/PIX-received ratio ceiling over a rolling window that blocks the account's outbound side. A second, lower ceiling applies only to **critical** MEDs — claimant message with scam or betting terms, or `scam-or-fraud` reason from the settlement partner.