Configure terminal
To continue with the integration of Mercado Pago Point to your system, after having created your application and obtained the appropriate credentials, it is necessary to configure your Point terminal to operate in integrated mode.
This configuration ensures that payments made on the terminals can be managed from your system, optimizing efficiency in reconciliation and task management.
To configure your Point terminal in integrated mode, you must first create and configure a store and a point of sale, and then associate that terminal to the created store and point of sale. This allows each reader to be linked not only to a Mercado Pago account, but also to a physical point of sale identified in our system.
Finally, with your terminal already linked, you must activate its operating mode as Point of Sale (PDV). Follow the instructions below to correctly perform each step.
Creating stores and points of sale in Mercado Pago is necessary to operate in physical stores with Point terminals and thus maintain reconciliation between your point of sale and Mercado Pago.
A store represents a physical store within Mercado Pago, which can have one or more associated points of sale. However, each point of sale only allows one associated terminal in PDV mode. This means that if you want to integrate more than one terminal, you must create the same number of points of sale and perform their association individually.
The creation and subsequent configuration of stores and points of sale can be done through two ways: through the Mercado Pago panel, or via API. The latter option is useful for systems that need to operate with multiple points of sale, as it allows associating multiple stores from the integrating system.
Choose the way that best suits your needs and follow the detailed steps as appropriate.
It is possible to create stores and points of sale from your system through our APIs for in-person payments. To do this, follow the steps below.
Create store
To create a store via API, send a POST with the Access Token that corresponds to your integration type (personalMercado Pago Point integrations to your system for your own use and configured using your application's production credentials. For more information, access the link below.Access credentials or for a third-partyMercado Pago Point integrations to your system on behalf of a seller and configured using credentials obtained through the OAuth security protocol. For more information, access the link below.Access credentials) to the endpoint Create storeAPI. You must add the user_id of the Mercado Pago account that will receive the money from the transactions in the path of your request and complete the required parameters with the business details as indicated below.
curl
curl -X POST \ 'https://api.mercadopago.com/users/USER_ID/stores'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "name": "Instore Store", "business_hours": { "monday": [ { "open": "08:00", "close": "12:00" } ], "tuesday": [ { "open": "09:00", "close": "18:00" } ] }, "external_id": "SUC001", "location": { "street_number": "0123", "street_name": "Example Street Name.", "city_name": "City name.", "state_name": "State name.", "latitude": 27.175193925922862, "longitude": 78.04213533235064, "reference": "Near to Mercado Pago" } }'
| Parameter | Requirement | Description and examples |
user_id | Required | Identifier of the Mercado Pago account that receives the money for sales made at the store. If you are performing your personalMercado Pago Point integrations to your system for your own use and configured using your application's production credentials. For more information, access the link below.Access credentials integration, you will find this value in the Application details. If, on the other hand, you are performing an integration for a third-partyMercado Pago Point integrations to your system on behalf of a seller and configured using credentials obtained through the OAuth security protocol. For more information, access the link below.Access credentials, you will obtain the value in the response to the linking through OAuthPrivate key generated through the OAuth security protocol, which allows managing integrations on behalf of third parties. For more information, go to the documentation.OAuth. |
name | Required | Name of the created store. |
external_id | Optional | External identifier of the store for the integrator's system. It can contain any alphanumeric value up to 60 characters, and must be unique for each store. For example, SUCMercadoPago. |
location | Required | This object must contain all data relating to the store location. You must pay particular attention to completing them correctly with the simple decimal standard, especially the latitude and longitude parameters, with the real data of the physical location. For example, "latitude": 27.175193925922862, and "longitude": 78.04213533235064 correspond to the exact location of the Taj Mahal, in India. |
If the request was sent correctly, the response will look like the example below.
json
{ "id": 1234567, "name": "Instore Store", "date_created": "2019-08-08T19:29:45.019Z", "business_hours": { "monday": [ { "open": "08:00", "close": "12:00" } ], "tuesday": [ { "open": "09:00", "close": "18:00" } ] }, "location": { "address_line": "Example Street Name, 0123, City name, State name.", "latitude": 27.175193925922862, "longitude": 78.04213533235064, "reference": "Near to Mercado Pago" }, "external_id": "SUC001" }
In addition to the data sent in the request, it will return the identifier assigned to that store by Mercado Pago under the id parameter.
Create point of sale
To be able to make sales with Mercado Pago, each created store must contain at least one associated point of sale. It is possible to create a point of sale and associate it with the previously created store by sending a POST with the Access Token that corresponds to your integration type (personalIntegrations of Mercado Pago Point to your system for personal use and configured from production credentials of your application. For more information, access the link below.Access credentials or for third partiesIntegrations of Mercado Pago Point to your system on behalf of a seller and configured from credentials obtained through the OAuth security protocol. For more information, access the link below.Access credentials) to the endpoint Create point of saleAPI as shown below.
curl
curl -X POST \ 'https://api.mercadopago.com/pos'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "name": "First POS", "store_id": 1234567, "external_store_id": "SUC001", "external_id": "SUC001POS001", "category": 621102 }'
| Parameter | Requirement | Description and examples |
name | Required | Name of the created point of sale. |
store_id | Required | Identifier of the store to which the point of sale belongs, assigned to that store by Mercado Pago. It is returned in the response to the store creation under the id parameter. |
external_store_id | Optional | External identifier of the store, which was assigned by the integrator's system at the time of its creation under the external_id parameter. |
external_id | Required | External identifier of the point of sale, defined for the integrator system. It must be a unique value for each point of sale and has a limit of 40 characters. |
category | Required | MCC code that indicates the category to which the point of sale belongs. You can consult the complete list of options in our API Reference. |
If the request was sent correctly, the response will look like the example below.
json
{ "id": 2711382, "qr": { "image": "https://www.mercadopago.com/instore/merchant/qr/2711382/0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1.png", "template_document": "https://www.mercadopago.com/instore/merchant/qr/2711382/template_0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1.pdf", "template_image": "https://www.mercadopago.com/instore/merchant/qr/2711382/template_0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1.png" }, "status": "active", "date_created": "2019-08-22T14:11:12.000Z", "date_last_updated": "2019-08-25T15:16:12.000Z", "uuid": "0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1", "user_id": 446566691, "name": "First POS", "fixed_amount": false, "category": 621102, "store_id": 1234567, "external_store_id": "SUC001", "external_id": "SUC001POS001" }
You can see in the table below the description of some of the returned parameters that may be useful for continuing with your integration later.
| Parameter | Description |
id | Identifier assigned to the point of sale by Mercado Pago. |
qr | Object that will contain a QR code associated with the created point of sale. It can only be used if you have integrated the QR Code payment solution. |
status | Status of the point of sale creation. |
user_id | Identifier of the Mercado Pago account that receives the money for sales made at the point of sale. |
name | Name assigned to the point of sale at the time of its creation. |
store_id | Identifier of the store to which the point of sale belongs, assigned to that store by Mercado Pago. It is returned in the response to the store creation under the id parameter. |
external_store_id | External identifier of the store, which was assigned by the integrator's system at the time of its creation under the external_id parameter. |
external_id | External identifier of the point of sale, defined for the integrator system at the time of its creation. |
If both requests were successful, you will have created and configured the store and point of sale necessary to continue with the configuration of your terminal in PDV mode.
The association of the Point terminal to the Mercado Pago account and the created store and point of sale must be performed from the Mercado Pago application on the mobile device of the receiving account or the one indicated as a collaborator. This application is available for Android or iOS devices.
Start by turning on the Point terminal. You will see the message "Log in to this device with your Mercado Pago account" on the screen. There you must choose between the options below.
- I am the business owner: select this option if you are the owner of the physical store.
- I am a collaborator: choose this option if your account was designated as a collaborator account by the store owner.
Once you have selected the appropriate option, a QR code will appear on the terminal screen, which you must scan with the Mercado Pago mobile application.
To do this, access the application and log in with the receiving account or the one designated as a collaborator account, as appropriate. Then, press the QR icon at the bottom and scan the code presented by the terminal.
After a few seconds, the Point terminal may request some additional configurations for the store. Follow the instructions displayed on the screen to complete all stages.
Finally, the terminal will ask you to select the store and point of sale to which you want to associate the terminal, and confirm the address of the store previously created with your Mercado Pago account. When finished, press the Confirm button.
Finally, the terminal will ask you to enter a password that will ensure its safe use. Once this process is finished, the screen will display the message "Ready! You can now charge with your Point", and you will have finished associating your terminal to the desired Mercado Pago account, and to the created store and point of sale.
As the last step in terminal configuration, and for them to be integrated with our API, it is necessary to activate the Point of Sale (PDV) operating mode.
To activate PDV mode via API for the first time, you must query the available terminals associated with your account by sending a GET with the Access Token that corresponds to your integration type (personalMercado Pago Point integrations to your system for your own use and configured using your application's production credentials. For more information, access the link below.Access credentials or for a third-partyMercado Pago Point integrations to your system on behalf of a seller and configured using credentials obtained through the OAuth security protocol. For more information, access the link below.Access credentials) to the endpoint Get terminalsAPI. We recommend filtering the search by optionally using the query params store_id and pos_id, identifiers returned in the creation of the store and point of sale, respectively.
curl
curl -X GET \ 'https://api.mercadopago.com/terminals/v1/list?limit=50&offset=1&store_id=1235456678&pos_id=1235456678'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \
This call will return a list of terminals linked to the Mercado Pago account, along with their respective associated point of sale and store, and their operating mode.
json
{ "data": { "terminals": [ { "id": "PAX_A910__SMARTPOS1234345545", "pos_id": 47792476, "store_id": "47792478", "external_pos_id": "SUC0101POS", "operating_mode": "PDV | STANDALONE | UNDEFINED" } ] }, "paging": { "total": 1, "offset": 0, "limit": 50 } }
| Parameter | Description |
terminals.id | Unique identifier of the terminal. The format in which this field is returned is "terminal type + "__" + terminal serial". For example, "PAX_A910__SMARTPOS123456789". You can identify the Point you want through the last characters of this field, which should match the serial that appears on the back label of the physical terminal. |
terminals.pos_id | Identifier of the point of sale to which the Point terminal is associated. |
terminals.store_id | Identifier of the store to which the Point terminal is associated. |
terminals.operating_mode | Operating mode in which the terminal is functioning at the time of the query. It can be: - PDV: Point of Sale (PDV) operating mode. This is the mode in which the terminal operates when integrated via API and can only receive card payments. - STANDALONE: default terminal configuration. This is the mode in which it operates when not integrated via API. - UNDEFINED: the configuration that the terminal has is not recognized. |
Since the only operating mode that allows integrating terminals via API is PDV, once you have located the desired Point terminal, you must activate it. To do this, send a PATCH with the Access Token that corresponds to your integration type (personalMercado Pago Point integrations to your system for your own use and configured using your application's production credentials. For more information, access the link below.Access credentials or for a third-partyMercado Pago Point integrations to your system on behalf of a seller and configured using credentials obtained through the OAuth security protocol. For more information, access the link below.Access credentials) to the endpoint Change operating modeAPI, as shown below.
curl
curl -X PATCH \ 'https://api.mercadopago.com/terminals/v1/setup'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "terminals": [ { "id": "PAX_A910__SMARTPOS1234345545", "operating_mode": "PDV" } ] }'
| Field | Type | Description |
terminals.id | String | Unique identifier of the terminal whose operating mode you want to modify, obtained in the request to query available terminals. You must send it following the format "terminal type + "__" + terminal serial", as in the following example: "PAX_A910__SMARTPOS123456789". |
terminals.operating_mode | String | Operating mode in which you want to configure the terminal. To integrate your terminal via API, the value must be PDV, which corresponds to the Point of Sale operating mode. |
If the request was successful, the response should return the parameter operating_mode=PDV.
json
{ "terminals": [ { "id": "PAX_A910__SMARTPOS1234345545", "operating_mode": "PDV" } ] }
To finish configuring your terminal, you must restart it and then verify that it has been applied by going to More options > Settings > Pairing mode. If you find that the pairing mode is Point of Sale (PDV), the change in operating mode was effective and you can continue integrating payment processing.