Mercado Pago API Pix: Integrate With Next.js

The Mercado Pago API Pix flow in a Next.js app needs three credentials (public key, access token, and webhook secret), one checkout preference created server-side, and a webhook listener that confirms approval. Redirect the buyer to Mercado Pago's hosted checkout, poll a pending-payment route when the buyer returns, and validate every webhook signature before trusting it.

How the Mercado Pago API Pix Integration Works in Next.js

The Mercado Pago API Pix integration in a Next.js app uses hosted Checkout Pro, three credentials, and a webhook, not card data on your own form. Your server creates a checkout preference, the browser SDK redirects the buyer to Mercado Pago's hosted page, and Mercado Pago notifies your app of the payment result. Pix payments stay pending until the buyer pays, so your app also needs a status route for when the buyer returns to your site.

This guide follows the process demonstrated by André Elias in a January 2025 video walkthrough (developer and creator of paid Next.js SaaS templates), reconciled against the Mercado Pago developers documentation. The stack is Next.js, the React framework, with routes hosted on Vercel for webhook testing and runtime logs.

Public Key vs Access Token vs Webhook Secret

Three credentials run the whole integration: the public key, the access token, and the webhook secret. Each lives in a different place and has a different exposure level. Since Pix launched in Brazil in 2020 and Mercado Pago added the credentials pages described below, confusing them — or mixing test and production environments — has been the most common cause of a broken setup.

• Public key (NEXT_PUBLIC_MP_PUBLIC_KEY): safe to expose in the browser, which is why it carries the NEXT_PUBLIC_ prefix in Next.js. The frontend SDK uses it to initialize Checkout Pro.
• Access token: server-side only. Your lib instantiates the Mercado Pago client with it to create preferences and query payments. Never ship it to the client.
• Webhook secret: the signature secret Mercado Pago gives you when you configure notifications. Your webhook route verifies each event's signature with it before processing, which blocks forged requests.

The environment depends on which account you copy the keys from. Production credentials come from your real account's 'production credentials' page. Test credentials come from logging into a test account and copying its 'production credentials' section: the label says production, but because you are inside a test user, the keys are test keys. That labeling quirk trips up nearly everyone on the first pass.

Creating the Application and Test Accounts

Search 'minhas integrações mercado pago' to land directly on 'Your integrations' in the developer dashboard, then create your application. The setup choices matter more than they look.

1. Name the application; names must be unique.
2. Choose solution type online payments (you are integrating yourself, not using an e-commerce platform).
3. Select the product Checkout Pro. If you plan transparent checkout instead, select that product; testing transparent checkout against a Checkout Pro application fails, and this mismatch cost the video's creator about an hour of debugging.
4. Integration model can stay blank; selecting the Mercado Pago wallet model is optional.
5. Create two test accounts: one buyer and one seller, each funded with test balance.

To get test credentials, log in as the seller test account (copy the generated email and password from the test accounts page), open 'Your integrations' again, and copy the public key, access token, and webhook secret from that session. Remember that paying from the same account you are selling from is rejected, so buy with the buyer test account.

Configuring Pix and the Webhook URL

Pix only appears as a payment option if your account has a registered Pix key, so register one in account settings before testing. The webhook notification URL is configured in the application's webhook section, where you enable 'payments' notifications and copy the signature secret. A common practice is pointing both success and test configurations to the same endpoint.

Unlike Stripe, which offers a CLI for local webhook forwarding, Mercado Pago's local testing is awkward. The practical workflow shown in the walkthrough is deploying to Vercel using its runtime logs: add a console.log at the top of your webhook handler, trigger a test notification from the dashboard, and confirm the event arrives with a valid signature. Note that the dashboard's simulated notification uses a payment ID that does not exist in your environment, so it verifies your endpoint and signature handling but will not process a real payment.

The Three Routes: Checkout, Pending Status, and Webhook

The integration needs three server endpoints in Next.js, each answering one question in the payment lifecycle: where does the buyer pay, did the payment go through, and how does Mercado Pago notify the server after the fact. Because Pix, the instant payment rail the Banco Central do Brasil launched in 2020, confirms payments asynchronously, the pending-status and webhook routes exist to close that gap. With the App Router model that Next.js 13 introduced in 2022, each endpoint is simply a route handler file.

• Create checkout: receives testId and userEmail from the client, builds a preference with items, metadata, payment method options, and installment count, and returns the checkout ID. Passing the user's email raises Mercado Pago's payment approval rate, so collect it whenever you have it.
• Pending payment status: Pix payments remain 'pending' after the checkout screen. When the buyer clicks 'back to the site', they land on this route, which queries the payment: if status is approved or the date_approved field is non-null, redirect to success; otherwise return the buyer to the home page.

One documented quirk: card payments report approval in the status field, but Pix payments sometimes leave status empty and carry the approval signal only in date_approved. Check both. A second quirk: Mercado Pago converts every metadata key you send at checkout creation to snake_case on the webhook payload, so read metadata with that naming on the server.

The webhook route handles the payment event type (use subscription_preapproval only if you later add recurring billing, which the walkthrough's creator handles with Stripe instead). Verify the signature using the webhook secret with the helper function from the documentation, then process approved payments server-side.

Settlement Timing and Approval Rate Trade-off

In 'Your business' settings, the settlement ('custos') section controls how soon money reaches you after a customer pays. Same-day settlement exists, but the creator reports two effects from his own experience: the per-transaction fee rises (his example showed R$ 4.99 falling to R$ 3.99 with 30-day settlement) and, in his observation, payment approval rates drop when settlement is immediate. He configures 30 days across his products and treats the immediate-settlement approval effect as a personal observation, not a documented Mercado Pago policy. Confirm current fees on your own account's pricing page, since they vary by country and plan.

Going to Production

After test payments pass, swap the three credentials in your .env for the production keys from your primary account, keeping the access token and webhook secret server-side. Run at least one end-to-end test with the buyer test account against the seller test account before switching, and keep Vercel's runtime logs open during the first production payments. Remember to uncheck any pre-selected deployment option in Vercel's log view if it filters out your webhook traffic.

For fiscal invoices issued alongside payments, services such as Focus NFE expose a REST API and webhooks for municipal invoice emission, which is what the video's sponsor is used for; it is optional to the payment flow itself.

FAQ

• Where do I find the public key in Mercado Pago? Open 'Your integrations' at the Mercado Pago developer panel, select your application, and open the credentials page. The public key sits alongside the access token, and its environment depends on whether you are logged into a real or test account.

• Why does my Pix payment never show 'approved' in the webhook? Pix payments often leave the status field empty and populate date_approved instead. Check both fields in your webhook handler and treat a non-null date_approved as payment confirmation.

• Can I test Mercado Pago webhooks locally? Local testing is much harder than with Stripe's CLI. The practical alternative is deploying to Vercel, logging events with console.log, and watching the runtime logs while triggering notifications from the dashboard.

• Does the metadata I send come back unchanged in the webhook? No. Mercado Pago converts all metadata keys to snake_case between checkout creation and the webhook payload. Read server-side metadata with that naming convention.

• Do I need transparent checkout to receive Pix? No. Hosted Checkout Pro offers Pix as a payment method. Transparent checkout is a separate product choice in the application setup and a separate integration effort.

Turn Your Own Integration Walkthroughs Into Articles

This article exists because a 28-minute screen recording explained a process that took its creator months of reading confusing documentation to learn. If you have the same kind of knowledge sitting in your own videos, including integration walkthroughs, architecture decisions, or lessons from a finished project, you can turn it into a searchable written guide.

With Skala Blog, you paste a YouTube URL, get a transcription, and generate a structured article you review before publishing. The explanation is already in your video; the article just makes it findable.

Source video