Mercado Pago

In this article

Setup

Support

Errors and declined transactions

This article describes the integration of Mercado Pago Point terminals (N950 PEDs) with LS Pay. The plugin communicates with Mercado Pago through its REST API.

Mercado Pago Point documentation

Mercado Pago Orders API reference

Setup

Note: This integration was tested on the N950 terminal.

Prerequisites

  • A Mercado Pago seller account with an application created for the integration. The credentials needed for the settings below are found in the application on the Mercado Pago developer portal.
  • A Mercado Pago Point N950 terminal, registered to the seller account and linked to the application.

Settings

The following settings are needed to communicate with the terminal:

Setting Description Default value
Access token The access token (Bearer) of the Mercado Pago application, found in the application's credentials on the Mercado Pago developer portal. Note: Make sure the token is safely stored. Use the test credentials in a test environment and the production credentials in a live environment.  
Device ID The serial number of the terminal, in the format NEWLAND_N950__<serial number>.  
Mercado Pago API base URL Base URL of the Mercado Pago API. https://api.mercadopago.com
Payment polling timeout Timeout, in seconds, for how long the plugin waits for the payment to complete on the terminal. 120
Polling interval How often, in milliseconds, the plugin asks Mercado Pago for the status of the payment. 3000

Testing the integration

Mercado Pago provides separate test users for testing: a seller and a buyer. Contact Mercado Pago to get the test users and credentials for your application.

  • Log on to the Mercado Pago developer portal with the seller test user to find the application credentials (such as the public key and access token).
  • To make test payments, install the Mercado Pago app on a mobile phone and log on to it with the buyer test user. The Mercado Pago app is only available in Argentina, so the app package must be requested from Mercado Pago. It is shared through TestFlight, so TestFlight must also be installed on the phone.

 

Support

EFT

Mercado Pago supports these EFT functions in LS Pay:

  • Purchase
    • The customer pays by scanning a QR code with the Mercado Pago app, and chooses to pay with account money or a credit card.
    • If the chosen card supports installments, the customer selects the number of installments on the terminal. The installment information in the response is returned in the additional data.
  • Refund
    • Only referenced refunds are supported. Stand-alone refunds are not supported.
    • Partial and full refunds are possible.
  • Cancel
    • A payment can only be canceled before it has been sent to the terminal (the order has the status "created").
  • Void
    • Mercado Pago has no void function, so a void is handled as a refund. A void can be full or partial, and can be done on any previous transaction.
    • How long after the purchase a return is accepted is decided by Mercado Pago.
  • Get last transaction

 

Test environment

Note: These steps are only needed in the test environment. In the production environment, the payment is shown on the terminal directly.

  • Only QR payments are supported.
  • After the purchase request has been sent, tap Actualizar on the terminal to fetch the request. The QR code is then shown on the terminal.
  • Scan the QR code with the Mercado Pago app (logged on with the buyer test user), scroll to the bottom and choose to pay with account money or a credit card. Two test credit cards are available, one of which supports installments.

 

Refunds and voids

Both a refund and a void must reference the original purchase, and both of the original transaction's IDs must be sent in the request:

Request field Value from the purchase response
originalAdditionalId The Mercado Pago order ID, returned in the AdditionalId field. Example: ORDTST01KWF3AXPZX8H1KKWRJJTHET2X. This is the order that is refunded.
originalEFTTransactionId The payment ID, returned in the EFTTransactionId field. It must be a payment that belongs to the order above.

Important: Both IDs must come from the original purchase. A refund response returns its own refund ID (starting with REF) in EFTTransactionId; sending that ID in a new refund request is rejected. Make sure the POS stores both IDs from the purchase response and sends them back with the refund or void.

The refund is rejected before it is sent to Mercado Pago if:

  • originalEFTTransactionId is missing. The error message is "Missing transaction reference, terminal does not support standalone refund".
  • originalEFTTransactionId is not a payment on the order. The error message is "Order '...' holds no payment '...'".

 

Errors and declined transactions

How a failure reported by Mercado Pago reaches the POS depends on what the failure is about.

Declined transactions

When Mercado Pago refuses a payment or a refund, the request itself has still completed. The transaction response is returned with ResultCode = Success, AuthorizationStatus = Declined, and EftMessage set to the reason given by Mercado Pago. A declined transaction is not saved as the last transaction and has no receipt, because nothing was authorized.

This applies to:

  • Payments declined by the terminal, for example cc_rejected_insufficient_amount. EftMessage is set to the payment's status detail.
  • Orders that have failed or expired. EftMessage is set to the order's status detail, or to the name of the status if no detail was returned.
  • Refunds that Mercado Pago refuses, for example when the refund amount is higher than what was paid ("Refund amount exceeds the available amount."). Mercado Pago decides whether an order can be refunded, so the refusal comes back with Mercado Pago's own wording. Refund declines include:
    • order_already_refunded
    • cannot_refund_order
    • refund_amount_exceeds
    • refund_period_exceeded
    • max_refunds_exceeded
    • payment_not_refundable
    • amount_not_refundable
    • unsupported_partially_refunds
    • partial_refund_forbidden_with_tips
    • action_not_allowed_for_current_state
    • refund_in_progress
    • movement_operations_pending
    • order_payment_not_yet_enabled_for_refund
    • insufficient_money_for_refund
  • A purchase sent to a terminal that already has a payment waiting (already_queued_order_for_terminal).

Integration errors

Faults in the integration are thrown as an EFTException and say nothing about the payment itself. These include:

  • Credential errors (unauthorized, user_not_authorized). Check the access token.
  • A malformed request (for example json_syntax_error, required_properties and empty_required_header).
  • An order that does not exist (order_not_found).
  • An unrecognized error code.
  • A connection failure, or a timeout while waiting for the payment on the terminal.
  • A failed cancel. A cancel does not return a transaction response, so a failure is always thrown.

Unknown order status

If Mercado Pago returns an order status the plugin does not recognize, the response is returned with AuthorizationStatus = None and ResultCode = Error. EftMessage still contains the status detail from Mercado Pago. Contact LS Retail support if this happens.