Weave Code
Mercadopago Laravel Package
puntodev/mercadopago
A Laravel/PHP integration for MercadoPago that simplifies creating payment preferences, handling checkout flows, and processing webhooks, giving developers a convenient wrapper for adding MercadoPago payments to their applications.
MercadoPago API Client
Frequently asked questions about Mercadopago
- What does the puntodev/mercadopago package actually do for Laravel?
- It is a thin Laravel service provider plus a hand-rolled HTTP client for api.mercadopago.com, focused on MercadoPago Checkout Pro. The exposed API is createPaymentPreference, findMerchantOrders, findMerchantOrderById, findPayments, and findPaymentById. It is not a wrapper around the official MercadoPago PHP SDK, so its scope is narrower than the package description suggests. If you need payment creation, refunds, subscriptions, or webhook validation, you will have to build or add those yourself.
- How do I install puntodev/mercadopago in a Laravel app?
- Install via Composer with composer require puntodev/mercadopago and let Laravel package discovery register the service provider. Before you commit, confirm your runtime meets the platform floor of PHP ^8.5 and illuminate/support ^13.0. On PHP 8.2–8.4 or Laravel 11/12, Composer will block the install. The supplied onboarding notes may not match the actual config file, so verify the env keys in the package source.
- Does this package support Laravel 11 or Laravel 12?
- Based on the stated requirements, no: it requires illuminate/support ^13.0 and php ^8.5. That is a hard install blocker for most Laravel 11/12 applications and for PHP 8.2–8.4 environments. If you need LTS support, you would have to fork the MIT-licensed code and relax the constraints, accepting the maintenance burden. Asking the maintainer whether ^11|^12|^13 support is planned is the key adopt-versus-fork question.
- Which environment variables does puntodev/mercadopago use for authentication?
- It uses OAuth2 client credentials, specifically MERCADOPAGO_API_CLIENT_ID and MERCADOPAGO_API_CLIENT_SECRET, and caches a bearer token for 1000 seconds under a key like mercadopago-token-{clientId}. This differs from the MERCADOPAGO_ACCESS_TOKEN pattern used in many MercadoPago tutorials and runbooks. Read the actual config file rather than relying on onboarding notes, and document the real keys before handoff. Expect the first integration day to be spent on auth if your team assumes access-token auth.
- How do I create a MercadoPago Checkout Pro preference with this package?
- Use the MercadoPago factory and MercadoPagoApi client, and build payloads with PaymentPreferenceBuilder and PaymentPreferenceItemBuilder instead of raw arrays. Credentials can be resolved per tenant with withCredentials($id, $secret), and usingSandbox() switches to the test environment. The package sets auto_return to all, collapses pending/failure back URLs to the success URL, and defaults item currency to ARS. Override currency per item if you are not Argentina-first.
- Does puntodev/mercadopago handle MercadoPago webhooks and signature validation?
- No. The package does not implement a webhook receiver, x-signature validation, idempotency, or reconciliation. When the evaluation says webhooks, it means you can pass a notification_url in the preference and then build the receiver yourself. You are responsible for validating signatures with x-signature and x-request-id, deduplicating notifications, and reconciling payment state. Treat webhook handling as custom application code, not a package feature.
- Can I process refunds, cancellations, or subscriptions with this package?
- No. The public API contract is limited to createPaymentPreference, findMerchantOrders, findMerchantOrderById, findPayments, and findPaymentById. There is no payment creation for Checkout API, Bricks, or transparent card processing, and no refunds, cancellations, preapproval, or subscription support. If your roadmap includes those features, this package covers roughly the first Checkout Pro milestone and then stops. You will need the official SDK or direct API calls for the rest.
- How do I test puntodev/mercadopago in CI without live MercadoPago credentials?
- Because the client uses Laravel's Http facade rather than an SDK transport, you can use Http::fake() to stub request and response sequences in feature tests. That gives you control over success, failure, and token-cache paths without hitting the sandbox. The package's own tests/MercadoPagoApiTest.php makes real HTTP calls and needs live credentials, so it is not a useful CI quality gate. Build your own fakes around the five API methods and error paths you actually use.
- What are the production risks of using puntodev/mercadopago?
- The main risks are bus factor 1, a single maintainer, 2 stars, 0 dependents, and no stated security-response or SLA process. Every call uses ->throw(), so failures surface as RequestException; retry, backoff, circuit breaking, and dead-letter handling are yours to implement. The PHP 8.5/Laravel 13 floor means you cannot consume it on an LTS stack without forking. MIT licensing is the mitigation because a fork is always available, but you inherit the maintenance burden.
- What are the alternatives to puntodev/mercadopago for Laravel?
- The official MercadoPago PHP SDK or direct calls to api.mercadopago.com are the obvious alternatives if you need broader coverage such as refunds, subscriptions, or transparent payments. This package is reasonable only for a narrow, greenfield Checkout Pro integration on PHP 8.5 and Laravel 13. Its per-tenant withCredentials() and usingSandbox() helpers are useful if you are building multi-tenant Argentina-first checkout. If the platform floor is not changing, plan to fork or use a different integration.
Weaver
How can I help you explore Laravel packages today?