This endpoint allows to create a total or partial refund for a payment transaction associated with an order for Mercado Pago QR Code. For a total refund, the request body must be empty, while for a partial refund, you must indicate the amount to be refunded along with the identifier of the payment transaction to be returned, as long as the total amount refunded does not exceed the full value of the transaction. Additionally, only orders with "status=processed" can be refunded. In case of success, the request will return a response with status 201.
POST
REQUIRED
REQUIRED
REQUIRED
400Error.
empty_required_header
The "X-Idempotency-Key" header is required and was not sent. Make the requisition again including it.
invalid_path_param
The "order_id" provided in the request path has has an invalid format. It must begin with the prefix "ORD" and be followed by 26 characters. Please confirm it and provide a valid ID to try again.
invalid_order_owner
Due to internal validations, you cannot process a refund for an order that you did not create.
in_store_payment_refund_order
The time limit for issuing a refund for the order has been exceeded. Please verify that you are within the 330 days period from the order creation date.
unsupported_partially_refunds
Due to internal validations, the order does not support partial refunds.
refund_amount_exceeds
Refund amount exceeds the available amount. Check if the requested amount is less than or equal to the available balance in the order.
401Error.
unauthorized
The value sent as Access Token is incorrect. Please check and try again with the correct value.
user_not_authorized
User not authorized to perform this action.
403Error.
partial_refund_forbidden_with_tips
Partial refunds are not allowed when the order has tips.
404Error.
order_not_found
The value sent as Order ID does not correspond to a created order, therefore it could not be found. Please check and try again with the correct value.
transaction_not_found
The transaction was not found. Check if the transaction ID sent in the request body is correct and belongs to the specified order.
409Error.
idempotency_key_already_used
The value sent as the idempotency header has already been used with a different request within the last 24 hours. Please try the request again sending a new value.
order_already_refunded
You are trying to return an order that has been already refunded. Verify if you have submitted the correct ID.
cannot_refund_order,
The status of the order does not allow its refund. Only orders with status 'processed' can be refunded.
refund_period_exceeded
The time limit allowed to make a refund of the order has been exceeded.
action_not_allowed_for_current_state
Action not allowed for the current payment status.
refund_in_progress
Refund in progress, please wait a few minutes.
movement_operations_pending
The order has pending movements, please wait a few minutes.
422Error.
payment_not_refundable
It is not possible to refund this payment.
amount_not_refundable
The amount cannot be refunded, try with another amount.
max_refunds_exceeded
The maximum number of refunds for this order has been exceeded.
425Error.
order_payment_not_yet_enabled_for_refund
The order is not yet enabled for refund, please try again later.
428Error.
insufficient_money_for_refund
It is not possible to make the refund, insufficient money in the account.
500Error.
idempotency_validation_failed
Validation fail. Please try submitting the request again.
500
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*********932064-12*********edf6d3c99*********2236c703f*********668' \
-H 'X-Idempotency-Key: be4e05f4-3228-4f95-92b7-c5500fddd6a9' \
-d '{
"transactions": [
{
"id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
"amount": "25"
}
]
}'{
"id": "ORD0000ABCD222233334444555566",
"status": "refunded",
"status_detail": "refunded",
"transactions": {
"refunds": [
{
"id": "REF01J67CQQH5904WDBVZEM1234D",
"transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
"amount": "25",
"status": "processing",
"reference_id": "12345678"
}
]
}
}