Mercado Pago Checkout Pro — setup and reference

Module and release scope

This guide covers Mercado Pago Checkout Pro 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Environment	select	Yes	Default: "sandbox" Choices: sandbox = Test users and credentials, live = Live
access_token — Access token	secret	Yes	Use the account-specific value described below.
collector_id — Collector / seller user ID	text	Yes	Use the account-specific value described below.
site_id — Merchant marketplace	select	Yes	Default: "MLB" Choices: MLB = Brazil, MLA = Argentina, MLM = Mexico, MCO = Colombia, MPE = Peru, MLU = Uruguay
webhook_secret — Webhooks secret signature	secret	Yes	Use the account-specific value described below.
currencies — Enabled invoice currency	text	Yes	Default: "BRL" Use the currency of this seller marketplace. CLP is excluded because this billing core uses two-decimal money.

This module uses Checkout Pro via the Preferences API, with authenticated Payment API verification. Supported merchant sites: Brazil/BRL, Argentina/ARS, Mexico/MXN, Colombia/COP, Peru/PEN and Uruguay/UYU. Chile/CLP is excluded because the billing core currently uses two-decimal money. Choose one seller marketplace and its matching invoice currency; no currency conversion occurs.

1. Create an application in Mercado Pago Developers. Obtain the seller access token, seller/collector user ID and marketplace ID. For sandbox use the provider's test credentials and test users in that marketplace.
2. Configure Webhooks for the payment topic using the exact callback URL displayed by EmailaBiller. Save its secret signature here. Leave legacy unsigned IPN disabled.
3. Test performs GET /users/me and verifies collector and marketplace.
4. Create a sandbox invoice checkout. The returned sandbox hosted URL is used in test mode; live uses the marketplace production URL.

A signed notification is only a locator: the module validates x-signature, x-request-id and the literal data.id query parameter, then retrieves the payment. Payment must be approved and captured, have no refund, match the collector and environment, and retain the original invoice binding. Browser returns also verify the original preference. Staff reconciliation searches by original reference with a strict result bound and requires a unique approved payment. Pending installments, authorization, rejection, refunds and chargebacks never count as new settlement.

Official references: Checkout Pro Preferences API, Webhooks, Get payment.

Install this signed package under System → Payment gateways → Install module. New installations are disabled. Create a separate connection, enter your own merchant credentials, run Test, and explicitly enable that connection after completing sandbox checkout and callback testing. No merchant credentials or business settings are included in this package.

The module uses verified HTTPS with fixed official provider endpoints, no redirects or automatic API retries, bounded uncompressed responses, exact two-decimal invoice accounting, and credential-safe errors. Network timeouts leave payment under review: inspect the provider before retrying. Provider methods depend on merchant approval, payer location, currency and device; installing this module does not promise every payment method. The module never collects card numbers, expiry dates or CVV.