Mercado Pago Wallet

Trusted Redirects Bundle

Mercado Pago Wallet is a digital wallet payment method that enables customers to pay using their Mercado Pago account balance, saved cards, or other funding sources within the Mercado Pago ecosystem. It is available in Argentina, Brazil, Chile, Mexico, and Uruguay. This guide walks you through integrating Mercado Pago Wallet with the EBANX Direct API.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.
• Knowledge of your development environment and tools.

Availability

Mercado Pago Wallet is available in the following countries and currencies:

Country	Currency
Argentina	Peso Argentino (ARS)
Brazil	Real Brasileiro (BRL)
Chile	Peso Chileno (CLP)
Mexico	Peso Mexicano (MXN)
Uruguay	Peso Uruguaio (UYU)

How it works

When a customer selects Mercado Pago Wallet at checkout, the payment follows a redirect-based flow:

• Initiate payment - Send a payment request to EBANX with payment_type_code set to mercadopago and a redirect_url for the customer to return to after completing the payment.
• Redirect customer - Redirect the customer to the URL provided in the response. The customer completes the payment on the Mercado Pago checkout page.
• Payment confirmation - Once the customer completes the payment, EBANX updates the payment status from pending (PE) to confirmed (CO). If the payment is not completed within the expiration window, the status updates to cancelled (CA).

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Payment request

   Once your customer selects Mercado Pago Wallet at checkout, create a payment request using the ws/direct endpoint. Assign the payment_type_code parameter to mercadopago.

   
   

   Payment parameters

   Parameter	Type	Required	Description
   integration_key	String	Yes	Your unique EBANX integration key.
   payment.name	String	Yes	Customer full name.
   payment.email	String	Yes	Customer email address.
   payment.phone_number	String	No	Customer phone number.
   payment.document	String	Required for AR, BR, CL, UY	Customer tax ID or document number (e.g., CUIT for Argentina, CPF for Brazil, RUT for Chile, CI for Uruguay). Not required for Mexico.
   payment.country	String	Yes	Two-letter country code (ar, br, cl, mx, uy). Must match the currency.
   payment.payment_type_code	String	Yes	Payment type identifier. Use mercadopago.
   payment.merchant_payment_code	String	Yes	Unique payment identifier generated by your system.
   payment.currency_code	String	Yes	Three-letter currency code (ARS, BRL, CLP, MXN, UYU). Must match the country.
   payment.amount_total	Number	Yes	Total payment amount in the specified currency.
   payment.redirect_url	String	Yes	URL to redirect the customer back to after completing the payment.

   
   

   Sample request

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "payment": {
         "name": "John Doe",
         "email": "john.doe@example.com",
         "phone_number": "5555555555",
         "document": "{{tax_id}}",
         "country": "{{country}}",
         "payment_type_code": "mercadopago",
         "merchant_payment_code": "{{merchant_payment_code}}",
         "currency_code": "{{currency}}",
         "amount_total": 99.85,
         "redirect_url": "https://merchant.example.com/callback"
       }
     }'

3. Payment response

   Each request returns a response similar to the example below. The response includes the ewallet_payment_method field, which indicates the funding source selected by the customer within the Mercado Pago wallet (e.g., ACCOUNT_BALANCE), and the ewallet_installments field, which indicates the number of installments chosen by the customer.

   {
     "payment": {
       "hash": "<{hash_here}>",
       "country": "{{country}}",
       "merchant_payment_code": "{{merchant_payment_code}}",
       "order_number": null,
       "status": "PE",
       "status_date": null,
       "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "99.85",
       "amount_ext": "99.85",
       "amount_iof": "0.00",
       "currency_rate": "1.0000",
       "currency_ext": "{{currency}}",
       "due_date": "{{YYYY-MM-DD}}",
       "instalments": "1",
       "payment_type_code": "mercadopago",
       "redirect_url": "https://acquirer.redirect.example.com",
       "ewallet_payment_method": "ACCOUNT_BALANCE",
       "ewallet_installments": "3",
       "pre_approved": false,
       "capture_available": null
     },
     "status": "SUCCESS"
   }

   At this stage, the payment will appear as pending (PE) in your

   Merchant Areachevron_right

4. Redirect customer to complete payment

   Redirect the customer to the URL provided in the redirect_url field of the response. The customer will be taken to the Mercado Pago checkout page to select their preferred funding source and authorize the payment.

   "redirect_url": "https://acquirer.redirect.example.com"

   The redirect_url returned in the response is different from the redirect_url you sent in the request. The response URL points to the Mercado Pago checkout page where the customer completes payment. After completing or cancelling, the customer is redirected back to the redirect_url you provided in the original request.

5. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

6. Congratulations!

   You have successfully integrated Mercado Pago Wallet.

   For more information, refer to the

   Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.