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.
reviewStatustells 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 thepix.med.updatedwebhook, 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;
lockStatusandlockedAmountshow it. If no return happens, the amount is released; if it does, it comes out of that held balance.
The stages of a MED
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 (clientAnswerDeadlinenull), no balance is held, and the review stays inawaiting_resultuntil the settlement bank decides.answer,messages,submitand attachments return409 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
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.
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
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.
Querying disputes
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.
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
Everything from the list plus the timeline, the messages exchanged, the
attachments with downloadUrl, and what is enabled right now:
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
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
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
Listing what is attached
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
Response 202:
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:
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.
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).
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
MED rate
Returns the deadline counters and the daily rate series:
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.
MED policies
See Policies and Rules for:
- Auto-block: automatically hold funds on disputes above an amount.
- Maximum rate (
medsection): 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, orscam-or-fraudreason from the settlement partner.