This endpoint performs a full or partial refund of the transactions associated with an 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. In case of success, the request will return a response with status 201.
POST
REQUIRED
REQUIRED
REQUIRED
REQUIRED
400Request error.
empty_required_header
The "X-Idempotency-Key" header is required and was not sent. Make the requisition again including it.
invalid_idempotency_key_length
The value sent in the "X-Idempotency-Key" header exceeded the allowed size. The header accepts values between 1 and 64 characters.
invalid_path_param
The "order_id" provided in the request path is not correct. Please confirm it and provide a valid ID to try again.
refund_amount_exceeds
The requested refund amount is greater than the available amount.
404Not found.
order_not_found
Order not found. Please check if you provided the correct order ID.
transaction_not_found
Transaction not found. Please check if you provided the correct Transaction ID.
409Some specific system rule does not allow the action to be performed due to defined restrictions.
idempotency_key_already_used
Validation fail. Please try submitting the request again.
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.
500Generic error.
idempotency_validation_failed
Validation fail. Please try submitting the request again.
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 APP_USR-5*********956537-12*********ff1a3d36d*********47e7b9985*********770' \
-H 'X-Idempotency-Key: 846d8c93-cda0-4834-a55d-20052a2bbade' \
-d '{
"transactions": [
{
"id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
"amount": "50.00"
}
]
}'{
"id": "ORD01J49MMW3SSBK5PSV3DFR32959",
"status": "processed",
"status_detail": "refunded",
"transactions": {
"refunds": [
{
"id": "REF01J49MMW3SSBK5PSV3DFR32959",
"transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
"reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
"amount": "24.50",
"status": "processed"
}
]
}
}