Create a preference server-side: POST /checkout/preferences with 'items' array (title, unit_price, quantity, currency_id), 'back_urls' (success, failure, pending), and 'notification_url' for webhooks; authenticate with your access_token in the Authorization header.
Redirect the customer to 'init_point' from the response (or use 'sandbox_init_point' in test mode); MercadoPago hosts the full checkout UI with local payment methods (Pix, Boleto, PSE, etc.) appropriate to the buyer's country.
MercadoPago sends a webhook POST to your 'notification_url' with 'type' and 'data.id' in the JSON body; respond with HTTP 200 immediately.
Fetch the authoritative resource: for 'type=payment', call GET /v1/payments/{id} using your access_token; for 'type=merchant_order', call GET /merchant_orders/{id}.
Check 'status' on the payment object: 'approved' means captured; 'pending' or 'in_process' means waiting (common for Boleto/offline methods that can take days); 'rejected' or 'cancelled' require action.
Validate the webhook by checking the 'x-signature' header: MercadoPago sends a HMAC-SHA256 signature of a specific string composed of the query parameters; verify using your webhook secret from the dashboard.
Known gotchas
Offline payment methods like Boleto Bancário (Brazil) and cash payments (OXXO in Mexico) have multi-day settlement windows — fulfilling orders immediately after preference creation, before 'approved' status, leads to fraud exposure.
MercadoPago uses separate credentials per country (Brazil, Argentina, Mexico, etc.) — a credential issued for Brazil will not work for transactions in Argentina; ensure you select the correct country in your application settings.
The 'pending' status is a legitimate terminal state for some payment methods while awaiting customer action; do not treat 'pending' as equivalent to 'failed' when cancelling orders.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp