This endpoint performs a full or partial refund of a processed order. To perform a full refund, you must not send the amount to be refunded in the request body. To perform a partial refund, you must indicate the amount to be refunded along with the transaction ID you wish to return. Multiple partial refunds can be issued against the same order as long as the cumulative refunded amount does not exceed the total paid amount. In case of success, the request will return a response with status 201.
POST
REQUIRED
REQUIRED
REQUIRED
CONDITIONALLY REQUIRED
splits.CONDITIONALLY REQUIRED
transactions.status and status_detail values and their meanings, see the order status reference.status and status_detail values and their meanings, see the order status reference.400Request error.
refund_amount_exceeds
An incorrect value for some property was sent. The amount provided exceeds what is available for refund. Check the message returned in the error details to find out what the problem was and try again.
order_refund_already_in_process
A full refund is already being processed for this order. Check the message returned in the error details to find out what the problem was and try again.
401Error. Access Token not authorized.
401
The value sent as Access Token is incorrect. Please check and try again with the correct value.
invalid_credentials
There is no support for test credentials. Use test users with production credentials for the sandbox environment and your production credentials for the production environment.
403Error. Forbidden.
forbidden
The application does not have permission to access this resource. Please check that the Access Token used has the necessary permissions and scopes for this operation.
PA_UNAUTHORIZED_RESULT_FROM_POLICIES
The account is blocked and its API keys have been revoked. At least one policy evaluated by the Policy Agent returned an UNAUTHORIZED result.
404Resource not found.
transaction_not_found
The transaction ID provided does not exist in this order. Use the id from transactions.payments[].id.
409Some specific system rule does not allow the action to be performed due to defined restrictions.
idempotency_key_already_used
The value sent as the idempotency header (X-Idempotency-Key) has already been used. Please try the request again sending a new value.
order_already_refunded
Order already refunded.
cannot_refund_order
Cannot refund order. Please check if the order is already refunded.
order_refund_already_in_process
There is already a full refund request in process for the order in question.
429Request limit exceeded.
too_many_requests
Client ID blocked by the gateway because the request limit for the ID in question was reached. Read the Retry-After header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests.
usage_quota_exceeded
Quota enforced by the API backend because the per-client request limit was reached. Read the Retry-After header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests.
500Generic error.
internal_error
Generic error. Please try submitting the request again.
curl -X POST \
'https://api.mercadopago.com/v1/orders/{order_id}/refund'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-H 'X-Idempotency-Key: 61b830f4-0247-4f7a-b870-ee3e3a7b3624' \
-d '{
"transactions": [
{
"id": "PAY01HRYFWNYRE1MR1E60MW3X0T2P",
"amount": "100.00"
}
],
"splits": [
{
"user_id": 1,
"amount": "50.00"
}
]
}'{
"id": "ORD01J49MMW3SSBK5PSV3DFR32959",
"status": "refunded",
"status_detail": "refunded",
"transactions": {
"refunds": [
{
"id": "REF01J49MMW3SSBK5PSV3DFR32959",
"transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
"reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
"amount": "24.50",
"status": "processed"
}
]
}
}