API Reference - Mercado Pago Developers

AI resources

Checkout Pro Checkout Pro redirects the buyer to a Mercado Pago environment to complete the payment. You can integrate it using the Orders API (modern flow) or the Preferences API (classic flow). This reference describes the available endpoints and how to interact with them. Looking for integration steps? Go to Checkout Pro via Orders documentation or Classic Checkout Pro.

Which integration path should you use? Choose based on your use case.

Via Orders API (Recommended)

Simplified flow with a single endpoint
Direct checkout_url to redirect the buyer
New features and simplified notifications

Via Preferences API (Legacy)

Preference-based flow with init_point
Compatible with existing integrations

This integration path is not recommended. The Preferences API will continue to be supported, but new features will only be available in the Orders API. If you are starting a new integration, use the Orders API. If you already have a Preferences integration, check the Checkout Pro via Orders documentation to plan your migration.

Available endpoints

All endpoints that make up the Checkout Pro integration via Preferences.

Preferences

The preference is the central object of the classic Checkout Pro flow. It defines the items, amounts, enabled payment methods, and the buyer's return URLs.

Operation	Path	Description
Create preferencePOST	`/checkout/preferences`	Creates a preference with items, prices, and `back_urls`; returns the `init_point` to redirect the buyer.
Search preferencesGET	`/checkout/preferences/search`	Searches preferences by filters such as `external_reference` or date; returns paginated results.
Get preferenceGET	`/checkout/preferences/{id}`	Returns the detail of a preference: `init_point`, items, and configured `back_urls`.
Update preferencePUT	`/checkout/preferences/{id}`	Updates an existing preference before the buyer completes the payment.

Payments

Read-only endpoints to verify the status of a payment after receiving the webhook notification or the return redirect.

Operation	Path	Description
Search paymentsGET	`/v1/payments/search`	Searches payments by filters such as `external_reference`, status, or date; returns paginated results.
Get paymentGET	`/v1/payments/{id}`	Returns the status and detail of the payment, including `status_detail`, to confirm the result after the notification.

Payment methods

Operation	Path	Description
Get payment methodsGET	`/v1/payment_methods`	Lists the payment methods available for the site, to include or exclude them in the preference.

Shipping

Operation	Path	Description
Calculate shipping ratesPOST	`/shipping/v1/shipments-rates`	Calculates the available shipping rates for a set of items and destination address.
Create shipmentPOST	`/shipping/v1/shipments`	Creates a shipment associated with a preference; returns the shipment identifier.
Get shipmentGET	`/shipping/v1/shipments`	Returns the detail and status of an existing shipment.
Cancel shipmentDELETE	`/shipping/v1/shipments/{id}`	Cancels a shipment before it is dispatched.
Get shipment labelGET	`/shipping/v1/shipments/{id}/packages/{packageId}/label`	Returns the shipment label in PDF format to print and attach to the package.
Track shipmentGET	`/shipping/v1/shipments-tracking/{tracking_number}`	Returns the tracking status of a shipment by its tracking number.

Chargebacks

Operation	Path	Description
Get chargebackGET	`/v1/chargebacks/{id}`	Retrieves a chargeback case by its ID returned in the body of the notification configured for chargebacks. Returns the chargeback details, including the dispute status, affected amount, and response deadline.
Search chargebacksGET	`/v1/chargebacks/search`	Searches all chargebacks for a payment by its "payment_id" returned in the body of the notification configured for chargebacks. The search returns paginated results with the detail of each case.
Upload supporting documentationPOST	`/v1/chargebacks/{id}/documentation`	Uploads evidence files to dispute a chargeback while its status ("documentation_status") is "pending".
Get supporting documentation fileGET	`/v1/chargebacks/documentation/{type}/{uuid}`	Downloads or renders inline a documentation file uploaded for a chargeback case.