Skip to content

Integrating Mercado Pago

Auth: OAuth 2.0 · Partner program: not required · Setup time: about 10 minutes · Last verified: 2026-05-15

LatAm-focused payments + wallet (subsidiary of MercadoLibre). Primary in AR, BR, MX, CL, CO, UY.

Long-lived access token (api_key-style). OAuth (oauth2) is also supported for marketplace integrations but the access-token path is the canonical operator path.

  1. Sign in at https://www.mercadopago.com/developers/panel.
  2. Your applications → Credentials, copy either the test or production access token.
  3. Open /platforms → Payments → Mercado Pago → Configure and submit:
    • accessToken

Configure under Notifications → Webhooks. Point at https://${PUBLIC_BASE_URL}/webhooks/mercado-pago and subscribe to:

  • payment
  • subscription_preapproval, subscription_authorized_payment
  • chargebacks
  • merchant_order

Mercado Pago signs deliveries with x-signature (HMAC-SHA-256 of <id>;<timestamp> with the secret).

  • Decimal money. transaction_amount is a float in major units; the adapter multiplies by 100 and rounds.
  • Status set is large. approved / pending / in_process / authorized / in_mediation / rejected / cancelled / refunded / charged_back. The adapter folds them into the canonical ChargeStatus.
  • Subscriptions are called “preapprovals” at the API layer. The adapter does not normalise the full preapproval lifecycle; fetching by ID returns the raw record.
  • Country-scoped currencies. A single MP account is typically scoped to one country and currency; multi-country setups need one connection per country.