# Refund order

This endpoint allows to create a total or partial refund for a payment transaction associated with an order for Mercado Pago Point. 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. In addition, they are only available for payments made with card, QR codes paid with the Mercado Pago wallet and other wallets. Both types of refunds can be made up to 90 days after the payment is made. 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. This is useful for avoiding errors, such as creating two identical payments. 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 associated with the order.

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

  - `transactions.refunds[].transaction_id` (string, optional)
  Identifier of the payment transaction that is being refunded, received in the response to its creation.

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

  - `transactions.refunds[].amount` (string, optional)
  Refund amount.

  - `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.

## 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 an invalid format. It must start with the prefix "ORD" and be followed by 26 characters. Please check it and provide a valid ID to try again. |
| 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 Access Token is incorrect, therefore the order 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 | The order was already refunded. |
| 409 | cannot_refund_order | The order status does not allow refund. |
| 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",
  "reference_id": "12345678",
  "amount": "24.50",
  "status": "processing"
  }
  ]
  }
}
```