How to migrate from the Dynamic QR Model API to the Orders API

The Orders API unifies payment processing with QR Code in Mercado Pago, consolidating the two creation methods of the Dynamic QR Model API into a single endpoint and extending query and cancellation resources to both modes. In addition, all new Mercado Pago features will be developed on the Orders API.

The Dynamic QR Model API had two creation methods with distinct behaviors:

• POST /qrs, dynamic QR mode: creates an order and returns a unique QR string per transaction in the qr_data field, without associating it with any checkout. The application is responsible for converting qr_data into a QR Code and displaying it to the customer.
• PUT /qrs, hybrid QR mode: creates an order, associates it with the checkout identified by {external_pos_id}, updating the linked static QR, and also returns the dynamic QR in the qr_data field.

The Orders API unifies these two methods into a single endpoint POST /v1/ordersAPI, differentiating behavior via the config.qr.mode parameter: the dynamic value corresponds to the legacy POST flow and the hybrid value corresponds to the legacy PUT flow.

This distinction also affected query and cancellation resources, which were available in the Dynamic QR Model API only for the PUT flow. In the Orders API, these resources become available for both flows via order_id.

To migrate your integration from the Dynamic QR Model API to the Orders API, follow the steps below.

Before starting the migration steps, review the table below for an overview of all endpoint changes. The Orders API unifies the two creation methods into a single POST /v1/ordersAPI and extends query and cancellation resources to both modes.

One of the most significant changes between the Dynamic QR Model API and the Orders API is the status model. In the Dynamic QR Model API, the state of a transaction was determined by monitoring notifications from two independent topics , payments and merchant_orders, with different fields and values for each. The Orders API unifies this behavior into a single status field on 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.

Regarding notifications, in the Legacy API they could be configured via the notification_url field in the request body (IPN model) or via webhooks with the payments and merchant_orders topics. In the Orders API, the notification_url field does not exist and the payments and merchant_orders topics are not compatible. Configure notifications in Your integrations, subscribing to the "Order (Mercado Pago)" (orders) topic, before going to production. For more information, see the notifications documentation.

The Orders API introduces a mandatory header change that affects all endpoints. The Access Token must be sent via the Authorization header. Apply the following change before testing any other resource.

The Orders API unifies the two creation methods into a single POST /v1/ordersAPI, differentiating behavior via the config.qr.mode parameter. The POST /qrs endpoint, dynamic QR mode, is equivalent to config.qr.mode: dynamic, and the PUT /qrs endpoint, hybrid QR mode, is equivalent to config.qr.mode: hybrid. In both cases, {user_id} is no longer a path parameter, {external_pos_id} moves to the body, and the type: "qr" field becomes required. Follow the steps below to adapt the request, the response, and error handling for each mode.

The GET /v1/orders/{order_id}API query endpoint is available for both dynamic and hybrid modes in the Orders API. In the Dynamic QR Model API, queries were available only for the PUT flow and queried by checkout, not by order. The POST flow had no query endpoint. State was obtained exclusively via payments and merchant_orders notifications.

The Orders API allows querying the complete order state directly by order_id, 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 POST /v1/orders/{order_id}/cancelAPI cancellation endpoint is available for both modes in the Orders API. In the Dynamic QR Model API, cancellation was available only for the PUT flow and canceled the order associated with the checkout via DELETE. The POST flow had no cancellation endpoint.

The HTTP method changes from DELETE to POST, {user_id} and {external_pos_id} are removed from the path, and the operation now identifies the order by order_id. The response changed from empty (HTTP 204) to the full order object with status: "canceled" (HTTP 200).

The Orders API introduces the dedicated POST /v1/orders/{order_id}/refundAPI endpoint for refunds, which did not exist in the Dynamic QR Model API in either flow. 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, for both modes.

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 operates correctly across all flows before going to production.

See the documentation to learn how to test the integration.