# Refund order

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** `/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, it's important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. The header accepts values between 1 and 64 characters.

### Path

- `order_id` (string, required)
  ID of the order to refund. This value is returned in the response from the endpoint [POST /v1/orders](/developers/en/reference/online-payments/wallet-connect/orders/create-order/post).

- `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 to refund, returned in the response from the endpoint [POST /v1/orders](/developers/en/reference/online-payments/wallet-connect/orders/create-order/post).

  - `transactions[].amount` (string, optional)
  Amount to refund from this payment. Must be greater than zero and less than or equal to the available refundable amount. Omit to refund the full available amount of the payment. The field can contain two decimal places or none.

## Response parameters

- `id` (string, optional)
  Identifier of the order being processed, returned in the response from the endpoint [POST /v1/orders](/developers/en/reference/online-payments/wallet-connect/orders/create-order/post).

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

  - `processed`
  All transactions have been successfully processed.

  - `refunded`
  The order has been fully refunded.

- `status_detail` (string, optional)
  Details about the order status.
Possible enum values:

  - `refunded`
  The order has been fully refunded.

  - `partially_refunded`
  The order has been partially refunded.

- `transactions` (object, optional)
  Contains information about the refund 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 created in the request, automatically generated by Mercado Pago.

  - `transactions.refunds[].transaction_id` (string, optional)
  Identifier of the payment transaction that was refunded.

  - `transactions.refunds[].reference_id` (string, optional)
  Reference identifier for the refund (may be empty).

  - `transactions.refunds[].amount` (string, optional)
  Amount refunded. The field can contain two decimal places or none.

  - `transactions.refunds[].status` (string, optional)
  Status of the refund.
Possible enum values:

  - `processed`
  The refund has been successfully processed.

  - `failed`
  The refund failed.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | empty_required_header | The `X-Idempotency-Key` header is required and was not sent. Make the request again including it. |
| 400 | invalid_idempotency_key_length | The `X-Idempotency-Key` must be between 1 and 64 characters. |
| 400 | 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. |
| 400 | refund_amount_exceeds | The refund amount is greater than the available amount on the transaction. |
| 401 | unauthorized | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 404 | order_not_found | Order not found. Please check if you provided the correct `order_id`. |
| 404 | transaction_not_found | Transaction not found. Please check if you provided the correct `transaction_id`. |
| 409 | order_already_refunded | The order has already been fully refunded. |
| 409 | cannot_refund_order | The order cannot be refunded. Please check the order `status` and try again. |
| 409 | order_refund_already_in_process | A full refund request is already being processed for this order. |
| 409 | 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. |
| 409 | operation_not_supported | The operation is not supported for this order. Please check the order `status` and `status_detail` and try again. |
| 423 | resource_locked | The idempotency key (`X-Idempotency-Key`) is currently locked by an in-flight request. Please retry after a short delay. |
| 500 | idempotency_validation_failed | Idempotency validation failed. Please try submitting the request again. |
| 500 | internal_error | 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": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "amount": "24.50"
  }
  ]
  }'
```

## Response example

```json
{
  "id": "ORDBTA01KHY4WFPYXJ9Z7S5CGED7WCTP",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
  "refunds": [
  {
  "id": "REF01KJZ0BPKX0BQ0KG1VPBMJDX9G",
  "transaction_id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "reference_id": "",
  "amount": "50.00",
  "status": "processed"
  }
  ]
  }
}
```

## Use cases

### Total refund of a payment

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{order_id}/refund' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{}'
```

```json
{
  "id": "ORDBTA01KHY4WFPYXJ9Z7S5CGED7WCTP",
  "status": "refunded",
  "status_detail": "refunded",
  "transactions": {
  "refunds": [
  {
  "id": "REF01KJZ0BPKX0BQ0KG1VPBMJDX9G",
  "transaction_id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "reference_id": "",
  "amount": "50.00",
  "status": "processed"
  }
  ]
  }
}
```

### Partial refund of a payment

```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": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "amount": "24.50"
  }
  ]
  }'
```

```json
{
  "id": "ORDBTA01KHY4WFPYXJ9Z7S5CGED7WCTP",
  "status": "processed",
  "status_detail": "partially_refunded",
  "transactions": {
  "refunds": [
  {
  "id": "REF01KJZ0CZ4FBFQMNZADKW8T7ZEH",
  "transaction_id": "PAY01KHY4WFPYXJ9Z7S5CGG0SE8KN",
  "reference_id": "",
  "amount": "24.50",
  "status": "processed"
  }
  ]
  }
}
```