Integration model
Checkout API now processes payments with Orders. This API is designed to simplify your development with Mercado Pago: with a single integration, you can access various payment solutions.
Additionally, the API makes the integration code more intuitive and provides more detailed error messages, streamlining the development process.
Differences in processing
Previously, payments via Checkout API were processed exclusively through the Payments API. Now, it is also possible to process them through Orders, which offers an efficient and straightforward integration alternative.
Below are the main differences between the two options.
| Feature | Payments API | Orders API |
| Payment processing | Automatic (create and process your transaction). | Automatic and manual (choosing when to process your transaction). |
| Transactions | One transaction per request. | Multiple transactions per request. |
| Operations | Online payments. | Online payments and In-person payments (Mercado Pago Point). |
| Notifications | Advanced setup via notification_url. | Simpler setup available in the Notifications section under Your integrations. |
| Error validation | Returns one error at a time. | Returns a list of all errors in the request. |
Processing modes for Orders
An online payment order can be created to be processed in two modes: Automatic mode and Manual mode.
The definition of the processing mode will be done at the time of creating the order, using the processing_mode parameter. Its value should be automatic for automatic processing, or manual to process the order manually. See below the characteristics of each mode.
capture_mode parameter indicates how the order will be processed and defines whether the creation response will have a final or intermediate status. It only applies when processing_mode is automatic. In manual mode, it defines whether the previously authorized amount will need to be captured later. For more details, see the API ReferenceAPI.The automatic mode is the default mode of the application. Through it, the transaction is completed in a single step and modifications are limited. It is suitable for scenarios where all information needed to complete the transaction is already available at order creation time, including buyer data, items, and payment method information properly tokenized.
In this flow, all information is sent in a single request, and the API is responsible for orchestrating communication with the processing layers. The status returned in the order creation response will depend on the capture_mode parameter configuration.
To create the order in automatic mode, set the processing_mode field, which defines the creation and processing format of the transaction, to automatic. In the transactions object, the payments node must contain the complete payment_method object, including the card token generated via SDK or API, as shown in the example below:
The API returns the order object with the transaction status already updated (for example, processed or accredited):
json
{ "id": "01JC1KVZ0WJY8Y4WA7MZAD5S2T", "status": "processed", "status_detail": "accredited", "transactions": { "payments": [ { "id": "pay_01JC1KVZ0WJY8Y4WA7MZG3A8F2", "status": "processed", "status_detail": "accredited", "payment_method": { "id": "master", "type": "credit_card", "installments": 12 } } ] } }
The allowed operations are:
- Create and process orderAPI: responsible for creating the order and simultaneously processing the transaction.
- Get orderAPI: allows you to obtain information about an order, including its status in real time.
- Search orderAPI: allows you to search orders in a massive way using various filters and pagination information.
- Capture orderAPI: enables the capture of the authorized amount of an order. This option is only valid for credit cards.
- Cancel orderAPI: responsible for canceling an existing order that has not yet been processed/finalized.
- Refund orderAPI: allows the total or partial refund of a payment. The order will be fully refunded if all transactions are refunded completely.
- Total refund: the value to be refunded should not be indicated in the request’s
body, that must be empty. - Partial refund: the amount to be refunded must be specified in the request’s
bodyalong with de transaction ID. All other transactions will remain as they are, and only the modified transaction will be refunded.
- Total refund: the value to be refunded should not be indicated in the request’s