Este endpoint permite realizar la devolución total o parcial de los valores asociados a una order. Para realizar un reembolso total, no debes enviar el monto a reembolsar en el body de la requisición. Para realizar un reembolso parcial sí debes indicar el valor a ser reembolsado, junto con el identificador de la transacción que deseas devolver. En caso de éxito, la solicitud devolverá una respuesta con el estado 201.
POST
REQUERIDO
REQUERIDO
REQUERIDO
REQUERIDO
Errores
Cada respuesta de la API incluye un código de estado HTTP que indica el resultado de la solicitud. El código 200 indica que la operación fue exitosa, el 400 señala un error en los datos enviados y el 500 indica un error interno del servidor.
Algunos errores 400 pueden gestionarse de forma programática e incluyen un código que describe la causa del error.
400Error de solicitud.
empty_required_header
El header "X-Idempotency-Key" es requerido y no fue enviado. Vuelve a realizar la requisición incluyéndolo.
invalid_idempotency_key_length
El valor enviado en el header "X-Idempotency-Key" excedió el tamaño máximo permitido. El header acepta valores entre 1 y 64 caracteres.
invalid_path_param
El "order_id" proporcionado en el path de la requisición no es correcto. Compruébalo y proporciona un ID válido para volver a intentarlo.
refund_amount_exceeds
El valor del reembolso es mayor que el valor disponible.
404No encontrada.
order_not_found
Order no encontrada. Comprueba si enviaste el ID correcto.
transaction_not_found
Transaction no encontrada. Comprueba si enviaste el ID correcto.
409Alguna regla específica del sistema no permite realizar la acción debido a restricciones definidas.
idempotency_key_already_used
El valor enviado como header de idempotencia ("X-Idempotency-Key") ya fue utilizado. Por favor, vuelve a intentar realizar la requisición enviando un nuevo valor.
order_already_refunded
Order ya reembolsada.
cannot_refund_order
No se puede reembolsar la order. Comprueba si la order ya ha sido reembolsada.
order_refund_already_in_process
Ya existe una solicitud de reembolso completo en proceso para la order en cuestión.
429Límite de solicitudes excedido.
too_many_requests
"Client ID" bloqueado por el gateway porque se alcanzó el límite de solicitudes para el ID en cuestión. Lee el header "Retry-After" de la respuesta y espera la cantidad de segundos indicada antes de volver a intentarlo. Para mayor resiliencia, implementa backoff exponencial con jitter, es decir, aumenta el tiempo de espera en cada nuevo intento y añade una variación aleatoria para evitar el reenvío simultáneo de muchas solicitudes.
usage_quota_exceeded
Cuota impuesta por el backend de la API porque se alcanzó el límite de solicitudes por cliente. Lee el header "Retry-After" de la respuesta y espera la cantidad de segundos indicada antes de volver a intentarlo. Para mayor resiliencia, implementa backoff exponencial con jitter, es decir, aumenta el tiempo de espera en cada nuevo intento y añade una variación aleatoria para evitar el reenvío simultáneo de muchas solicitudes.
500Error genérico.
idempotency_validation_failed
Falla en la validación de idempotencia. Intenta enviar la solicitud nuevamente.
internal_error
Error genérico. Intenta enviar la solicitud nuevamente.
curl -X POST \
'https://api.mercadopago.com/v1/orders/{order_id}/refund'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-1*********685765-12*********1b4332e5c*********e077d7679*********664' \
-H 'X-Idempotency-Key: 5b11431d-663b-4b54-a144-eafa4530ff21' \
-d '{
"transactions": [
{
"id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
"amount": "24.50"
}
]
}'{
"id": "ORD01J49MMW3SSBK5PSV3DFR32959",
"status": "processed",
"status_detail": "refunded",
"transactions": {
"refunds": [
{
"id": "REF01J49MMW3SSBK5PSV3DFR32959",
"transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
"reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
"amount": "24.50",
"status": "processed"
}
]
}
}