# 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 function allows you to repeat requests safely, without the risk of carrying out the same action more than once by mistake. This is useful to avoid mistakes such as creating two identical payments. To ensure that each request is unique, it is important to use a unique value in your request header. We suggest using a V4 UUID or random strings. The header accepts values between 1 and 128 characters.

### Path

- `order_id` (string, required)
  ID of the order that is being refunded. This value is returned in the response to the request made to the endpoint [POST /v1/orders](/developers/en/reference/online-payments/checkout-api/create-order/post).

- `splits` (array, optional)
  List of receivers to refund. If omitted, the total amount is refunded to all participants. To refund a specific participant, include their `receiver_id` and optionally the `amount` to refund.

  - `splits[].receiver_id` (string, optional)
  Identifier of the receiver that will receive the refund. Same value used when creating the split order.

  - `splits[].amount` (string, optional)
  Amount to refund to this receiver. If omitted, the full amount of their portion is refunded.

## Response parameters

- `id` (string, optional)
  Identifier of the order being processed in the request.

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

  - `processed`
  All transactions have been successfully processed.

  - `refunded`
  The order has been refunded.

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

  - `refunded`
  The order has been refunded.

  - `partially_refunded`
  The order has been partially refunded.

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

  - `transactions.refunds[].transaction_id` (string, optional)
  Identifier of the transaction associated with the refund.

  - `transactions.refunds[].reference_id` (string, optional)
  Reference ID of the transaction.

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

  - `transactions.refunds[].status` (string, optional)
  Payment status.
Possible enum values:

  - `processed`
  The payment has been successfully processed.

## 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 value sent in the `X-Idempotency-Key` header exceeded the allowed size. The header accepts values between 1 and 128 characters. |
| 400 | invalid_path_param | The `order_id` provided in the request path is not correct. Please confirm it and provide a valid ID to try again. |
| 400 | refund_amount_exceeds | The requested refund amount is greater than the available amount. |
| 403 | forbidden | The application does not have permission to access this resource. Please check that the Access Token used has the necessary permissions and scopes for this operation. |
| 403 | PA_UNAUTHORIZED_RESULT_FROM_POLICIES | The account is blocked and its API keys have been revoked. At least one policy evaluated by the Policy Agent returned an `UNAUTHORIZED` result. |
| 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 | 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 | order_already_refunded | Order already refunded. |
| 409 | cannot_refund_order | Cannot refund order. Please check if the order is already refunded. |
| 409 | order_refund_already_in_process | There is already a full refund request in process for the order in question. |
| 429 | too_many_requests | Client ID blocked by the gateway because the request limit for the ID in question was reached. Read the `Retry-After` header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. |
| 429 | usage_quota_exceeded | Quota enforced by the API backend because the per-client request limit was reached. Read the `Retry-After` header from the response and wait the indicated number of seconds before retrying. For greater resilience, implement exponential backoff with jitter, that is, increase the wait time with each new attempt and add a random variation to avoid simultaneous retransmission of multiple requests. |
| 500 | idempotency_validation_failed | Idempotency validation failure. 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 '{
  "splits": [
  {
  "receiver_id": "550e8400-e29b-41d4-a716-446655440001",
  "amount": "250.00"
  }
  ]
  }'
```

## Response example

```json
{
  "id": "ORD01J49MMW3SSBK5PSV3DFR32959",
  "status": "processed",
  "status_detail": "refunded",
  "transactions": {
  "refunds": [
  {
  "id": "REF01J49MMW3SSBK5PSV3DFR32959",
  "transaction_id": "PAY01JEVQM06WDW16MAQ8B5SC0MSC",
  "reference_id": "01JEVQM899NWSQC4FYWWW7KTF9",
  "amount": "24.50",
  "status": "processed"
  }
  ]
  }
}
```