Statuses and results
Interpret charge, refund, and dispute statuses while distinguishing progress from financial results.
A status reports a resource's progress. A reason explains a recorded condition, and a result describes the conclusion of an analysis. Check which field is being shown: these fields are not interchangeable.
Charge statuses
In the API, a charge's status uses the codes below. The history may also
contain statuses for methods that are not available for new charges.
| Code or value | Meaning | How to interpret |
|---|---|---|
0 | Created | Charge registered without confirmed payment. Whether it can be paid depends on its due date, enabled methods, and available payment details. |
1 | Awaiting payment | Charge awaiting payment confirmation. Opening checkout or issuing Pix details or a boleto does not confirm receipt. |
2 | Authorized | Payment authorized without confirmation of completion. Do not deliver the product or consider the amount received based only on this status. |
3 | Processing | Payment processing without a final result yet. Track the existing charge before requesting another payment. |
4 | Paid | Charge payment confirmed. Fees, holds, and refunds are separate information and may affect the amount available for use. |
5 | Partially refunded | Part of the amount received has been returned. Check the history and refund eligibility to determine the remaining amount that can be requested. |
6 | Refunded | The amount received has been returned in full. The refund may involve more than one entry; check the links and history to reconcile it. |
7 | Cancelled | Charge cancelled for new payments. Cancelling a charge is different from returning a payment received. |
8 | Expired | The payment deadline has passed. This status does not prove bank cancellation: check the charge and boleto before concluding that cancellation occurred. |
9 | Failed | The charge or its payment ended in failure. Check the available details before requesting another charge; this status does not confirm receipt. |
10 | Disputed | The payment is associated with a dispute. Check the case for its stage, amounts, and available information. |
11 | Dispute under review | The dispute is under review. The result and any financial effect still need to be checked in the case and statement. |
12 | Dispute lost | The dispute outcome was unfavorable to the company. Check the amounts reported in the case and related entries to determine the financial effect. |
13 | Dispute won | The decision was in the company's favor. Check the balance and entries: this status does not indicate when the held amount became available. |
Authorization, issuance of payment details, and processing do not confirm that a charge has been paid. An expired charge does not prove that an issued boleto has been cancelled. See Charges for the available actions and the conditions for each request.
Refund statuses
A refund's status in the API is a string. It does not use charge status
numbers. Track the same rf_ identifier to check the result.
| Code or value | Meaning | How to interpret |
|---|---|---|
reserved | Requested | The refund request was registered, but the refund has not been confirmed yet. Track this same refund before making another request. |
accepted | Accepted for processing | The request was accepted and awaits the final result. Acceptance does not confirm that the money has returned to the payer. |
completed | Completed | The refund was confirmed. Check the refund amount and related entries to reconcile it. |
failed | Failed | The refund failure was confirmed. Check the reason, other refunds for the charge, and eligibility before making a new request. |
unknown | Awaiting confirmation | The refund result has not been confirmed yet. Continue checking the same request; do not treat this status as failure or a completed refund. |
A connection failure does not mean the request failed. Check the request and charge history before trying again. In Sandbox, a confirmed refund belongs to the simulation; it does not move real money.
Refund failure reasons
failure_reason.code reports a public cause of a confirmed failure. In other
statuses, failure_reason is null.
| Code or value | Meaning | How to interpret |
|---|---|---|
REFUND_NOT_SUBMITTED | Request not submitted | This refund was not submitted for processing. Check the charge history and eligibility before requesting again. |
REFUND_REJECTED | Request rejected | The refund request was rejected. Check the charge refunds before making another attempt. |
REFUND_PROCESSING_UNAVAILABLE | Processing unavailable | Processing was unavailable and this refund ended in failure. Check the charge and its eligibility before another request. |
REFUND_PROCESSING_FAILED | Processing failure confirmed | The refund failure was confirmed without a more detailed reason. Check the charge refunds before trying again. |
REFUND_FAILURE_REASON_UNAVAILABLE | Reason not provided | No confirmed reason is available for this refund failure. Check the history and contact support if you need to clarify the result. |
Use the code to handle the response. The message explains the problem and can be improved without changing the code's meaning. The absence of a detailed cause does not justify assuming bank rejection or automatically requesting another refund.
Dispute types
You need the kind field to interpret reasons and results.
| Code or value | Meaning | How to interpret |
|---|---|---|
chargeback | Payment dispute | Identifies dispute history classified as chargeback. Interpret the reason using that category's catalog; the name does not confirm that cards are enabled for new charges. |
med | Pix dispute (MED) | Identifies a case under the Pix Mecanismo Especial de Devolução. Check the stage, reason, and analysis results; the existence of the case does not confirm a refund or fraud. |
The name chargeback does not prove that cards are available for new charges
in Raims. It identifies the category of the record retrieved.
Dispute stages
The public stage field reports dispute progress:
| Code or value | Meaning | How to interpret |
|---|---|---|
open | Open | The dispute was registered and does not yet have a confirmed analysis. Check the information and deadlines shown in the case. |
in_analysis | Under analysis | The dispute is under analysis. This stage does not yet confirm a result or refund. |
refund_in_analysis | Refund under analysis | Analysis of a possible refund is in progress. Check the result and refunded amount when provided; this stage does not prove that money has left the account. |
closed | Closed | Tracking of the analysis has ended. Read the results and amounts reported in the case: closure alone does not mean a win, loss, or refund. |
cancelled | Cancelled | The dispute was cancelled. This stage does not confirm a refund or balance release; check the amounts and statement. |
rejected | Opening rejected | The request to open the dispute was rejected. Check the available details; this result is not a refund to the payer. |
failed | Failed | Dispute processing was not completed because of a failure. Check the case and contact support if you need to clarify the result. |
closed reports that the analysis has ended. On its own, it does not mean a
decision in the company's favor or a refund. Check the results and amounts
available in the dispute details.
Reasons reported in MED
When kind is med, interpret reason_code using this table. The reason is
the allegation reported in the dispute, not a finding of fraud.
| Code or value | Meaning | How to interpret |
|---|---|---|
1 | Scam reported | The complainant reported that the payment is linked to a scam. This category records the dispute reason and does not confirm that fraud occurred. |
2 | Account takeover reported | The complainant reported that another person used the account without authorization. The conclusion depends on case analysis. |
3 | Coercion reported | The complainant stated that they made the payment under coercion. Check the analysis results for the case conclusion. |
4 | Fraudulent access reported | The dispute reports suspected fraudulent access related to the payment. The reported reason does not amount to proven fraud. |
5 | Other reason | The reason was classified outside the other categories. Check the complaint details when available. |
6 | Unrecognized reason | The reason received does not match a recognized category in this catalog. Do not infer the cause from the code; check the available case details. |
Reasons for other disputes
When kind is chargeback, reason_code uses this other table. The same
number can have a different meaning in a MED case.
| Code or value | Meaning | How to interpret |
|---|---|---|
1 | Fraud alleged | The dispute was registered with an allegation of fraud. The reason does not replace the analysis result. |
2 | Unrecognized purchase | The complainant stated that they do not recognize the purchase. Check the case details and result. |
3 | Unrecognized service | The complainant stated that they do not recognize the service charged. This category records the allegation and does not determine the dispute result. |
4 | Product or service mismatch | The complainant reported a mismatch in the product or service. Check the case details to understand the complaint. |
5 | Improper charge | The complainant alleged an improper charge. The conclusion and any financial effect depend on the result reported in the case. |
6 | Other reason | The dispute uses a reason outside the other categories. Check the available details; do not interpret this value as the equivalent reason in a MED case. |
A null reason is not available to show. Do not fill this field with a cause
inferred from the amount, date, or payment type.
MED analysis results
infraction_result reports the result of the infraction analysis:
| Code or value | Meaning | How to interpret |
|---|---|---|
agreed | Infraction recognized | The analysis recognized the reported infraction. This result does not confirm a refund; check the refund analysis result and the amount actually returned. |
disagreed | Infraction not recognized | The analysis did not recognize the reported infraction. Check the other available results and amounts to understand the case outcome. |
refund_result reports the result of the refund request analysis:
| Code or value | Meaning | How to interpret |
|---|---|---|
partially_accepted | Refund partially accepted | The analysis accepted returning part of the amount requested. Check the amount actually returned; acceptance alone does not prove a money movement. |
totally_accepted | Refund fully accepted | The analysis accepted the full refund requested. Check the refunded amount and statement to confirm the financial effect. |
rejected | Refund rejected | The analysis rejected the refund requested. Check the case and related entries to reconcile the amounts, including any holds or releases. |
Recognizing an infraction and accepting a request do not, on their own,
confirm that money has been returned. refunded_amount_cents reports the
case's total confirmed refunds when that information is available. A null
result remains different from a rejection or a confirmed zero amount.
Dispute loss reasons
loss_reason_code, when provided, describes the recorded reason for the
unfavorable decision. A note may add context to this code.
| Code or value | Meaning | How to interpret |
|---|---|---|
1 | Response deadline expired | The recorded reason for the loss was expiry of the response deadline. Check the case dates and result. |
2 | Insufficient evidence | The evidence submitted was considered insufficient for the dispute. Check the available case details. |
3 | Invalid documentation | The documentation submitted was not accepted in the analysis. Check the case details to understand the reported result. |
4 | Final decision | The loss was recorded based on the final analysis decision. Check the case amounts and statement to identify the financial effect. |
5 | Other loss reason | The loss has a reason outside the other categories. Check the reason note when available; the absence of a note does not justify inferring a cause. |
These reasons do not replace checking the case's stage and result. See Disputes to track the available data while distinguishing analysis, decisions, and money movements.