Configurar terminal

La creación de sucursales y cajas en Mercado Pago es necesaria para poder operar en tiendas físicas con terminals Point y así poder mantener la conciliación entre tu punto de venta y Mercado Pago.

Una sucursal representa una tienda física dentro de Mercado Pago, que puede tener una o más cajas vinculadas. Sin embargo, cada caja permite solo una terminal asociada. Esto significa que, si estás queriendo integrar más de una terminal, deberás crear la misma cantidad de cajas y realizar su asociación de manera individual.

La creación y configuración de sucursales y cajas pueden realizarse por dos vías: desde el panel de Mercado Pago o vía API. Esta última opción es útil para sistemas que requieran operar con varios puntos de venta, ya que permite asociar varias sucursales desde el sistema integrador.

Elige la vía que mejor se adecúe a tus necesidades y sigue los pasos detallados según corresponda.

API

Panel de Mercado Pago

Es posible crear sucursales y cajas desde tu sistema a través de nuestras APIs para pagos presenciales. Para eso, sigue los pasos a continuación.

Crear sucursal

Para crear una sucursal vía API, envía un POST con el Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales, nunca debe exponerse en el frontend y comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba al endpoint /users/{user_id}/storesPOST. Deberás agregar el user_id de la cuenta de pruebaIdentificador numérico de una cuenta de prueba, utilizado para simular al vendedor durante la integración. Puedes consultarlo junto con los datos de esa cuenta. En producción, reemplázalo por el User ID de la cuenta real que recibirá los pagos. en el path de tu solicitud y completar los parámetros requeridos con los detalles del negocio según se indica a continuación.

Es fundamental completar correctamente toda la información de ubicación de la sucursal (city_name, state_name, latitude y longitude). Los datos incorrectos pueden causar errores en los cálculos de impuestos, impactando directamente la facturación y la regularización fiscal de tu 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": "Sucursal Instore",
  "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": "Nombre de Calle de Ejemplo.",
    "city_name": "Nombre de ciudad.",
    "state_name": "Nombre de estado.",
    "latitude": 27.175193925922862,
    "longitude": 78.04213533235064,
    "reference": "Cerca de Mercado Pago"
  }
}'

Parámetro	Obligatoriedad	Descripción y ejemplos
user_id	Obligatorio	Identificador de la cuenta de Mercado Pago que recibe el dinero por las ventas realizadas en la sucursal. Si estás realizando una integración propiaIntegraciones de Mercado Pago Point a tu sistema para uso propio y configuradas a partir de credenciales de prueba de tu aplicación. Para más información, accede al link a continuación.Acceder a las credenciales de prueba, encontrarás este valor en los Datos de integración. Si, en cambio, estás realizando una integración para tercerosIntegraciones de Mercado Pago Point a tu sistema en nombre de un vendedor y configuradas a partir de credenciales de prueba obtenidas a través del protocolo de seguridad OAuth. Para más información, accede al link a continuación.Acceder a las credenciales de prueba, obtendrás el valor en la respuesta a la vinculación por medio de OAuthClave privada generada mediante el protocolo de seguridad OAuth, que permite gestionar integraciones en nombre de terceros. Para más información, dirígete a la documentación.OAuth.
name	Obligatorio	Nombre de la sucursal creada.
external_id	Opcional	Identificador externo de la sucursal para el sistema del integrador. Puede contener cualquier valor alfanumérico de hasta 60 caracteres, y debe ser único para cada sucursal. Por ejemplo, SUCMercadoPago.
location	Obligatorio	Este objeto debe contener toda la información de la ubicación de la sucursal. Es importante completar todo correctamente, especialmente latitude y longitude, usando el formato decimal simple y los datos reales del lugar. Por ejemplo, "latitude": 27.175193925922862, y "longitude": 78.04213533235064 corresponden a la ubicación exacta del Taj Mahal, en India.

Si la solicitud fue enviada correctamente, la respuesta será como el ejemplo a continuación.

json
{
  "id": 1234567,
  "name": "Sucursal 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": "Nombre de Calle de Ejemplo, 0123, Nombre de ciudad, Nombre de estado.",
    "latitude": 27.175193925922862,
    "longitude": 78.04213533235064,
    "reference": "Cerca de Mercado Pago"
  },
  "external_id": "SUC001"
}

Además de los datos enviados en la solicitud, devolverá el identificador asignado a esa sucursal por Mercado Pago bajo el parámetro id.

Crear caja

Para poder realizar ventas con Mercado Pago, cada sucursal creada deberá contener por lo menos una caja asociada. Es posible crear una caja y asociarla a la sucursal previamente creada enviando un POST con el Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales, nunca debe exponerse en el frontend y comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba al endpoint /v2/posPOST como se muestra a continuación.

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	Obligatoriedad	Descripción y ejemplos
name	Opcional	Nombre de la caja, definido por el integrador al momento de la creación. Solo se permiten caracteres alfanuméricos, guiones, guiones bajos y espacios internos. El valor no puede comenzar ni terminar con un espacio. El límite máximo permitido es de 45 caracteres. Si no se proporciona, la API establece automáticamente el valor de external_id como nombre.
store_id	Condicional	Identificador de la sucursal a la que pertenece la caja, asignado por Mercado Pago. Es devuelto en la respuesta a la creación de la sucursal bajo el parámetro id. Obligatorio si external_store_id no es enviado. Si se envían ambos, deben corresponder a la misma sucursal.
external_store_id	Condicional	Identificador externo de la sucursal, que le fue asignado por el sistema del integrador al momento de su creación bajo el parámetro external_id. Obligatorio si store_id no es enviado. Si se envían ambos, deben corresponder a la misma sucursal.
external_id	Opcional	Identificador externo de la caja, definido para el sistema integrador. Debe ser un valor único para cada caja y tiene un límite de 40 caracteres.

Si la solicitud fue enviada correctamente, la respuesta será como el ejemplo a continuación.

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

Puedes ver en la tabla de abajo la descripción de algunos de los parámetros devueltos que pueden ser útiles para continuar con tu integración más adelante.

Parámetro	Descripción
id	Identificador asignado a la caja por Mercado Pago.
status	Estado en el que se encuentra la creación del punto de venta.
user_id	Identificador de la cuenta de Mercado Pago que recibe el dinero por las ventas realizadas en la caja.
name	Nombre asignado a la caja al momento de su creación.
store_id	Identificador de la sucursal a la que pertenece la caja, asignado a esa sucursal por Mercado Pago. Es devuelto en la respuesta a la creación de la sucursal bajo el parámetro id.
external_store_id	Identificador externo de la sucursal, que le fue asignado por el sistema del integrador al momento de su creación bajo el parámetro external_id.
external_id	Identificador externo de la caja, definido para el sistema integrador al momento de su creación.
qr_response	Objeto que contendrá un código QR asociado a la caja creada. Solo podrá ser utilizado en caso de tener integrada la solución de pago Código QR. Contiene los siguientes atributos: uuid: identificador único del código QR asociado a esta caja. image: URL de la imagen del código QR a ser utilizado para realizar las transacciones. template_document: URL del archivo (en formato PDF) del template con el código QR. template_image: URL del archivo (en formato de imagen) del template con el código QR. qr_code: cadena cruda del código QR que puede ser codificada en una imagen por el sistema integrador.

Recuerda que solo es posible asociar una terminal por caja. Si deseas integrar varias terminals, deberás crear una caja para cada una de ellas.

Si ambas solicitudes fueron exitosas, habrás creado y configurado la sucursal y la caja necesarias para continuar con la configuración de tu terminal en modo integrado.

La asociación de la terminal Point a la cuenta de Mercado Pago y a la sucursal y caja creadas debe ser realizada desde la aplicación de Mercado Pago en el dispositivo móvil de la cuenta recaudadora o de aquella indicada como colaboradora. Esta aplicación está disponible para dispositivos Android o iOS.

Comienza encendiendo la terminal Point. Verás en la pantalla el mensaje "Inicia sesión en este dispositivo con tu cuenta de Mercado Pago". Allí deberás elegir entre las opciones a continuación.

• Soy responsable del negocio: selecciona esta opción si eres el dueño de la tienda física.
• Soy un colaborador: elige esta opción si tu cuenta fue indicada como cuenta de colaborador por el propietario de la tienda.

Una vez seleccionada la opción que corresponda, aparecerá un código QR en la pantalla de la terminal que deberás escanear con la aplicación móvil de Mercado Pago.

Para eso, accede a la aplicación e inicia sesión con la cuenta recaudadora o aquella indicada como cuenta de colaborador, según corresponda. Luego, presiona el ícono QR en el margen inferior y escanea el código presentado por la terminal.

La terminal te solicitará que selecciones la sucursal y la caja a las que quieres asociarla, y confirmes la dirección de la sucursal previamente creada con tu cuenta de Mercado Pago. Al finalizar, presiona el botón Confirmar.

Por último, la terminal te solicitará que ingreses una contraseña que garantizará su uso seguro. Así, algunas configuraciones y funcionalidades de la terminal (como el brillo de la pantalla y el acceso a la configuración de red, por ejemplo) estarán protegidas y solo se accederá a ellas mediante esta contraseña.

Una vez finalizado este proceso, la pantalla exhibirá el mensaje "¡Listo! Ya puedes cobrar con tu Point", y habrás finalizado la asociación de tu terminal a la cuenta de Mercado Pago deseada, y a la sucursal y caja creadas.

Como último paso, consulta la terminal asociada y activa el modo de operación que corresponda a tu integración.

Antes de hacerlo, consulta las terminals disponibles activas en tu cuenta. Para eso, envía un GET con el Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales, nunca debe exponerse en el frontend y comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba al endpoint /terminals/v1/listGET. Recomendamos el uso opcional de los parámetros store_id y pos_id para filtrar los resultados - estos identificadores se devuelven en la creación de la sucursal y la caja, 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 llamada devolverá una lista de terminals vinculadas a la cuenta de Mercado Pago, junto con su respectiva caja y sucursal asociadas, y su modo de operación.

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

Para actualizar el modo de operación, envía un PATCH con el Access Token de pruebaClave privada vinculada a una aplicación, utilizada en el backend para autenticar operaciones en el entorno de prueba. Puedes consultarla en la sección Credenciales de la aplicación, dentro del entorno de prueba. No permite procesar pagos reales, nunca debe exponerse en el frontend y comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba al endpoint /terminals/v1/setupPATCH, como se muestra a continuación.

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

Si la solicitud fue exitosa, la respuesta devolverá el modo de operación seleccionado.

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

Para finalizar, reinicia la terminal. Si configuraste el modo PDV, verifica que el cambio se haya aplicado en Más opciones > Configuraciones > Modo de vinculación. El valor debe ser Punto de Venta (PDV).