Configure terminal

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. 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.

API

Mercado Pago Panel

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 linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix.Access test credentials to the endpoint /users/{user_id}/storesPOST. You must add the test account user_idNumeric identifier for a test account, used to simulate the seller during the integration. You can find it with the account details. In production, replace it with the User ID of the real account that will receive the payments. in the path of your request and complete the required parameters with the business details as indicated below.

It is essential to correctly fill in all store location information (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 {{YOUR_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 Integration data. 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 linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix.Access test credentials to the endpoint /v2/posPOST as shown below.

curl
curl -X POST \
    'https://api.mercadopago.com/v2/pos'\
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    -d '{
  "name": "POS-001",
  "store_id": "1234567",
  "external_id": "STO001POS001"
}'

Parameter	Requirement	Description and examples
name	Optional	Name of the point of sale, defined by the integrator at creation time. Only alphanumeric characters, hyphens, underscores, and internal spaces are allowed. The value cannot start or end with a space. The maximum allowed limit is 45 characters. If not provided, the API automatically sets the external_id value as the name.
store_id	Conditional	Identifier of the store to which the point of sale belongs, assigned by Mercado Pago. It is returned in the store creation response under the id parameter. Required if external_store_id is not provided. If both are sent, they must refer to the same store.
external_store_id	Conditional	External identifier of the store, which was assigned by the integrator's system at the time of its creation under the external_id parameter. Required if store_id is not provided. If both are sent, they must refer to the same store.
external_id	Optional	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.

If the request was sent correctly, the response will look like the example below.

json
{
  "id": 1234567,
  "name": "POS-001",
  "status": "active",
  "date_created": "2024-01-15T10:30:00Z",
  "date_last_updated": "2024-01-15T10:30:00Z",
  "user_id": 123456,
  "store_id": "1234567",
  "external_store_id": "STO001",
  "external_id": "STO001POS001",
  "config": {
    "qr": {
      "operating_mode": "pdv"
    }
  },
  "qr_response": {
    "uuid": "0977011a027c4b4387e52069da4264deae2946af4dcc44ee98a8f1dbb376c8a1",
    "image": "https://www.mercadopago.com/instore/merchant/qr/1234567/abc123.png",
    "template_document": "https://www.mercadopago.com/instore/merchant/qr/1234567/template_abc123.pdf",
    "template_image": "https://www.mercadopago.com/instore/merchant/qr/1234567/template_abc123.png",
    "qr_code": "00020101021226940014BR.GOV.BCB.PIX2572pix-qr-h.mercadopago.com/instore/h/p/v2/abc123"
  }
}

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.
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.
qr_response	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. It contains the following attributes: uuid: unique identifier of the QR code associated with this point of sale. image: URL of the QR code image to be used to perform transactions. template_document: URL of the file (in PDF format) of the template with the QR code. template_image: URL of the file (in image format) of the template with the QR code. qr_code: raw QR code string that can be encoded into a QR image by the integrator system.

Remember that it is only possible to associate one terminal per point of sale. If you want to integrate multiple terminals, you must create a point of sale for each one of them.

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 integrated 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 final step, query the associated terminal and activate the operating mode that corresponds to your integration.

Before doing so, query the available terminals active in your account. To do this, send a GET with the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix.Access test credentials to the endpoint /terminals/v1/listGET. 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={{STORE_ID}}&pos_id={{POS_ID}}'\
    -H 'Content-Type: application/json' \
       -H 'Authorization: Bearer {{YOUR_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 | SELF_SERVICE"
      }
    ]
  },
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

To update the operating mode, send a PATCH with the test Access TokenPrivate key linked to an application, used in the backend to authenticate operations in the test environment. You can find it in the application's Credentials section, within the test environment. It cannot process real payments, must never be exposed in the frontend, and starts with the `APP_USR` prefix.Access test credentials to the endpoint /terminals/v1/setupPATCH, as shown below.

curl
curl -X PATCH \
    'https://api.mercadopago.com/terminals/v1/setup'\
    -H 'Content-Type: application/json' \
       -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
  "terminals": [
    {
      "id": "NEWLAND_N950__N950NCB123456789",
      "operating_mode": "PDV | SELF_SERVICE"
    }
  ]
}'

If the request was successful, the response will return the selected operating mode.

json
{
  "terminals": [
    {
      "id": "NEWLAND_N950__N950NCB123456789",
      "operating_mode": "PDV | SELF_SERVICE"
    }
  ]
}

To finish, restart the terminal. If you configured PDV mode, verify that the change was applied by going to More options > Settings > Pairing mode. The value must be Point of Sale (PDV).