How to migrate from the Payments API to the Orders API

The Payments API continues to work normally after the launch of the Orders API. Mercado Pago has not deactivated this API; it has simply stopped adding new features to it, while maintaining security and stability fixes. Technically, both APIs can remain active at the same time, each processing part of your volume.

We recommend the following strategy:

• Migrate by payment method, not all at once. Move cards to the Orders API first, then migrate the remaining payment methods one at a time after validating stability.
• Split traffic in your own checkout. Because each API uses independent endpoints, credentials, and idempotency keys, it is safe to route part of new transactions to /v1/ordersPOST and the rest to /v1/paymentsPOST.
• Handle notifications separately. Configure the Webhook to listen to the orders and payment topics in parallel during the transition, routing each payload to the appropriate handler. Disable payment only after migrating new traffic and monitoring outstanding Payments API transactions and notifications.
• Define how to interrupt the migration. If you need to return to the Payments API, redirect only new transactions. Existing transactions must continue to be retrieved, captured, canceled, or refunded through the API in which they were processed, because they cannot and do not need to be transferred from one API to the other.
• Monitor the approval rate and integration quality separately for each API during coexistence, as a criterion for deciding when to stop sending traffic to the Payments API.

Before starting the migration, confirm that all the payment methods in your integration already have an equivalent in the Orders API.

In addition to payment method availability, check whether your integration uses Marketplace or Split Payments 1:1. In the Payments API, these integrations withhold commissions through application_fee; the Orders API does not yet have a documented equivalent field for this mechanism. Treat this as a blocker before migrating the flow.

In the Payments API, each operation used its own resource under /v1/payments/{id}. The Orders API consolidates most of these operations into subresources of the same /v1/orders/{order_id} and introduces dedicated endpoints that were not available before: explicit capture; adding, removing, and updating transactions; and manual-mode processing.

The Authorization header is required in both APIs and does not change. The main change is that the idempotency header becomes mandatory for almost all write operations.

In the Payments API, status and status_detail exist at a single level. In the Orders API, the same concept exists at two levels: the order status, as a consolidated view, and the status of each transaction in transactions.payments[]. This distinction becomes essential when an order has more than one transaction.

The creation endpoint changes from /v1/paymentsPOST to /v1/ordersPOST. In addition to the URL, the request structure has been reorganized: the amount and payment method move into the transactions.payments[] node, an array that allows multiple transactions per order. The type field, with the fixed value online, and the config node are introduced without direct equivalents in the legacy API.

The following table maps the main fields in the creation response between the two APIs.

The Payments API returns one error at a time, the first one found. The Orders API returns a list with all request validation errors in a single response, making corrections faster.

The retrieval endpoint changes from /v1/payments/{id}GET to /v1/orders/{id}GET. The response includes the complete order object, including all associated transactions, their refunds, and any chargebacks—information that required separate queries in the legacy API.

Retrieval errors

The search endpoint changes from /v1/payments/searchGET to /v1/orders/searchGET, with restructured filters and pagination. Date ranges become required, and pagination uses page and page_size instead of offset and limit.

The amount reservation changes from a boolean field (capture) to a capture mode configured when creating the order (capture_mode), combined with a dedicated capture endpoint.

As in the Payments API, you can cancel an order before payment is completed or refund it, fully or partially, after approval. See below how each flow changes in the Orders API.

The Customers API endpoints are used by both the Payments API and the Orders API and do not change structure during migration. Only the way a saved card is used for a new charge changes, because the payment is now created as an order.

What changes when paying with a saved card:

In the Payments API, marketplace integrations use OAuth to obtain the connected seller's Access Token and send the application_fee field, with the amount withheld by the integrator, in the payment creation body.

3D Secure 2.0 authentication changes from a simple field to a dedicated configuration node at config.online.transaction_security, with explicit control over chargeback liability.

Possible statuses after the 3DS flow in the Orders API:

The HMAC-SHA256 signature and validation mechanism is identical in both APIs. What changes is the notification topic and where it is configured.

The chargeback retrieval endpoint /v1/chargebacks/{id}GET is identical in both APIs. The difference is in the notification event and the new fields exposed directly in the order.

The resolution fields are identical in both APIs.

Fraud prevention best practices remain conceptually the same. What changes is where additional data is sent in the request body.

The use of test credentials, users, and cards follows the same approach. The main difference is the email required for the payer and the table of cardholder names used to simulate each scenario.

The Orders API evaluation considers the following aspects to measure the quality of the migrated integration.

Before going to production, confirm the following:

• Activate production credentials in Your integrations.
• Replace the test Public Key and Access Token with their production versions.
• Implement an SSL/HTTPS certificate, which is required in production.
• Reconfigure the Webhook for the orders topic. Disable the payment topic only after migrating new traffic and completing monitoring of outstanding Payments API transactions and notifications.
• Ensure that all status and status_detail values are handled at both the order and transaction levels.

After applying the changes, verify that the integration works correctly in all flows before going to production. Use the checkboxes below to confirm each point.

Required validations

Validations based on your flow

Validations for flows that do not yet have an equivalent