Mercado Pago

You are building a Mercado Pago integration for [Django / Next.js / Laravel / Rails / Node.js / etc.]. Follow these rules exactly.

## Architecture
1. Use **Checkout Pro (redirect)** as the default — simplest PCI scope (SAQ-A), no card form on your servers. Use **Checkout Bricks** when you need an embedded UX with hosted card fields (still SAQ-A). Use **Checkout Transparent** only when Bricks doesn't fit your UX — it raises PCI scope.
2. Flow: server creates a Preference via `POST /checkout/preferences` with `items`, `payer`, `back_urls`, `notification_url`, `external_reference` → customer is redirected to `init_point` (or `sandbox_init_point` in test) → completes payment → Mercado Pago redirects back to your `back_urls.success` with `?status=&payment_id=&preference_id=&external_reference=` → **your server must call `GET /v1/payments/{payment_id}` with your access token before fulfilling the order**. Never trust the redirect query string — it isn't signed.
3. Subscribe to webhooks at `POST /mercadopago/webhook` for `payment`, `subscription_authorized_payment`, `subscription_preapproval`, `chargebacks`. The webhook is the source of truth for async events; the verify call is the source of truth for the synchronous redirect.

## Operating-country model — one account per country
Mercado Pago is a per-country product: separate dashboards (mercadopago.com.br vs .ar vs .mx vs .co vs .cl vs .pe vs .uy), separate access tokens, separate fee tables, slightly different features (Pix is BR-only, SPEI is MX-only, MSI installments are MX-only, Pix-na-credito is BR-only). If you operate across countries, store one set of credentials per country and select per the buyer/merchant context.

## Settlement term — pick deliberately
Card pricing varies materially by settlement term:
- Brazil: instant 4.98% / 30-day 3.98% (debit 1.99%; **Pix 0%**)
- Mexico: instant 3.49%+MXN 4 / 7-day 3.19%+MXN 4 / 30-day 2.95%+MXN 4 (SPEI free)
- Colombia: instant 3.29%+COP 800+IVA / 14-day 2.79%+COP 800+IVA
- Argentina: account-money 0.8%, cards up to 6.99% instant, with per-province variation from July 2025 due to Ingresos Brutos

Decide once per merchant context and document. Default to deferred when cash-flow allows — savings compound.

## Webhook security (do not skip)
1. Configure your webhook URL in the per-country Dashboard → Webhooks. Generate a Secret Key (per-app) and store it as `MERCADOPAGO_WEBHOOK_SECRET_{COUNTRY}`.
2. Verify the `x-signature` header. Format: `ts={timestamp},v1={hmac}`. Parse by splitting on `,` then `=`.
3. Build the manifest exactly: `id:{data.id};request-id:{x-request-id};ts:{ts};` — note the trailing semicolon and the use of `data.id` from the query string (not the body).
4. Compute `HMAC-SHA256(manifest, secret_key)` → hex. Compare to `v1` using constant-time compare (`hmac.compare_digest` / `crypto.timingSafeEqual`).
5. Reject (return 401) on mismatch. Return 200 within 22 seconds on success — Mercado Pago retries on 4xx/5xx. Queue heavy work (email, fulfilment) to a background job.
6. **Idempotency:** dedupe on `data.id` in a processed-events table. Always call `GET /v1/payments/{data.id}` with your access token to get the canonical status — never trust the webhook body's status field for fulfilment.
7. (Optional but recommended) IP-allowlist Mercado Pago's notification IPs from the per-country docs.

## Payment methods per country
- **Brazil**: enable Pix (0% fee, instant) — must register a Pix key in the dashboard before live Pix works. Boleto Bancário (async, 1–3 day settlement). Cards with parcelamento (installments).
- **Mexico**: SPEI (free, instant), OXXO/7-Eleven cash, MSI installments on cards.
- **Argentina**: cards with cuotas, Rapipago/Pago Fácil cash, account money.
- **Chile/Colombia/Peru/Uruguay**: cards, account money, local cash networks (Servipag, Efecty, PagoEfectivo, RedPagos), bank rails (PSE in CO).

Pass `payment_methods.excluded_payment_types` in the Preference if you want to constrain (e.g., online-only, no boleto).

## Secrets
- `MP_ACCESS_TOKEN_{COUNTRY}` server-side only — used for all REST calls, never expose to browser.
- `MP_PUBLIC_KEY_{COUNTRY}` client-only for SDK init / Bricks / Transparent tokenization.
- `MP_WEBHOOK_SECRET_{COUNTRY}` server-side only for x-signature verification.
- Use sandbox tokens (`TEST-*`) in development; production tokens (`APP_USR-*`) only in production. Never commit any of these.

## Subscriptions (recurring)
- Create a Pre-approval Plan via `POST /preapproval_plan` (frequency: month/week/day, free trial, amount).
- Direct customer to the plan's `init_point` to subscribe.
- Handle webhook events: `subscription_preapproval` (subscription state changes), `subscription_authorized_payment` (each renewal charge). Store `preapproval_id` on your subscription record.
- For card-on-file recurring without the plan flow, tokenize the card once via Bricks/Transparent, store the `card_token` (one-shot) and `card_id`, then create future charges via `POST /v1/payments` with `token` and `payer.id`.

## Marketplace / split payments (1:N)
1. Implement OAuth for seller onboarding: redirect sellers to `https://auth.mercadopago.com/authorization?client_id={app_id}&response_type=code&platform_id=mp&state={csrf}&redirect_uri={your_callback}`.
2. Exchange the `code` for an `access_token` per seller via `POST /oauth/token`. Store encrypted; refresh tokens are supported.
3. For each charge, use the seller's access_token (not your platform's) and pass `marketplace`, `marketplace_fee` to deduct your platform fee automatically.
4. Renew tokens before expiry; rotate on seller offboarding.

## Disputes / chargebacks
- Subscribe to `chargebacks` topic. You have **10 calendar days** to upload evidence after notification; issuer validation may take up to 130 days during which funds may be withheld.
- Page on-call when the event fires. Check `coverage_elegible` flag — eligible cases are covered by the Seller Protection Program.
- Build a single dispute-response template per common reason code; upload promptly.

## Reconciliation
- Store `payment_id`, `external_reference`, `transaction_amount`, `net_received_amount`, `status`, `status_detail`, and `date_approved` on your order.
- Use `external_reference` as your idempotency / order linkage key — pass it on the Preference.
- Pull settlement reports via the Reports API (or download from the Dashboard) and reconcile daily.

## Development workflow
- Use the official MCP Server (`@mercadopago/mcp-server`) in your IDE for webhook simulation, notifications-history diagnostics, and quality-validation prompts.
- Use the Prompt Library (mercadopago.com.{tld}/developers/en/prompt-library) for end-to-end Checkout Pro and webhook scaffolds.
- Use sandbox `init_point` for testing; the test card numbers per country are documented in the per-country test cards page.

## Error handling
- Treat 5xx and timeouts as retryable with exponential backoff (3 attempts, 1s/5s/30s).
- Treat 4xx (except 429) as non-retryable validation errors; surface to operator.
- Log every request with idempotency key + response status for audit.

## Account hygiene
- Mercado Pago's automated risk system can close accounts without human review — keep KYC current, avoid sudden 10x volume spikes without prior support contact, and have a backup gateway (PayPal Brasil/dLocal/EBANX/Stripe) wired in for business continuity.
- Enforce 2FA on all admin dashboard logins. Rotate API keys on staff departure.

Deliver a minimal working integration: Preference → redirect/Brick → server-side `GET /v1/payments/{id}` verify → x-signature webhook with manifest-format HMAC-SHA256 → idempotent fulfilment. Do not add features beyond those requested.