Skip to navigation

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

StagereviewStatusWho actsDeadline
Defenseawaiting_defenseAccount holder, through you48 h from filing (clientAnswerDeadline)
Reviewpending_reviewCorpXUp to 7 days from filing, the scheme’s deadline
Clarificationinfo_requestedAccount holder, through you24 h from the request (infoDueAt), capped by the review deadline
Executionin_executionCorpXReturn within 96 h of the decision
Awaiting fundsawaiting_fundsCorpXWhile there is an amount left to return; new returns as funds come in
Closedrefunded 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

reviewStatusMeaningWhat you can do
awaiting_defenseDispute open, waiting for the account holder’s defense.Attach evidence and answer (answer).
pending_reviewDefense received (or deadline passed); CorpX is reviewing.Follow along.
info_requestedCorpX asked for clarification; the question is in infoRequest.message.Send messages and attachments, then submit.
in_executionReturn decided; CorpX blocks the account, returns the PIX, and releases the account.Follow the webhook.
awaiting_fundsThe balance did not cover the amount; the remainder stays held and is returned as funds come in.Follow along.
refundedReturn completed. refundPartial says whether it was partial.—
refusedReturn refused; amount released in the account.—
awaiting_resultOnly with direction: opened: CorpX filed the dispute and waits for the settlement bank.Follow partnerStatus.
lockStatusMeaning
pendingHold not yet in effect.
lockedAmount held; lockedAmount says how much.
failedThe hold was not possible at the time; CorpX reassesses.
unlockedAmount released.
absentDispute 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.

EventWhen
pix.med.openedDispute filed.
pix.med.updatedEach status change the settlement bank communicates.
pix.med.review.updatedEach step of CorpX’s review: defense received, clarification requested, decision, holds, returns, closure.
{
"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

{
"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.

reasonWhat happened
submittedDefense (or clarification) received; review in progress.
info_requestedCorpX asked for clarification. infoRequest.message and infoDueAt filled in.
decidedDecision made. decision is accept or refuse; decisionMessage explains.
balance_lockedAmount held in the account.
account_blockedAccount blocked for the return.
balance_unlockedHeld amount released.
refund_sentReturn sent; refund.amount and, when available, refund.endToEndId.
refund_completedReturn settled. refundedTotal and remaining updated.
refund_failedThe return did not complete; CorpX retries.
remainder_lockedWhat was left to return stayed held.
account_unblockedAccount released.
closedDispute closed (refunded or refused).

Querying disputes

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.

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

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:

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

POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/upload-url
{
"filename": "delivery-receipt.pdf",
"contentType": "application/pdf",
"sizeBytes": 184320
}
{
"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

POST /v1/accounts/{accountId}/pix/med/{medId}/evidence/add
{
"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

LimitValue
Accepted typesapplication/pdf, image/jpeg, image/png, image/webp, text/plain, text/csv
Size per file5 MB
Total per dispute6 MB
Files per dispute10
HTTPerrorCodeWhen
413file_too_largeFile above 5 MB.
413payload_too_largeThe dispute’s set would exceed 6 MB.
422unsupported_media_typecontentType outside the list.
422too_many_filesEleventh file in the same dispute.
409med_not_writableDispute outside awaiting_defense / info_requested.

Listing what is attached

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

POST /v1/accounts/{accountId}/pix/med/{medId}/answer
{
"result": "DISAGREE",
"reason": "Legitimate sale: customer registered 14 months ago, product delivered and tracking confirmed on 02/19."
}
FieldRequiredDescription
resultyesAGREE acknowledges the fraud; DISAGREE contests the report.
reasonon DISAGREEThe defense, in free text.

Response 202:

{
"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:

HTTPerrorCodeWhen
400invalid_payloadresult outside AGREE/DISAGREE.
409conflictThe dispute has already been answered.
422invalid_payloadDISAGREE without reason.
404med_not_foundThe 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.

POST /v1/accounts/{accountId}/pix/med/{medId}/messages
{ "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).

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

HTTPerrorCodeWhen
404med_not_foundDispute does not exist or belongs to another account.
409med_not_writableMessage or attachment outside awaiting_defense / info_requested.
409med_opened_by_usMED filed by CorpX on the holder’s behalf (direction: opened): nothing to answer.
422med_info_missingsubmit with no message and no new attachment.
403account_blockedFinancial operation on the account while the return executes.

MED rate

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

Returns the deadline counters and the daily rate series:

FieldDescription
totalTotal disputes recorded.
awaitingAnswerDisputes still without your answer.
dueSoonUnanswered with less than 12 hours left.
overdueUnanswered with the deadline passed.
openAmountSummed amount of disputes not yet closed.
nextDeadlineThe 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.

RateSituation
< 0.4%Healthy
0.4% – 1.0%Attention, monitor
> 1.0%Elevated, action may be needed

MED policies

See Policies and Rules 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.