Refund an order

Server URLloading...

POST

/stores/{store_id}/orders/{order_id}/refund

Send

Authorization

Path

Header

Body

Returns money through the gateway that took it (Mercado Pago), from the order's latest approved payment. Omit amount_cents to refund what is left on it; pass it for a partial refund. Local state changes only after the gateway accepts: the refund is recorded, and once the payment is fully refunded the order becomes refunded (stock released, open production cancelled, orders.updated webhook and orders.refunded event); otherwise its payment_status becomes partially_refunded.

Send an Idempotency-Key header. Every call that passes the checks creates a new refund at the gateway, so a blind retry of a partial refund returns money twice. With the header, a retry replays the first response for 24 hours, and the key is also forwarded to the gateway. A retry without it is still bounded by the refundable amount: once the payment is fully refunded, further calls fail with already_refunded.

Payments taken outside a gateway (cash, card machine, manual PIX) cannot be refunded here; record them with PATCH .../status to refunded.

Path Parameters

Header Parameters

Response Body

curl -X POST "https://example.com/stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/orders/497f6eca-6276-4993-bfeb-53cbbbba6f08/refund" \  -H "Content-Type: application/json" \  -d '{}'

{
  "amount_cents": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  "currency": "string",
  "external_id": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "order_id": "93101167-9065-4b9c-b98b-5d789a3ed9fe",
  "payment_intent_id": "7e322e88-5311-4979-b283-b9a687137f41",
  "provider_code": "string",
  "reason": "string"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}

{
  "code": "not_found",
  "details": {},
  "error": "Order not found"
}