Simulate refund failure
Test failure of a pending Pix refund in the Sandbox.
Simulates failure of a pending Pix refund without completing the refund. Use this request to check the failure reason and the release of the amount back to the available balance.
Sandbox only
Use a Sandbox key or an OAuth connection with Sandbox access. The simulated failure is not available in Production.
See Pending and failed Pix refunds to prepare the test and track its results.
Path Params
Test refund identifier returned by Simulate a pending refund.
Up to 100 characters
Headers
Unique key chosen by your system to identify this request. When retrying, send the same key and parameters. Without this header, the request is processed normally. See the idempotency guide for retention and handling pending or uncertain responses.
1 to 255 characters
Responses
Response Body
Test failure confirmed or the same failure already recorded. The amount returns to the available balance and there is no receipt for a completed refund.
Pix refund request linked to a charge.
Public refund request ID.
ID of the charge that received the original payment.
Amount requested for a refund, in Brazilian real cents.
Request description, or null when not provided.
Current status: reserved for a request being prepared, accepted for a request accepted and awaiting confirmation, completed for a completed refund, failed for a confirmed failure and unknown for a result not yet confirmed. Retrieve the same request until there is a confirmed result.
Request date, in Unix seconds in UTC.
Refund confirmation date, in Unix seconds in UTC, or null.
Confirmed failure date, in Unix seconds in UTC, or null.
Reason available when the status is failed, or null for other statuses. A failure with no recorded cause uses REFUND_FAILURE_REASON_UNAVAILABLE; do not assume the request was rejected.
Confirmed cause code. REFUND_FAILURE_REASON_UNAVAILABLE indicates that the cause is unavailable.
Explanation in English and guidance for tracking the request. Use code to handle the cause; do not depend on the exact text.
Response Body
The refund identifier or request is invalid. This request does not accept a body or query parameters. Check the fields in error.details.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Response Body
This request accepts only Sandbox, using an API key or OAuth authorization for that environment.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Response Body
The refund was not found in the company Sandbox. IDs from another company or from Production receive the same response.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
Response Body
The refund is not pending for this result. Check the current status; a completion cannot be changed to a failure, or a failure to a completion.
Code and explanation of the error returned by the API.
Stable error code.
Error explanation in English. For validation errors, it summarizes the category; details identify the corrections. Use the codes to handle the response.
Invalid fields or references submitted in the body, with the field, code and explanation. Omitted for general errors and when there is no field correction to indicate.
Public name of the JSON field, query parameter, path parameter or header related to the error. Nested fields and lists retain their path and index. $ represents the root of the JSON body.
Reason for the field error, such as REQUIRED, INVALID_TAXID, UNKNOWN_FIELD, DUPLICATE_FIELD or INVALID_TYPE.
Explanation in English of the problem with this field or parameter and the available correction. Do not use the text to determine your integration flow.
For common errors, see HTTP response codes.