# Refund order

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** `/v1/orders/{order_id}/refund`

## Request parameters

### Header

- `X-Idempotency-Key` (string, required)
  This feature allows you to safely retry requests without the risk of accidentally performing the same action more than once. To ensure that each request is unique, you must use an exclusive value in the header of each unique value for each call. If you use a value already assigned to another request, you will receive information corresponding to that created resource in response, not this new request. We suggest using a UUID V4 or random strings.

### Path

- `order_id` (string, required)
  ID of the order that contains the associated payment transaction to be refunded. This value is returned in the response to the 'Create order' ("/v1/orders") request.

- `transactions` (array, optional)
  Contains information about the transaction associated with the order to be refunded. This array is optional and should only be sent for partial refunds. Do not send this node for a total refund.

  - `transactions[].id` (string, optional)
  Identifier of the payment transaction created in the request, obtained in the response to the creation of the order ("transactions.payments.id"). Required for partial refunds.

  - `transactions[].amount` (string, optional)
  Amount to be refunded. Must be less than the original transaction value. The field can contain two decimal places or none. Required for partial refunds.

## Response parameters

- `id` (string, optional)
  Identifier of the order to be refunded, received in the response to its creation.

- `status` (string, optional)
  Current status of the order or the transaction.
Possible enum values:

  - `refunded`
  The order has been succesfully refunded (total refund).

  - `processed`
  The order payment has been processed. This status is returned when a partial refund is made and there is still remaining balance in the order. To check the status of the refund, run the 'Get order by ID' ("/v1/orders/{id}") request and confirm it in the "transactions.refunds.status" field, and enable your Webhooks notifications.

- `status_detail` (string, optional)
  Details about the refund status. It is returned exclusively when the order is reimbursed through the API
Possible enum values:

  - `refunded`
  The order has been succesfully refunded (total refund).

  - `partially_refunded`
  The order has been partially refunded. A portion of the transaction amount has been returned, but there is still remaining balance.

- `transactions` (object, optional)
  Contains information about the transaction associated with the order.

  - `transactions.refunds` (array, optional)
  Contains information about the refund transaction associated with the order.

  - `transactions.refunds[].id` (string, optional)
  Identifier of the transaction, automatically generated by Mercado Pago.

  - `transactions.refunds[].transaction_id` (string, optional)
  Identifier of the "payments" that will be refunded, assigned to the transaction at the time of order creation.

  - `transactions.refunds[].amount` (string, optional)
  Amount returned in the refund. If the payment was discounted, that amount will be reflected.

  - `transactions.refunds[].status` (string, optional)
  Current status of the refund for the transaction associated with an order.
Possible enum values:

  - `processing`
  The total refund was successfully requested and is being processed. Enable your Webhooks notifications to receive an alert if the refund was successful, or to find out if there was an error.

  - `processed`
  The partial refund of the transaction was requested and processed successfully.

  - `transactions.refunds[].reference_id` (string, optional)
  ID that associates the transaction and its refund.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the requisition again including it. |
| 400 | 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. |
| 400 | invalid_order_owner | Due to internal validations, you cannot process a refund for an order that you did not create. |
| 400 | 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 160 days period from the order creation date. |
| 400 | unsupported_partially_refunds | Due to internal validations, the order does not support partial refunds. |
| 400 | 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. |
| 401 | unauthorized | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 401 | user_not_authorized | User not authorized to perform this action. |
| 403 | partial_refund_forbidden_with_tips | Partial refunds are not allowed when the order has tips. |
| 404 | 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. |
| 404 | 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. |
| 409 | 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. |
| 409 | order_already_refunded | You are trying to return an order that has been already refunded. Verify if you have submitted the correct ID. |
| 409 | cannot_refund_order, | The status of the order does not allow its refund. Only orders with status=processed can be refunded. |
| 409 | refund_period_exceeded | The time limit allowed to make a refund of the order has been exceeded. |
| 409 | action_not_allowed_for_current_state | Action not allowed for the current payment status. |
| 409 | refund_in_progress | Refund in progress, please wait a few minutes. |
| 409 | movement_operations_pending | The order has pending movements, please wait a few minutes. |
| 422 | payment_not_refundable | It is not possible to refund this payment. |
| 422 | amount_not_refundable | The amount cannot be refunded, try with another amount. |
| 422 | max_refunds_exceeded | The maximum number of refunds for this order has been exceeded. |
| 425 | order_payment_not_yet_enabled_for_refund | The order is not yet enabled for refund, please try again later. |
| 428 | insufficient_money_for_refund | It is not possible to make the refund, insufficient money in the account. |
| 500 | idempotency_validation_failed | Validation fail. Please try submitting the request again. |
| 500 | 500 | Generic error. Please try submitting the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{order_id}/refund' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "transactions": [
  {
  "id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50"
  }
  ]
  }'
```

## Response example

```json
{
  "id": "ORD0000ABCD222233334444555566",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
  "refunds": [
  {
  "id": "REF01J67CQQH5904WDBVZEM1234D",
  "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3",
  "amount": "24.50",
  "status": "processing",
  "reference_id": "12345678"
  }
  ]
  }
}
```