Weave Code
Dx Php Laravel Package
mercadopago/dx-php
Official Mercado Pago SDK for PHP, making it easy to add payments to Laravel or any PHP app. Create checkout preferences, process payments, manage subscriptions, and handle webhooks and notifications through a clean, object-oriented API.
Mercado Pago PHP SDK (dx-php) is the official client library for integrating Mercado Pago payments into PHP applications. It wraps the REST API with a fluent, object-oriented interface, handling authentication refresh, request signing, and response mapping so you can build checkout flows without manual cURL work.
- OAuth 2.0 token management with automatic refresh
- Payments & Checkout Pro preferences, plus refunds and cancellations
- Webhook notifications for async payment events
- Framework-agnostic design with Laravel-friendly service providers
- Typed entities mirroring the Mercado Pago API
Frequently asked questions about Dx Php
- How do I install mercadopago/dx-php in a Laravel application?
- Run composer require mercadopago/dx-php and pin an exact version, since vendor payment SDKs often track the live API rather than semver guarantees. The dependency graph is shallow, but watch for a Guzzle version conflict if your app already pins Guzzle explicitly. There is no service provider to discover, so register your own singleton binding and keep the SDK behind an adapter class rather than calling it from controllers and jobs.
- Is mercadopago/dx-php an official Laravel package with a service provider or facade?
- No. It is Mercado Pago's official PHP SDK and is framework-agnostic: no ServiceProvider, no facade, no publishable config, and no Laravel-idiomatic contracts. That gap is manageable, but it dictates the architecture, so treat the SDK as an anti-corruption layer boundary instead of a library to sprinkle through your codebase. You write the service provider binding, the config file, and the adapter yourself.
- How should I configure and store the Mercado Pago access token in Laravel?
- Store credentials in environment variables and read them through config/mercadopago.php, never hardcoded or committed. The SDK sets its access token through a static, global configurator, so avoid configuring it in a service provider constructor or any bootstrap that persists across requests. Resolve the token at call time inside a single resolved service, which also makes per-tenant and multi-account setups possible.
- Does mercadopago/dx-php work with Laravel Octane and queue workers?
- It can, but static state persists across requests under Octane and long-running workers, so a globally configured access token can leak between requests or tenants. Never rely on the static configurator surviving a request boundary. Wrap the SDK in a service that resolves credentials per call, and be careful with parallel test execution for the same reason.
- How do I receive and validate Mercado Pago webhooks in Laravel?
- The SDK does not build webhook handling for you: add a route excluded from CSRF verification, validate the signature yourself, return 200 quickly, and push reconciliation into a queued job. Keep a scheduled poll of the payments/search endpoint alongside the webhook so you have a reliable source of truth when notifications are missed or replayed. Signature validation is your responsibility, not the SDK's.
- Can I use mercadopago/dx-php for marketplaces and split payments?
- Single-tenant with one merchant account works fine, but marketplace or OAuth split payments is high effort. You must store and refresh per-seller tokens and resolve the correct token per call, while the SDK's global static configuration is a correctness hazard in that design. This changes the architecture, not just the config, so plan the OAuth token storage and refresh flow before adopting.
- Should I use Checkout Pro or Checkout Bricks with this SDK?
- Checkout Pro is a redirect flow: one preference create plus a webhook, low effort, and keeps you in the lighter SAQ-A PCI scope. Checkout Bricks embeds card fields client-side with tokenization, which is medium effort and expands your PCI scope. The SDK has no frontend opinion, so treat Bricks as a separate JavaScript integration with its own version pin.
- Which PHP and Laravel versions does mercadopago/dx-php support?
- It installs via Composer on a modern stack and is compatible with PHP 8.x and Laravel 10, 11, and 12, with a shallow dependency graph. Watch for a Guzzle constraint conflict if your application pins Guzzle directly. Pin exact SDK versions and treat upgrades as change-managed events rather than routine composer update noise.
- How do I test Mercado Pago payments in Laravel without real charges?
- Use Mercado Pago test users and sandbox credentials in a non-production environment, and assert on your own adapter's responses rather than the SDK's loosely typed dynamic-property models. Because the SDK depends on global mutable state, run configuration-touching tests serially or isolate them so parallel execution does not cause flaky failures. Also verify the Packagist vendor is the first-party publisher before trusting it in a payment path.
- What are the production risks and alternatives to mercadopago/dx-php?
- The dominant risks are global mutable state conflicting with dependency injection, Octane, and queue workers; untyped models where field drift after an API change surfaces at runtime on a money path; and weak version guarantees. There is also a provenance gap worth clearing, so confirm the vendor is first-party, verify the source repository, and mirror the dependency if unclear. Alternatives are mostly direct HTTP calls against the documented REST API, or a community Laravel wrapper, so keep the SDK behind your own interface to swap or bypass it later.
Weaver
How can I help you explore Laravel packages today?