The Orders API unifies QR Code payment processing on Mercado Pago, providing standardized endpoints, a consolidated status model, and new native capabilities that did not exist in the Instore Orders API. In addition, all new Mercado Pago features will be developed on the Orders API.

Migrating from the Instore Orders API to the Orders API involves updating endpoints and request fields, consolidating the notifications model, and leveraging new native resources that did not exist before: dedicated query endpoints by order_id, cancellation, and refund. The migration does not change the business flow: the customer continues scanning the QR Code with the Mercado Pago app and confirming the payment.

Read on to learn how to complete this migration.

Before starting the migration steps, see the table below for an overview of all endpoint changes. In the Instore Orders API, each operation used a URL with the user and point-of-sale identifier in the path. The Orders API consolidates these operations into standardized endpoints and introduces resources that did not exist before.

In the Instore Orders API, there were two valid endpoints for creation and cancellation: /mpmobile/instore/qr/{user_id}/{external_id}, using the external point-of-sale identifier, and /mpmobile/instore/qr/{pos_id}, using the internal identifier. Both migrate to the same endpoint in the Orders API: POST /v1/ordersAPI, where the point of sale is identified by the config.qr.external_pos_id field in the body.

One of the most significant changes between the Instore Orders API and the Orders API is the status model. In the Instore Orders API, the state of a transaction was determined by monitoring notifications from two independent topics , payments and merchant_orders, with distinct fields and values for each. The Orders API unifies this behavior into a single status field in the order. See the complete mapping below.

In addition, the Orders API also introduces the status_detail field, which provides greater detail on the transaction state. The possible values are created, canceled, accredited, refunded, and expired.

The Orders API introduces two mandatory header changes that affect all endpoints. The Access Token must be sent via the Authorization header. Sending it as a query parameter is not allowed in the Orders API. Apply the following changes before testing any other resource.

The creation endpoints POST /mpmobile/instore/qr/{user_id}/{external_id}API and POST /mpmobile/instore/qr/{pos_id} migrate to POST /v1/ordersAPI. Beyond the URL change, the request structure was significantly reorganized: the user and point-of-sale identifiers move from the path to the body, new required fields were introduced, and the Orders API offers three QR Code modes configurable via config.qr.mode. Follow the steps below to adapt the request, response, and error handling.

curl
Copiar
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "type": "qr",
    "total_amount": "50.00",
    "external_reference": "ext_ref_1234",
    "config": {
      "qr": {
        "external_pos_id": "STORE001POS001",
        "mode": "static"
      }
    },
    "transactions": {
      "payments": [
        {
          "amount": "50.00"
        }
      ]
    },
    "items": [
      {
        "title": "Smartphone",
        "unit_price": "50.00",
        "quantity": 1,
        "unit_measure": "unit"
      }
    ]
  }'

The query endpoint GET /v1/orders/{order_id}API is a capability exclusive to the Orders API. The Instore Orders API did not have a dedicated endpoint to query the status of a transaction. Previously, the status was obtained exclusively via webhook notifications from the payments and merchant_orders topics. The Orders API allows querying the complete order status at any time, including status, payments, refunds, and payment method data.

curl
Copiar
curl -X GET \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The cancellation endpoint changes completely in structure: from DELETE /mpmobile/instore/qr/{user_id}/{external_id}API to POST /v1/orders/{order_id}/cancelAPI. The HTTP method changes from DELETE to POST, the {user_id} and {external_id} are removed from the path, and the cancellation now operates on the unique order identifier.

In the Instore Orders API, cancellation deleted the active order associated with the point of sale, an operation on the point of sale rather than on the individual transaction. In the Orders API, cancellation operates directly on the order via order_id, without depending on the point of sale in the path. The response changed from empty (HTTP 204) to the complete order object with status: "canceled" (HTTP 200).

The Orders API introduces the dedicated endpoint POST /v1/orders/{order_id}/refundAPI for refunds, which did not exist in the Instore Orders API. Previously, it was necessary to receive the payment webhook, obtain the payment_id, and execute the refund through the Payments API separately. Now, the refund is performed directly on the order.

curl
Copiar
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}'

After applying the changes, verify that the integration works correctly across all flows before going to production.

See the documentation to learn how to test the integration.