Configurar terminal

A criação de lojas e caixas no Mercado Pago é necessária para poder operar em lojas físicas com terminals Point e assim poder manter a conciliação entre seu ponto de venda e o Mercado Pago.

Uma loja representa uma loja física dentro do Mercado Pago, que pode ter um ou mais caixas vinculados. No entanto, cada caixa permite apenas um terminal associado. Isso significa que, se você está querendo integrar mais de um terminal, deverá criar a mesma quantidade de caixas e realizar sua associação de maneira individual.

A criação e a configuração de lojas e caixas podem ser realizadas por duas vias: a partir do painel do Mercado Pago ou via API. Esta última opção é útil para sistemas que requeiram operar com vários pontos de venda, já que permite associar várias lojas a partir do sistema integrador.

Escolha a via que melhor se adeque às suas necessidades e siga os passos detalhados conforme o caso.

API

Painel do Mercado Pago

É possível criar lojas e caixas a partir do seu sistema através de nossas APIs para pagamentos presenciais. Para isso, siga os passos abaixo.

Criar loja

Para criar uma loja via API, envie um POST com o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste ao endpoint /users/{user_id}/storesPOST. Você deverá adicionar o user_id da conta de testeIdentificador numérico de uma conta de teste, utilizado para simular o vendedor durante a integração. Você pode consultá-lo junto com os dados dessa conta. Em produção, substitua-o pelo User ID da conta real que receberá os pagamentos. no path da sua solicitação e completar os parâmetros requeridos com os detalhes do negócio conforme indicado abaixo.

É fundamental preencher corretamente todas as informações de localização da loja (city_name, state_name, latitude e longitude). Dados incorretos podem causar erros nos cálculos de impostos, impactando diretamente o faturamento e a regularização fiscal da sua empresa.

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": "Loja Instore",
  "business_hours": {
    "monday": [
      {
        "open": "08:00",
        "close": "12:00"
      }
    ],
    "tuesday": [
      {
        "open": "09:00",
        "close": "18:00"
      }
    ]
  },
  "external_id": "LOJ001",
  "location": {
    "street_number": "0123",
    "street_name": "Nome da Rua de Exemplo.",
    "city_name": "Nome da cidade.",
    "state_name": "Nome do estado.",
    "latitude": 27.175193925922862,
    "longitude": 78.04213533235064,
    "reference": "Próximo ao Mercado Pago"
  }
}'

Parâmetro	Obrigatoriedade	Descrição e exemplos
user_id	Obrigatório	Identificador da conta do Mercado Pago que recebe o dinheiro pelas vendas realizadas na loja. Se você está realizando uma integração própriaIntegrações de Mercado Pago Point ao seu sistema para uso próprio e configuradas a partir de credenciais de teste da sua aplicação. Para mais informações, acesse o link abaixo.Acessar as credenciais de teste, encontrará este valor nos Dados da integração. Se, ao contrário, está realizando uma integração para para terceirosIntegrações de Mercado Pago Point ao seu sistema em nome de um vendedor e configuradas a partir de credenciais de teste obtidas por meio do protocolo de segurança OAuth. Para mais informações, acesse o link abaixo.Acessar as credenciais de teste, obterá o valor na resposta à vinculação por meio de OAuthChave privada gerada mediante o protocolo de segurança OAuth, que permite gerenciar integrações em nome de terceiros. Para mais informações, dirija-se à documentação.OAuth.
name	Obrigatório	Nome da loja criada.
external_id	Opcional	Identificador externo da loja para o sistema do integrador. Pode conter qualquer valor alfanumérico de até 60 caracteres, e deve ser único para cada loja. Por exemplo, LOJMercadoPago.
location	Obrigatório	Este objeto deve conter todas as informações da localização da loja. É importante preencher tudo corretamente, especialmente latitude e longitude, usando o formato decimal simples e os dados reais do local. Por exemplo, "latitude": 27.175193925922862, e "longitude": 78.04213533235064 correspondem à localização exata do Taj Mahal, na Índia.

Se a solicitação foi enviada corretamente, a resposta será como o exemplo a seguir.

json
{
  "id": 1234567,
  "name": "Loja Instore",
  "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": "Nome da Rua de Exemplo, 0123, Nome da cidade, Nome do estado.",
    "latitude": 27.175193925922862,
    "longitude": 78.04213533235064,
    "reference": "Próximo ao Mercado Pago"
  },
  "external_id": "LOJ001"
}

Além dos dados enviados na solicitação, retornará o identificador atribuído a essa loja pelo Mercado Pago sob o parâmetro id.

Criar caixa

Para poder realizar vendas com o Mercado Pago, cada loja criada deverá conter pelo menos um caixa associado. É possível criar um caixa e associá-lo à loja previamente criada enviando um POST com o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste ao endpoint /v2/posPOST como mostrado a seguir.

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"
}'

Parâmetro	Obrigatoriedade	Descrição e exemplos
name	Opcional	Nome do caixa, definido pelo integrador no momento da criação. São permitidos apenas caracteres alfanuméricos, hífens, underscores e espaços internos. O valor não pode começar nem terminar com espaço. O limite máximo permitido é de 45 caracteres. Se não informado, a API define automaticamente o valor de external_id como nome.
store_id	Condicional	Identificador da loja à qual pertence o caixa, atribuído pelo Mercado Pago. É retornado na resposta à criação da loja sob o parâmetro id. Obrigatório se external_store_id não for enviado. Se ambos forem enviados, devem se referir à mesma loja.
external_store_id	Condicional	Identificador externo da loja, que foi atribuído pelo sistema do integrador no momento de sua criação sob o parâmetro external_id. Obrigatório se store_id não for enviado. Se ambos forem enviados, devem se referir à mesma loja.
external_id	Opcional	Identificador externo do caixa, definido para o sistema integrador. Deve ser um valor único para cada caixa e tem um limite de 40 caracteres.

Se a solicitação foi enviada corretamente, a resposta será como o exemplo a seguir.

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"
  }
}

Você pode ver na tabela abaixo a descrição de alguns dos parâmetros retornados que podem ser úteis para continuar com sua integração mais adiante.

Parâmetro	Descrição
id	Identificador atribuído ao caixa pelo Mercado Pago.
status	Status no qual se encontra a criação do ponto de venda.
user_id	Identificador da conta do Mercado Pago que recebe o dinheiro pelas vendas realizadas no caixa.
name	Nome atribuído ao caixa no momento de sua criação.
store_id	Identificador da loja à qual pertence o caixa, atribuído a essa loja pelo Mercado Pago. É retornado na resposta à criação da loja sob o parâmetro id.
external_store_id	Identificador externo da loja, que foi atribuído pelo sistema do integrador no momento de sua criação sob o parâmetro external_id.
external_id	Identificador externo do caixa, definido para o sistema integrador no momento de sua criação.
qr_response	Objeto que conterá um código QR associado ao caixa criado. Só poderá ser utilizado caso tenha integrada a solução de pagamento Código QR. Contém os seguintes atributos: uuid: identificador único do código QR associado a este caixa. image: URL da imagem do código QR a ser utilizado para realizar as transações. template_document: URL do arquivo (em formato PDF) do template com o código QR. template_image: URL do arquivo (em formato de imagem) do template com o código QR. qr_code: string bruta do código QR que pode ser codificada em uma imagem pelo sistema integrador.

Lembre-se de que só é possível associar um terminal por caixa. Se deseja integrar vários terminals, deverá criar um caixa para cada um deles.

Se ambas as solicitações foram bem-sucedidas, você terá criado e configurado a loja e o caixa necessários para continuar com a configuração do seu terminal em modo integrado.

A associação do terminal Point à conta do Mercado Pago e à loja e caixa criados deve ser realizada a partir da aplicação do Mercado Pago no dispositivo móvel da conta recebedora ou daquela indicada como colaboradora. Esta aplicação está disponível para dispositivos Android ou iOS.

Comece ligando o terminal Point. Você verá na tela a mensagem "Inicie sessão neste dispositivo com sua conta do Mercado Pago". Ali você deverá escolher entre as opções abaixo.

• Sou responsável pelo negócio: selecione esta opção se você é o dono da loja física.
• Sou um colaborador: escolha esta opção se sua conta foi indicada como conta de colaborador pelo proprietário da loja.

Uma vez selecionada a opção que corresponda, aparecerá um código QR na tela do terminal que você deverá escanear com a aplicação móvel do Mercado Pago.

Para isso, acesse a aplicação e inicie sessão com a conta recebedora ou aquela indicada como conta de colaborador, conforme o caso. Em seguida, pressione o ícone QR na margem inferior e escaneie o código apresentado pelo terminal.

O terminal solicitará que você selecione a loja e o caixa aos quais quer associá-lo, e confirme o endereço da loja previamente criada com sua conta do Mercado Pago. Ao finalizar, pressione o botão Confirmar.

Por último, o terminal solicitará que você insira uma senha que garantirá seu uso com mais segurança. Com isso, você garante que algumas configurações e funcionalidades do terminal (como o brilho da tela e acesso a configuração da rede, por exemplo) estejam protegidas e só possam ser acessadas mediante senha.

Uma vez finalizado este processo, a tela exibirá a mensagem "Pronto! Já pode cobrar com seu Point", e você terá finalizado a associação do seu terminal à conta do Mercado Pago desejada, e à loja e caixa criados.

Como última etapa, consulte o terminal associado e ative o modo de operação correspondente à sua integração.

Antes de fazer isso, consulte os terminals disponíveis ativos em sua conta. Para isso, envie um GET ao endpoint /terminals/v1/listGET, utilizando o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste. Recomendamos o uso opcional dos parâmetros store_id e pos_id para filtrar os resultados - esses identificadores são retornados na criação da loja e do caixa, respectivamente.

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}}'

Esta chamada retornará uma lista de terminals vinculados à conta do Mercado Pago, junto com seu respectivo caixa e loja associados, e seu modo de operação.

json
{
  "data": {
    "terminals": [
      {
        "id": "NEWLAND_N950__N950NCB123456789",
        "pos_id": "23545678",
        "store_id": "12354567",
        "external_pos_id": "LOJ0101POS",
        "operating_mode": "PDV | SELF_SERVICE"
      }
    ]
  },
  "paging": {
    "total": 1,
    "offset": 0,
    "limit": 50
  }
}

Para atualizar o modo de operação, envie um PATCH com o Access Token de testeChave privada vinculada a uma aplicação, utilizada no backend para autenticar operações no ambiente de teste. Você pode consultá-la na seção Credenciais da aplicação, dentro do ambiente de teste. Ela não permite processar pagamentos reais, nunca deve ser exposta no frontend e começa com o prefixo `APP_USR`.Acessar as credenciais de teste ao endpoint /terminals/v1/setupPATCH, como mostrado a seguir.

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"
    }
  ]
}'

Se a solicitação foi bem-sucedida, a resposta retornará o modo de operação selecionado.

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

Para finalizar, reinicie o terminal. Se configurou o modo PDV, verifique se a alteração foi aplicada acessando Mais opções > Configurações > Modo de vinculação. O valor deve ser Ponto de Venda (PDV).