Disputes

Track disputes for payments received by your company, including cases under the Pix Special Refund Mechanism (Mecanismo Especial de Devolução, MED). The API lets you view records and their available results.

When to look up a dispute

Use the list to identify cases and track their stages. View the details when you need the reason, report, company response or available dates. The data reflects the tracking shown by Raims; querying the API does not open a dispute, submit a defense, accept a refund or move money.

The kind field distinguishes med, for the Pix MED procedure, from chargeback, for the other dispute records shown by Raims. This field identifies the case type and must be considered when interpreting its reasons and results.

List disputes and navigate pages

Use List disputes. You can filter by charge, stage, disputed amount or creation date range and choose sorting by creation date or amount. The amount filter uses exact equality in Brazilian real cents. Dates use Unix seconds in UTC, and range boundaries are inclusive.

Start without a cursor, process list and copy page.next_after to after while page.has_next is true. Keep the filters and sorting throughout navigation. To change the query, start again without a cursor.

To go back, use page.previous_before in before. Do not send populated after and before together. Copy the entire cursor without interpreting or changing its contents. See Listing and pagination.

An empty list means the page has no cases matching the query. Filtering by charge does not grant access to another company or environment.

View a dispute

Use Retrieve a dispute with the id returned in the list. Keep the complete identifier: the API returns IDs with the dp_ or med_ prefix depending on the record type. charge_id identifies the linked charge, or is null when no link is available.

The details include the report, company response, reason and dates when available. due_at is the recorded response deadline, or null when no deadline is provided. The presence of this field does not mean that the API accepts a response submission.

Tracking stages

Use stage to track the case:

closed alone does not mean a decision in favor of the company or money refunded. The stage shows progress; the result fields describe what has been confirmed for that case. Repeated queries do not start or speed up its review.

Reasons and results

Interpret reason_code together with kind. The same number can represent different reasons:

reason_code: null means the reason is unavailable.

For MED cases, infraction_result can be agreed when the infraction is recognized or disagreed when it is not. refund_result can be partially_accepted, totally_accepted or rejected, according to the refund review. These results alone do not confirm that money was refunded.

refunded_amount_cents shows the total confirmed refunds for the MED case. For chargeback records, won_amount_cents and lost_amount_cents show amounts decided in favor of or against the company, when available. Each field is null when it does not apply to the case type or no result is available; preserve the difference between null and a confirmed zero.

loss_reason_code, when provided, identifies an expired response deadline (1), insufficient evidence (2), invalid documentation (3), a final decision (4) or another reason (5). loss_reason_note adds context when a note is available.

Company and environment

Queries require an API key and use the company and environment linked to it. A Sandbox key queries only that environment; it does not access Production disputes. This documentation console accepts only Sandbox keys.

Use the identifier returned by Raims and handle errors by HTTP status and error.code. For validation failures, also check the fields indicated in error.details. The individual query returns the same error when the case does not exist or is unavailable to the key used.