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
400Request error.
empty_required_header
The X-Idempotency-Key header is required and was not sent. Make the request again including it.
invalid_idempotency_key_length
The X-Idempotency-Key must be between 1 and 64 characters.
invalid_path_param
The order_id provided in the path is not valid. Please confirm it and provide a valid order_id to try again.
refund_amount_exceeds
The refund amount is greater than the available amount on the transaction.
401Error. Access Token not authorized.
unauthorized
The value sent as Access Token is incorrect. Please check and try again with the correct value.
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.
order_already_refunded
The order has already been fully refunded.
cannot_refund_order
The order cannot be refunded. Please check the order status and try again.
order_refund_already_in_process
A full refund request is already being processed for this order.
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.
operation_not_supported
The operation is not supported for this order. Please check the order status and status_detail and try again.
423Resource locked.
resource_locked
The idempotency key (X-Idempotency-Key) is currently locked by an in-flight request. Please retry after a short delay.
500Generic error.
idempotency_validation_failed
Idempotency validation failed. 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-8*********88776-122*********fc20dede6*********a497d7225*********64' \
-H 'X-Idempotency-Key: ebb4bb03-8d69-47e1-bd7a-32620a4bfd86' \
-d '{
"transactions": [
{
"id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
"amount": "24.50"
}
]
}'{
"id": "ORDBTA01KHY4WFPYXJ9Z7S5CGED7WCTP",
"status": "refunded",
"status_detail": "refunded",
"transactions": {
"refunds": [
{
"id": "REF01KJZ0BPKX0BQ0KG1VPBMJDX9G",
"transaction_id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
"reference_id": "",
"amount": "50.00",
"status": "processed"
}
]
}
}