Mercadopago

Mercado Pago API

The MercadoPago REST API. Please see https://www.mercadopago.com/developers for more details.

Payments#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The MercadoPago REST API. Please see https://www.mercadopago.com/developers for more details.

Endpoints 142

OAuth

  • POSTCreate OAuth token/oauth/tokenExchanges authorization codes for access tokens, refreshes expired tokens, or requests client credentials tokens for machine-to-machine flows. Security notes:…

Preferences

  • POSTCreate a preference/checkout/preferencesCreates a Checkout Pro preference. The response contains init_point (production) and Webhook events triggered: payment, merchant_order
  • GETGet preference by ID/checkout/preferences/:id
  • PUTUpdate a preference/checkout/preferences/:id
  • GETSearch preferences/checkout/preferences/search

Payments

  • POSTCreate a payment/v1/paymentsCreates a payment. For card payments, generate a card token client-side via MercadoPago.js before calling this endpoint. For cash/offline methods (Boleto,…
  • GETGet payment by ID/v1/payments/:id
  • PUTUpdate or capture a payment/v1/payments/:idUpdate payment fields or capture an authorized payment. To capture an authorized two-step payment: send {"capture": true}. To cancel an authorized payment:…
  • GETSearch payments/v1/payments/search?sort=string&criteria=asc

Orders

  • GETSearch orders/v1/orders?begin_date=2024-01-01T00:00:00Z&end_date=2024-01-01T00:00:00ZSearch for orders using date range and optional filters. begin_date and end_date are required.
  • POSTCreate an order/v1/ordersCreates an Order for processing payment transactions. Supports automatic (single-stage, set processing_mode=automatic) and manual (multi-stage, set…
  • GETGet order by ID/v1/orders/:idReturns all order information for the given order ID.
  • POSTCancel an order/v1/orders/:order_id/cancelCancels an order and all its transactions. Only orders with status=action_required or status=created can be canceled.
  • POSTProcess an order/v1/orders/:order_id/processTriggers processing of an order and all its transactions. Only available for manual-mode orders (processing_mode=manual). After calling this endpoint the…
  • POSTCapture an authorized order/v1/orders/:order_id/captureFully captures a previously authorized order (capture_mode=manual). All associated authorized transactions are captured in full.
  • POSTRefund an order/v1/orders/:order_id/refundPerforms a full or partial refund of transactions associated with an order. For a full refund, send an empty request body (omit transactions). For a partial…
  • PUTUpdate a transaction on an order/v1/orders/:order_id/transactions/:transaction_idUpdates the payment method of a pending transaction on a manual-mode order.
  • DELETEDelete a transaction from an order/v1/orders/:order_id/transactions/:transaction_idRemoves a transaction from a manual-mode order. Only available before processing.
  • POSTAdd a transaction to an order/v1/orders/:order_id/transactionsAdds a payment transaction to an order. Only available when processing_mode=manual. The order must be in status=created.

Merchant Orders

  • POSTCreate a merchant order/merchant_ordersWebhook events triggered: merchant_order
  • GETGet merchant order/merchant_orders/:id
  • PUTUpdate merchant order/merchant_orders/:id
  • GETSearch merchant orders/merchant_orders/search

Customers

  • POSTCreate a customer/v1/customersCreates a customer profile for storing payment methods. The customer email is unique per account.
  • GETSearch customers/v1/customers/search
  • GETGet customer by ID/v1/customers/:id
  • PUTUpdate a customer/v1/customers/:id
  • DELETEDelete a customer/v1/customers/:id/deletePermanently deletes a customer profile. This action cannot be undone. Saved cards associated with the customer will also be removed.

Cards

  • GETList customer cards/v1/customers/:customer_id/cards
  • POSTSave a card to a customer/v1/customers/:customer_id/cardsSaves a tokenized card to a customer profile for future payments. The token must be created client-side via MercadoPago.js. Raw card data must never pass…
  • GETGet a saved card/v1/customers/:customer_id/cards/:id
  • PUTUpdate a saved card/v1/customers/:customer_id/cards/:id
  • DELETEDelete a saved card/v1/customers/:customer_id/cards/:id
  • POSTCreate a card token (client-side only)/v1/card_tokensCLIENT-SIDE ONLY. Creates a single-use card token from raw card data. Call this from your frontend using MercadoPago.js with the PUBLIC_KEY. Never call this…
  • GETGet a card token/v1/card_tokens/:idPCI scope: Handling this endpoint brings your integration into PCI DSS scope.

Addresses

  • GETList customer addresses/v1/customers/:customer_id/addresses
  • POSTCreate a customer address/v1/customers/:customer_id/addressesAdds a shipping or billing address to a customer profile.
  • GETGet a customer address/v1/customers/:customer_id/addresses/:address_id
  • PUTUpdate a customer address/v1/customers/:customer_id/addresses/:address_id
  • DELETEDelete a customer address/v1/customers/:customer_id/addresses/:address_id

Payment Methods

  • GETList available payment methods/v1/payment_methodsReturns all payment methods available for the credential's site_id. Use this to build payment method selectors and validate method availability before…
  • GETGet installment options/v1/payment_methods/installments?payment_method_id=visa&amount=1000.0Returns available installment plans for a given card BIN, amount, and site. Use this to populate installment selectors in your checkout.

Identification Types

  • GETList identification types/v1/identification_typesReturns valid ID document types for the credential's site_id. Examples: CPF/CNPJ (Brazil), DNI/CUIL/CUIT (Argentina), RFC/CURP (Mexico). Use this to populate…

Cancellations & Refunds

  • GETList refunds for a payment/v1/payments/:id/refunds
  • POSTCreate a refund/v1/payments/:id/refundsCreates a full or partial refund for an approved payment. Omit the amount field for a full refund. Partial refunds are supported; multiple partials are…
  • GETGet a specific refund/v1/payments/:id/refunds/:refund_id
  • PUTCancel a payment/v1/payments/:id/cancellationsCancels a payment that is in pending or authorized status. Only payments that have not yet been captured or processed can be cancelled. For approved payments…

Chargebacks

  • GETGet chargeback by ID/v1/chargebacks/:id
  • PUTUpload chargeback documentation/v1/chargebacks/:id

Subscriptions

  • POSTCreate a subscription/preapproval
  • GETGet subscription/preapproval/:id
  • PUTUpdate subscription/preapproval/:idUpdate subscription status or billing details. Common use: {"status": "paused"} to pause, {"status": "authorized"} to resume, {"status": "cancelled"} to cancel.
  • GETSearch subscriptions/preapproval/search
  • GETExport subscriptions/preapproval/export?collector_id=0Exports a list of subscriptions for a collector as a downloadable file. Filter by plan ID, status, and sort order.

Plans

  • POSTCreate a subscription plan/preapproval_planCreates a recurring billing plan. Individual subscriptions reference this plan. The response includes init_point to send subscribers to authorize billing.
  • GETGet subscription plan/preapproval_plan/:id
  • PUTUpdate a subscription plan/preapproval_plan/:id
  • GETSearch subscription plans/preapproval_plan/search

Invoices

  • GETGet subscription invoice/authorized_payments/:id
  • GETSearch subscription invoices/authorized_paymentsSearch billing invoices generated by subscriptions.

Wallet Connect

  • POSTCreate a Wallet Connect agreement/v2/wallet_connect/agreementsCreates an authorization agreement for Wallet Connect. Returns an agreement token to redirect the payer to MP for wallet authorization. Available in:…
  • GETGet a Wallet Connect agreement/v2/wallet_connect/agreements/:agreement_idAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • DELETERevoke a Wallet Connect agreement/v2/wallet_connect/agreements/:agreement_idAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • POSTCreate a payer token from agreement/v2/wallet_connect/agreements/:agreement_id/payer_tokenAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • POSTCreate an advanced payment/v1/advanced_paymentsCreates a Wallet Connect advanced payment (marketplace split payment). Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • GETGet an advanced payment/v1/advanced_payments/:advanced_payment_idAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • PUTCapture or cancel an advanced payment/v1/advanced_payments/:advanced_payment_idCapture (capture=true) or cancel (status=cancelled). Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • POSTCreate a discount promise/v2/wallet_connect/discountsValidates a coupon and returns discount amount and legal terms. Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • POSTValidate a coupon/v2/wallet_connect/couponsChecks coupon status and returns description and legal terms. Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM)

Stores

  • POSTCreate a store/users/:user_id/stores
  • GETGet store by ID/stores/:id
  • GETSearch stores/users/:user_id/stores/search
  • PUTUpdate a store/users/:user_id/stores/:id
  • DELETEDelete a store/users/:user_id/stores/:id

POS

  • GETSearch points of sale/pos
  • POSTCreate a point of sale/posCreates a point of sale in a store to receive payments for products or services. Each POS will have a unique QR code linked to it.
  • GETGet a point of sale/pos/:id
  • PUTUpdate a point of sale/pos/:id
  • DELETEDelete a point of sale/pos/:id
  • GETList POS devices for a user/users/:user_id/pos

Terminals

  • POSTCreate a refund intent on a terminal/point/integration-api/devices/:deviceid/refundInitiates a refund intent on a Point terminal device.
  • DELETECancel a refund intent on a terminal/point/integration-api/devices/:deviceid/refund/:refundintentid
  • GETGet a refund intent status/point/integration-api/refund/:refundintentid
  • GETGet list of terminals/terminals/v1/listReturns all Point hardware terminals registered to the account. Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • PATCHUpdate terminal operation mode/terminals/v1/setupChanges the operating mode of one or more terminals. PDV — integrated POS mode (connected to your system); STANDALONE — independent mode (no system…
  • POSTCreate a terminal print action/terminals/v1/actionsSends a print action to a Point terminal — either a receipt image or a DTE (electronic tax document, available in Chile/MLC only). Set type to PRINT_INFO for…
  • GETGet terminal action status/terminals/v1/actions/:action_idAvailable in: Argentina, Brazil, Chile, Mexico (MLA, MLB, MLC, MLM)
  • POSTCancel a terminal action/terminals/v1/actions/:action_id/cancelAvailable in: Argentina, Brazil, Chile, Mexico (MLA, MLB, MLC, MLM)

Point Deprecated

  • GETList Point devices/point/integration-api/devicesAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • POSTCreate a payment intent on a Point device/point/integration-api/devices/:deviceid/payment-intentsCreates a payment intent that is sent to a Point POS device for the customer to tap/insert their card. The device handles card capture. Available in:…
  • DELETECancel a payment intent/point/integration-api/devices/:deviceid/payment-intents/:paymentintentidAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)
  • GETGet payment intent details/point/integration-api/payment-intents/:paymentintentidAvailable in: Argentina, Brazil, Mexico (MLA, MLB, MLM)

QR Orders

  • POSTConfirm QR cashout status/instore/orders/:merchant_order_id/confirmationConfirms the cashout status for a QR-based cash withdrawal order. Available in: Argentina, Brazil (MLA, MLB)

QR Integrator

  • GETGet QR integrator configuration/instore/integrator
  • PATCHCreate or update QR integrator configuration/instore/integratorConfigures the integrator settings for QR in-store payments.

QR Deprecated

  • GETGet in-store order (deprecated V2)/instore/qr/seller/collectors/:user_id/pos/:external_pos_id/ordersDeprecated. Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order
  • DELETEDelete in-store order (deprecated V2)/instore/qr/seller/collectors/:user_id/pos/:external_pos_id/ordersDeprecated. Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order
  • PUTCreate in-store order (deprecated V1)/mpmobile/instore/qr/:user_id/:external_idDeprecated. Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order
  • DELETEDelete in-store order (deprecated V1)/mpmobile/instore/qr/:user_id/:external_idDeprecated. Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order
  • PUTCreate in-store order (deprecated V2)/instore/qr/seller/collectors/:user_id/stores/:external_store_id/pos/:external_pos_id/ordersDeprecated. Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order
  • PUTCreate dynamic QR order (deprecated)/instore/orders/qr/seller/collectors/:user_id/pos/:external_pos_id/qrsDeprecated. Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM) Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order
  • POSTCreate a QR trama (deprecated Dynamic QR)/instore/orders/qr/seller/collectors/:user_id/pos/:external_pos_id/qrsDeprecated. Available in: Argentina, Brazil, Mexico (MLA, MLB, MLM) Migration guide: https://www.mercadopago.com/developers/en/docs/qr-code/orders/create-order

Claims

  • GETGet claim details/post-purchase/v1/claims/:claim_idReturns full details of a post-sale claim including status, stage, and players.
  • GETSearch claims/post-purchase/v1/claims/search
  • GETGet claim reason/post-purchase/v1/claims/reasons/:reason_idReturns the description and metadata for a specific claim reason code.
  • GETGet claim status history/post-purchase/v1/claims/:claim_id/status_history
  • GETGet claim evidence/post-purchase/v1/claims/:claim_id/evidences

Claim Messages

  • GETGet claim messages/post-purchase/v1/claims/:claim_id/messages
  • POSTSend a message in a claim/post-purchase/v1/claims/:claim_id/actions/send-messageSends a text message (with optional attachments) in the claim thread.
  • POSTAttach a file to a claim message/post-purchase/v1/claims/:claim_id/attachmentsUploads and attaches a file (image, PDF) to a claim. Supported formats: JPEG, PNG, PDF. Max size: 10 MB.
  • GETGet attached file metadata/post-purchase/v1/claims/:claim_id/attachments/:fileName
  • GETDownload an attached file/post-purchase/v1/claims/:claim_id/attachments/:fileName/download

Claim Resolutions

  • POSTRequest claim mediation/post-purchase/v1/claims/:claim_id/actions/open-disputeEscalates a claim to mediation, requesting MP to intervene in the dispute.
  • GETGet expected mediation resolutions/post-purchase/v1/claims/:claim_id/expected-resolutionsReturns the possible resolution options for a claim at the mediation stage.

Claim Shipping

  • POSTUpload shipping evidence/post-purchase/v1/claims/:claim_id/actions/evidencesUploads shipping evidence (tracking code, proof of delivery) to support the seller's case in a claim. Accepted as part of the claims resolution process.

Releases Report

  • GETGet releases report configuration/v1/account/release_report/config
  • PUTUpdate releases report configuration/v1/account/release_report/config
  • POSTCreate releases report configuration/v1/account/release_report/configCreates the configuration for automatic releases report generation. Defines columns, schedule frequency, file format, and optional SFTP delivery.
  • GETGet releases report list/v1/account/release_report
  • POSTCreate a releases report/v1/account/release_reportGenerates a one-time releases report for the specified date range. Returns a task ID to poll for completion via the task endpoint.
  • GETSearch releases reports/v1/account/release_report/search
  • GETGet releases report task status/v1/account/release_report/task/:task_idPolls the status of a report generation task. Check until status=done.
  • POSTEnable automatic releases report generation/v1/account/release_report/scheduleEnables scheduled report generation based on the configured frequency.
  • DELETEDisable automatic releases report generation/v1/account/release_report/schedule
  • GETList scheduled releases reports/v1/account/release_report/list
  • GETDownload a releases report file/v1/account/release_report/:file_nameDownloads the generated report CSV file by filename.

Settlements Report

  • GETGet settlements report configuration/v1/account/settlement_report/config
  • PUTUpdate settlements report configuration/v1/account/settlement_report/config
  • POSTCreate settlements report configuration/v1/account/settlement_report/configCreates the configuration for automatic all-transactions (settlements) report generation. Defines columns, schedule frequency, file format, and optional SFTP…
  • GETGet settlements report list/v1/account/settlement_report
  • POSTCreate a settlements report/v1/account/settlement_reportGenerates a one-time all-transactions report for the specified date range. Returns a task ID to poll for completion.
  • GETSearch settlements reports/v1/account/settlement_report/search
  • GETGet settlements report task status/v1/account/settlement_report/task/:task_id
  • POSTEnable automatic settlements report generation/v1/account/settlement_report/schedule
  • DELETEDisable automatic settlements report generation/v1/account/settlement_report/schedule
  • GETList scheduled settlements reports/v1/account/settlement_report/list
  • GETDownload a settlements report file/v1/account/settlement_report/:file_name

Payouts

  • POSTCreate a batch of payout transactions/v1/payoutsAvailable in: Argentina, Mexico (MLA, MLM)
  • GETList payout transactions/v1/payouts/:payout_id/transactionsAvailable in: Argentina, Mexico (MLA, MLM)
  • PUTCancel a payout transaction/v1/payouts/:payout_id/transactions/:transaction_id/cancelAvailable in: Argentina, Mexico (MLA, MLM)
  • POSTCreate a disbursement (Pix or bank transfer)/v1/transaction-intents/processCreates a Pix or bank transfer disbursement for Brazil. The payment_method_id determines the method: - pix — instant Pix transfer (available 24/7) -…
  • GETGet disbursement status/v1/transaction-intents/:idAvailable in: Brazil (MLB)

API details

Base URL
https://api.mercadopago.com
Authentication
A bearer token in the Authorization header
An API key in the X-Public-Key header
OAuth 2.0 (authorization code flow) with 3 scopes
Operations
142 operations on 108 pathsGET 65POST 42PUT 20DELETE 13PATCH 2
7 marked deprecated
Main resources
Releases Report 11Settlements Report 11Orders 10Wallet Connect 9Terminals 8Cards 7QR Deprecated 7POS 6Addresses 5Claim Messages 5
Response formats
application/json text/csv application/octet-stream
Description format
OpenAPI 3.1.0, API version 1.0.0

How to test the Mercado Pago API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Mercado Pago API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Create OAuth token” (POST /oauth/token), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Mercado Pago API?

The MercadoPago REST API. Please see https://www.mercadopago.com/developers for more details. It is listed under Payments and has 142 endpoints.

Who publishes the Mercado Pago API?

It is listed from Mercadopago's public API description (an OpenAPI document), not published by Mercadopago on Swastik Codes. Anyone who controls mercadopago.com.br can claim the profile by adding a DNS TXT record.

What is the base URL of the Mercado Pago API?

Requests go to https://api.mercadopago.com. Endpoint paths are added to this base URL.

How do I authenticate with the Mercado Pago API?

It accepts 3 methods: A bearer token in the Authorization header; an API key in the X-Public-Key header; OAuth 2.0 (authorization code flow) with 3 scopes.

How many endpoints does the Mercado Pago API have?

142 operations on 108 paths (65 GET, 42 POST, 20 PUT, 13 DELETE, 2 PATCH). The largest groups are Releases Report, Settlements Report, Orders, Wallet Connect.

Is forking the Mercado Pago API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.