Configure terminal
To continue with the integration of Mercado Pago Point to your system, after creating your application and obtaining 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. Mercado Pago Point offers two operating modes for API integration:
- Point of Sale (
PDV): traditional mode for operations with an attendant responsible, ideal for physical stores with in-person service. - SELF_SERVICE (
SELF_SERVICE): mode for self-service environments, perfect for kiosks, terminals, and unattended points of sale, where the customer makes the payment independently.
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 either PDV or SELF_SERVICE 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 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 test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Application details > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations.Access test credentials to the endpoint Create storeAPI. You must add the test account user_idDuring development, use the User ID from the test account. Go to Your integrations > Application details > Test credentials > Test credentials data and copy the displayed User ID. When going to production, replace it with the User ID of the real Mercado Pago account that will receive the payments. in the path of your request and complete the required parameters with the business details as indicated below.
city_name, state_name, latitude and longitude). Incorrect data can cause errors in tax calculations, directly impacting billing and fiscal compliance of your company.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": "STO001", "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 test credentials. For more information, access the link below.Access test 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 test credentials obtained through the OAuth security protocol. For more information, access the link below.Access test 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, STOMercadoPago. |
location | Required | This object must contain all information about the store location. It is important to fill everything correctly, especially latitude and longitude, using the simple decimal format and the real data of the 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": "STO001" }
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 test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Application details > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations.Access test 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": "12354567", "external_store_id": "STO001", "external_id": "STO001POS001", "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": "12354567", "external_store_id": "STO001", "external_id": "STO001POS001" }
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 or SELF_SERVICE 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.
The terminal will ask you to select the store and point of sale to which you want to associate it, 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. This way, you guarantee that some settings and functionalities of the terminal (such as screen brightness and network configuration access, for example) are protected and can only be accessed with a password.
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 desired operating mode. Choose between PDV for traditional operator-assisted service or SELF_SERVICE for self-service mode, depending on your use case.
The POS mode should be configured in traditional sales models, when the operation is conducted by an attendant.
To activate PDV mode via API for the first time, you must query the available terminals active in your account. To do this, send a GET with the test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Application details > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations.Access test credentials to the endpoint Get terminalsAPI. We recommend optionally using the store_id and pos_id parameters to filter the results - these identifiers are 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=0&store_id=12354567&pos_id=23545678'\ -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": "NEWLAND_N950__N950NCB123456789", "pos_id": "23545678", "store_id": "12354567", "external_pos_id": "STO0101POS", "operating_mode": "PDV | STANDALONE | SELF_SERVICE | 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, "NEWLAND_N950__N950NCB123456789". 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 for traditional service. - SELF_SERVICE: self-service operating mode. This is the mode in which the terminal operates when integrated via API for kiosk and totem scenarios. - 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. |
To activate PDV mode, send a PATCH with the test Access TokenPrivate key of the application created in Mercado Pago, used in the backend during integration development. You can access it in Your integrations > Application details > Tests > Test credentials. When going to production, replace it with the production Access Token if it is your own integration, or with the Access Token obtained via OAuth in the case of third-party integrations.Access test credentials to the endpoint Update operation 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": "NEWLAND_N950__N950NCB123456789", "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: "NEWLAND_N950__N950NCB123456789". |
terminals.operating_mode | String | Operating mode in which you want to configure the terminal. To integrate your terminal via API for traditional service, 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": "NEWLAND_N950__N950NCB123456789", "operating_mode": "PDV" } ] }
To finish configuring your terminal, you must restart it and then verify that it was successful 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.