# Mercado Pago source: https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/alt-pay-methods/a2a/mercado-pago/index.md Mercado Pago is a payments platform in Latin America that enables ecommerce merchants to accept local payment methods in local currencies. Mastercard Gateway integrates with Mercado Pago Checkout and provides a hosted redirect payment experience. You redirect customers to Mercado Pago to confirm the payment, and the customers return to your website after the payment is confirmed. ## Prerequisites {#prerequisites} To use the Mercado Pago payment method through the Mastercard Gateway, you must: * Register with your browser payments service provider. * Have a bank account in one of the supported currencies registered against your merchant account at your browser payments service provider. * Ensure that your merchant profile on the Mastercard Gateway is configured using the details of your account with the browser payments service provider. * Obtain your access token details from Mercado Pago and configure them on the gateway before you offer Mercado Pago as a payment method. ## Mercado Pago transactions {#mercado-pago-transactions} Mercado Pago supports transactions originating from multiple countries with their corresponding currencies. | Country | Currency | |-----------|----------| | Argentina | ARS | | Brazil | BRL | | Mexico | MXN | ## Mercado Pago integration {#mercado-pago-integration} ### Mercado Pago through Direct Payment {#mercado-pago-through-direct-payment} Direct Payment integration allows you to offer the Mercado Pago payment method on your checkout page. Mercado Pago is supported starting with API version 58. To initiate a Direct Payment transaction, submit the [INITIATE_BROWSER_PAYMENT](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#browser-payment) operation using the WSAPI with these parameters: * `sourceOfFunds.type=MERCADO_PAGO_CHECKOUT` * `browserPayment.operation=PAY` ### POI request {#poi-request} ```shell curl --request POST \ --url "{{remotehost}}/api/rest/version/llaatteesstt/merchant/MPMER01/paymentOptionsInquiry" \ --header "Authorization: Basic bWVyY2hhbnQuTVBNRVIwMTplMTQ4ZjczMmY2ODIxOTY1ZGFiYTJjYzg3MjE0NjYyMA==" \ --header "Content-Type: application/json" ``` ### POI response {#poi-response} ```json { "merchant": "MPMER01", "paymentTypes": { "klarnaPayLater": { "countries": [ { "countryCode": "GBR" } ], "currencies": [ { "currency": "GBP" } ], "transactionSources": [ { "transactionSource": "INTERNET" } ] }, "mercadoPagoCheckout": { "currencies": [ { "currency": "ARS" }, { "currency": "BRL" }, { "currency": "MXN" } ] }, "openBankingBankTransfer": { "aspsp": { "other": [ { "id": "898df7e6-09ef-414f-9c70-072513a33d26", "name": "Adonis Bank" } ] }, "capabilities": [ { "capability": "REFUNDS" } ] } }, "result": "SUCCESS", "supportedPaymentOperations": [ { "supportedPaymentOperation": "PURCHASE" } ] } ``` ### Sample code to Initiate Mercado Pago Payment {#sample-code-to-initiate-mercado-pago-payment} ```json { "apiOperation": "INITIATE_BROWSER_PAYMENT", "billing": { "address": { "city": "Edinburgh", "company": "MPGS", "country": "USA", "postcodeZip": "EH123AB", "stateProvince": "Scotland", "street": "OceanPoint", "street2": "OceanDrive" } }, "browserPayment": { "operation": "PAY", "returnUrl": "{{remotehost}}/apmDemoApp/complete.html" }, "customer": { "account": { "id": "custoAccount" }, "dateOfBirth": "1999-12-31", "email": "test_user_7027819509285046979@testuser.com", "firstName": "Payton", "lastName": "McPayer", "mobilePhone": "0779xxxx555", "nationalId": "nationalId1" }, "order": { "reference": "TEST-SUCCEED", "amount": "123.46", "itemAmount": "115", "currency": "ARS", "discount": { "amount": "7.00" }, "item": [ { "detail": { "unitTaxRate": "0" }, "name": "spud", "quantity": "1", "unitDiscountAmount": "3.00", "unitPrice": "21.00", "category": "Electronics", "sku": "sku_one", "description": "Mobile phone", "unitTaxAmount": "0.47" }, { "detail": { "unitTaxRate": "0" }, "name": "item2", "quantity": "2", "unitDiscountAmount": "2.00", "unitPrice": "47.00", "category": "Eatables", "sku": "sku_two", "description": "chips", "unitTaxAmount": "5.00" } ], "shippingAndHandlingAmount": "4.99", "taxAmount": "10.47" }, "shipping": { "address": { "city": "Shipsville", "country": "MXN", "postcodeZip": "EH67DX", "stateProvince": "Scotland", "street": "2ShippingHeights", "street2": "ShipsDrive" }, "contact": { "email": "test_user_62904073@testuser.com", "firstName": "Shipfirst", "lastName": "McShiplast" } }, "sourceOfFunds": { "type": "MERCADO_PAGO_CHECKOUT" } } ``` ### Impact of customer and item information on approval rates {#impact-of-customer-and-item-information-on-approval-rates} Payment method providers, such as Mercado Pago, recommend that merchant submit customer and item details with each transaction. This information improves visibility for authorization and fraud systems, enabling more accurate transaction assessment. As a result, merchant can reduce false declines and improve approval rates. | Parameters Name | Type | Description | |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | * `customer.firstName` * `customer.lastName` * `customer.phone` * `order.item[n].sku` * `order.item[n].name` * `order.item[n].description` * `order.item[n].category` * `order.item[n].quantity` * `order.item[n].unitPrice` | Strongly recommended | The payment method provider requires the customer and item information to better assess transactions, improve approval rates, and reduce false declines. | ## Void {#void} You can cancel the Mercado Pago payment only under these conditions. * If the payer is not redirected to Mercado Pago, then the gateway updates the order status to CANCELLED. * If a payment is created and is in the Pending or in progress state, then the payment by default gets updated to the cancelled state and the gateway updates the order status to CANCELLED. ## Refunds {#refunds} You can refund the Mercado Pago payments in installments or in full. Ensure that your merchant account is enabled for refunds on the Mastercard Gateway through your browser payments service provider. Partial refunds are allowed on the Mercado Pago payments. ## Interpretation of the transaction result {#interpretation-of-the-transaction-result} This table specifies the transaction response codes for the possible scenarios that you may encounter after initiating the Mercado Pago payment. | Initiate browser payment response | What this means... | |-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `response.gatewayCode=SUBMITTED` `result=SUCCESS` | Redirect the payer using the URL provided in the response. | | **Retrieve transaction or Retrieve order response** | **What this means...** | | `response.gatewayCode=APPROVED` `result=SUCCESS` | The payment is successful. | | `response.gatewayCode=PENDING` `result=PENDING` | The Mastercard Gateway is waiting for a notification from the acquirer about the payment result. Try `RETRIEVE_TRANSACTION` again later or listen to notifications from the Mastercard Gateway. | | `response.gatewayCode=CANCELLED` `result=FAILURE` | The payer has canceled the interaction for this payment. Offer the payer the option to try another payment method. | | `response.gatewayCode=DECLINED` or `ACQUIRER_SYSTEM_ERROR` `result=FAILURE` | The payment was declined. Offer the payer the option to try another payment method. In case of an `ACQUIRER_SYSTEM_ERROR`, you may want to inquire with the acquirer about the reason for the payment failure, or you can try `RETRIEVE_TRANSACTION` again. | | `response.gatewayCode=TIMED_OUT` `result=FAILURE` | Treat this as a declined payment. The Mastercard Gateway attempts to ensure the transaction is not successful or reverts the transaction. | ## Mercado Pago through Hosted Checkout {#mercado-pago-through-hosted-checkout} Hosted Checkout integration allows you to collect payment details from your payer through an interaction that the Mastercard Gateway hosts and displays. From the API version 63 onwards, Mercado Pago is automatically available as a payment method once your payment service provider enables and configures you for this payment method. The Mercado Pago payment method on Modern Hosted Checkout uses this flow. 1. Payers select Mercado Pago as the payment method on the hosted checkout screen. 2. Once payers select the Mercado Pago payment method, the browser redirects the payer to the Mercado Pago website to initiate the payment. 3. After the payment process is complete on the Mercado Pago website, the browser redirects the payer back to your website. The order confirmation receipt displays for the payers. ## Test your integration {#test-your-integration} You can use test cards of the local payment methods and simulate different payment responses without using a real card. Use any test card provided in the linked documentation for [ARS](https://www.mercadopago.com.ar/developers/en/docs/checkout-pro/additional-content/your-integrations/test/cards), [BRL](https://www.mercadopago.com.br/developers/en/docs/checkout-pro/additional-content/your-integrations/test/cards), and [MXN](https://www.mercadopago.com.mx/developers/en/docs/checkout-pro/additional-content/your-integrations/test/cards). Ensure to use these details with the non-test merchants until Mercado Pago sandbox. This table describes the payment results status that you can use to fill against the cardholder's name: | Payment status | Description | Transaction response gateway code | |----------------|----------------------------|-----------------------------------| | APRO | Approved payment | APPROVED | | OTHE | Declined for general error | TIMED_OUT | | CONT | Pending payment | PENDING | Warning: As the request is routed to the Mercado Pago Sandbox, you can test these credentials only with the non-test merchants. The test card details might change as Mercado Pago hosts the test card URLs. Use your Mercado Pago Sandbox credentials to test with the sandbox environment.