Mercado Pago via dLocal
This feature is a Private Beta release. Contact Chargebee Support to enable Mercado Pago via dLocal for your live and test sites.
Mercado Pago is a digital wallet in Latin America that customers use to pay from a stored wallet balance or a linked funding source. Chargebee supports Mercado Pago as a payment method through the dLocal payment gateway.
When customers select Mercado Pago at checkout, they are redirected to Mercado Pago to approve the payment and authorize an enrollment. The payment is processed asynchronously, and the transaction stays in a pending state until dLocal confirms the final status through a webhook notification. After the initial authorization, Chargebee stores the enrollment returned by dLocal and uses it for merchant-initiated renewal charges.
Supported countries and currencies
Mercado Pago via dLocal supports the following countries and currencies. Refer to the dLocal Mercado Pago documentation for each country for the latest details.
| Country | Currency | dLocal documentation |
|---|---|---|
| Brazil | BRL | Mercado Pago in Brazil |
| Chile | CLP | Mercado Pago in Chile |
| Mexico | MXN | Mercado Pago in Mexico |
| Colombia | COP | Mercado Pago in Colombia |
Chargebee sends the customer's billing country as the payer country for Mercado Pago transactions, and rejects a Mercado Pago payment intent created in a currency not supported for that country.
Payment features and workflows
The following table describes the supported features and behavior for Mercado Pago via dLocal:
| Feature | Description | Supported | Default state | Configuration or behavior |
|---|---|---|---|---|
| Integration sync mode | Defines how payment requests are processed and how statuses are updated. | Yes (asynchronous only) | Asynchronous | dLocal processes Mercado Pago payments asynchronously. Chargebee receives the final status through webhooks. |
| Capture settings | Defines when funds are captured after authorization. | Yes | Auto capture | No configuration required. Auto capture is the only supported option. Manual capture is not available for Mercado Pago. |
| Verification modes | Defines how payment methods are validated before payment. | No | Not applicable | Zero-amount verification is not supported. The customer authorizes the enrollment as part of the first payment, or through a standalone enrollment redirect. |
| Regulatory requirements support | Compliance requirements for the payment method. | Not applicable | Not applicable | Not applicable |
| Statement descriptor | Business name shown in the customer's statement. | No | Not applicable | Chargebee does not send a statement descriptor to dLocal for this method. |
| Chargeback management | Handles disputes and chargebacks. | No | Not applicable | Not supported. Wallet payments are approved by the customer in the Mercado Pago app. |
| Fraud management | Identifies high-risk transactions. | No | Not applicable | Not supported by Chargebee for this method. Risk screening is handled by dLocal and Mercado Pago. |
| Transaction initiation type | Indicates whether the transaction is customer-initiated or merchant-initiated. | Yes | Customer-initiated for the first payment | The first payment is customer-initiated and requires a redirect. Renewals are merchant-initiated and run against the stored enrollment without a redirect. |
| Error intelligence | Provides standardized failure categorization. | Yes | Enabled | No configuration required. |
| Gateway transaction details | Provides raw gateway responses. | Yes | Enabled | Available under Error details on the transaction page. |
| Addition of payment methods in the Chargebee Dashboard | Add a payment method outside a checkout. | No | Not applicable | A merchant cannot add this payment method from the customer record in the Chargebee Dashboard. Use the Create a payment source using permanent token API with the dLocal enrollment ID. The enrollment must already be authorized by the customer. |
| Refunds | Returns funds to the customer's wallet. | Yes | Enabled | Full and partial refunds are supported once the payment is settled. A refund against a pending payment fails. |
| Void | Cancels an authorization before capture. | No | Not applicable | Not supported. Use a refund after the payment settles. |
Prerequisites
Ensure the following before configuring Mercado Pago payments via dLocal:
- A dLocal merchant account with Mercado Pago enabled. Contact the dLocal support team to activate Mercado Pago for your account.
- dLocal is added and configured as a payment gateway in your Chargebee site.
- Your Chargebee site is enabled for BRL, CLP, MXN, or COP collections, depending on the countries you sell in.
Integration options
You can integrate Mercado Pago via dLocal using the following methods:
| Integration method | Supported |
|---|---|
| Chargebee Checkout | In-app layout of Checkout - Supported Full Page Checkout - Supported |
| Chargebee Self-Serve Portal | Supported. Customers can add or update Mercado Pago as a payment method from the customer portal. |
| Custom Checkout | Payment Components - Supported Chargebee.js (without Payment Components) - Supported API (Payment Intent) - Supported dLocal.js - Not supported |
Supported token formats
Use the following token formats when you build a custom checkout or migrate from another provider:
| Token type | Description | Supported | Token field | Token format |
|---|---|---|---|---|
| Chargebee Payment Intent | Recommended for a custom checkout built with Chargebee.js or Payment Components. | Yes | payment_intent[id] | payment_intent_id |
| Chargebee token | Legacy format. Not recommended for new integrations. | No | Not applicable | Not applicable |
| Gateway permanent token | The dLocal enrollment ID. Used for recurring payments and migrations. | Yes | payment_method[reference_id] | dLocal enrollment ID |
| Gateway temporary token | Short-lived token convertible to a permanent token. | No | Not applicable | Not applicable |
Configure Mercado Pago in Chargebee
Follow these steps to enable Mercado Pago in your Chargebee site:
- Log in to the Chargebee app.
- Go to Settings > Configure Chargebee > Payment Gateways.
- Select the relevant dLocal instance from the list.
- On the Configure dLocal page, turn on Mercado Pago in the list of payment methods.
- Click Apply to save your changes.
Configure Smart Routing
When you enable Mercado Pago through dLocal, Chargebee automatically adds a Smart Routing rule that sends transactions to that dLocal instance for each of BRL, CLP, MXN, and COP that is enabled on your site and has no Mercado Pago rule yet. If a rule already points to another gateway for a currency, Chargebee does not change it. Edit that rule so that Mercado Pago transactions route to dLocal.
Follow these steps to modify the Smart Routing settings:
-
Go to Settings > Configure Chargebee > Payment Gateways.
-
Click Manage Rules under Smart Routing.
-
Go to the Mercado Pago section and click Add a Gateway or Edit for the relevant currency.
-
Select the dLocal instance that has Mercado Pago enabled from the Choose a payment gateway drop-down menu.
-
Click Save.
Configure webhook notifications
Mercado Pago payment statuses are confirmed asynchronously, so webhook notifications from dLocal are mandatory.
Chargebee registers and manages the dLocal webhook endpoint for your site. You do not need to create the endpoint manually in the dLocal dashboard.
dLocal sends notifications for the following updates, which Chargebee applies to the corresponding record:
| Notification | What Chargebee updates |
|---|---|
| Payment status update | Moves the transaction to success or failure based on the final dLocal payment status. |
| Enrollment status update | Activates, rejects, cancels, or expires the stored Mercado Pago payment method. |
| Refund status update | Marks the refund as complete or failed. |
Checkout flow
Your customer completes the following steps at checkout when paying with Mercado Pago via dLocal:
-
The customer reviews the order on the Your cart page and clicks Proceed to Checkout.
-
The customer enters Account Details, Billing Address, and the document number, selects Mercado Pago, and clicks Pay & Subscribe.
-
The customer is redirected to Mercado Pago and approves the payment and the enrollment in the Mercado Pago app.
-
The customer is redirected back to Chargebee.
-
Chargebee marks the transaction as successful or failed when it receives the status from dLocal, and the order confirmation page appears.
Enable for subscriptions
Mercado Pago supports recurring billing through dLocal enrollments.
- First payment (customer-initiated). Chargebee sends the payment and the enrollment request together. The customer approves both in a single redirect. dLocal creates an on-demand enrollment.
- Stored payment method. Chargebee stores the dLocal enrollment ID as the payment method reference for the customer.
- Renewals (merchant-initiated). Chargebee charges the stored enrollment directly. The customer is not redirected again. The enrollment must be active at dLocal before a renewal can succeed. A merchant-initiated payment against an enrollment that is still pending approval fails.
- Adding the method without a payment. Chargebee can create an enrollment on its own, without a payment. The customer still completes a redirect to authorize it.
- Removing the method. Deleting the payment method in Chargebee cancels the enrollment at dLocal.
Testing in sandbox
Use the dLocal sandbox environment to validate the Mercado Pago flow end to end.
Test payer details for each supported country:
| Country | Currency | Document number |
|---|---|---|
| Brazil (BR) | BRL | 11934254096 |
| Chile (CL) | CLP | 12345678 |
| Mexico (MX) | MXN | 1234567890 |
| Colombia (CO) | COP | 12345678 |
Run the same flow for each country using its currency and document number.
A sandbox transaction stays pending until the customer completes the redirect and dLocal sends the status notification. Treat that transaction as pending until the notification arrives.
Testing in production
Before going live:
- Confirm that Mercado Pago is enabled in your live dLocal account.
- Confirm that Mercado Pago is turned on for the live dLocal gateway instance in Chargebee, and that Smart Routing sends transactions in your supported currencies to that instance.
- Run an end-to-end transaction with a real Mercado Pago wallet, because approval requires the Mercado Pago app.
- Verify that the transaction moves from pending to success after the webhook notification arrives.
- Verify that a renewal against the stored enrollment succeeds without a redirect.
Reconciliation
To reconcile transactions between Chargebee and dLocal:
- Retrieve the id_at_gateway value from the Chargebee transaction details.
- Locate the payment with the same ID in your dLocal reports.
- Match the transactions using this reference to ensure financial consistency.
Error codes and troubleshooting
Open the failed Mercado Pago transaction and check Error details for the dLocal response. Error intelligence categorizes the failure. No additional configuration is required.
FAQs
1. Can customers use Mercado Pago for recurring subscriptions?
Yes. The customer approves an enrollment during the first payment, and Chargebee uses that enrollment to collect renewals without redirecting the customer again.
2. Why is my Mercado Pago transaction still pending?
Mercado Pago is asynchronous. The transaction stays pending until the customer completes the redirect and dLocal sends the final status notification. If a transaction stays pending well beyond the redirect window, the customer most likely abandoned the approval.
3. Can I capture a Mercado Pago payment manually?
No. Mercado Pago supports auto capture only. Manual capture and void are not available.
4. Does the billing address country affect Mercado Pago?
Yes. Chargebee sends the customer's billing country as the payer country for Mercado Pago, because the method is offered across multiple countries.
5. Is the document number mandatory?
Chargebee does not enforce it, but dLocal does. Chargebee sends the document number to dLocal only when the customer provides one. dLocal lists the payer's document as required in the countries where Mercado Pago is supported (for example, CPF or CNPJ in Brazil), so a payment without it can be rejected by dLocal. Collect the document number at checkout.
Limitations and important points
- Mercado Pago is available only for Brazil, Chile, Mexico, and Colombia, in BRL, CLP, MXN, and COP respectively.
- Manual capture and void are not supported. Use a refund after the payment settles.
- A refund against a payment that is still pending at dLocal fails.
- A renewal fails if the enrollment has not reached the active state at dLocal.