Configurar terminal
Para continuar con la integración de Mercado Pago Point a tu sistema, luego de crear tu aplicación y obtener las credenciales adecuadas, es necesario que configures tu terminal Point para operar en modo integrado.
Es esta configuración la que garantiza que los pagos realizados en las terminals puedan ser gestionados desde tu sistema, optimizando la eficiencia en la conciliación y en la gestión de tareas.
Para realizar la configuración de tu terminal Point en modo integrado, primero deberás crear y configurar una sucursal y una caja, y luego asociar esa terminal a la sucursal y caja creadas. Esto permite que cada lector esté vinculado no solo a una cuenta de Mercado Pago, sino también a un punto de venta físico identificado en nuestro sistema.
Por último, con tu terminal ya vinculada, deberás activar su modo de operación. Mercado Pago Point ofrece dos modos de operación para integración vía API:
- Punto de Venta (
PDV): modo tradicional para operaciones con un encargado responsable, ideal para tiendas físicas con atención presencial. - Autoservicio (
SELF_SERVICE): modo para ambientes de autoservicio, perfecto para kioskos, tótems y puntos de venta sin vendedor, donde el cliente realiza el pago de forma independiente.
Sigue las instrucciones a continuación para realizar correctamente cada paso.
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, sea en modo PDV o SELF_SERVICE. 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.
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 de la aplicación creada en Mercado Pago, utilizada en el backend durante el desarrollo de la integración. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Al salir a producción, reemplázalo por el Access Token de producción si se trata de una integración propia, o por el Access Token obtenido mediante OAuth en el caso de integraciones de terceros.Acceder a las credenciales de prueba al endpoint Crear sucursalAPI. Deberás agregar el user_id de la cuenta de pruebaDurante el desarrollo, utiliza el User ID de la cuenta de prueba. Accede a Tus integraciones > Detalles de la aplicación > Credenciales de prueba > Datos de las credenciales de prueba y copia el User ID que se muestra. Al salir a producción, reemplázalo por el User ID de la cuenta real de Mercado Pago 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.
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 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 Detalles de aplicació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 de la aplicación creada en Mercado Pago, utilizada en el backend durante el desarrollo de la integración. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Al salir a producción, reemplázalo por el Access Token de producción si se trata de una integración propia, o por el Access Token obtenido mediante OAuth en el caso de integraciones de terceros.Acceder a las credenciales de prueba al endpoint Crear cajaAPI como se muestra a continuación.
curl
curl -X POST \ 'https://api.mercadopago.com/pos'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -d '{ "name": "Primer POS", "store_id": "12354567", "external_store_id": "SUC001", "external_id": "SUC001POS001", "category": 621102 }'
| Parámetro | Obligatoriedad | Descripción y ejemplos |
name | Obligatorio | Nombre de la caja creada. |
store_id | Obligatorio | 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 | Opcional | 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 | Obligatorio | 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. |
category | Obligatorio | Código MCC que indica el rubro al que pertenece el punto de venta. Puedes consultar la lista completa de opciones en nuestra Referencia de API. |
Si la solicitud fue enviada correctamente, la respuesta será como el ejemplo a continuación.
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": "Primer POS", "fixed_amount": false, "category": 621102, "store_id": "12354567", "external_store_id": "SUC001", "external_id": "SUC001POS001" }
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. |
qr | 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. |
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. |
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 PDV o SELF_SERVICE.
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 de la configuración de terminals, y para que estas puedan estar integradas con nuestra API, es necesario activar el modo de operación deseado. Elige entre modo PDV para atención tradicional o modo SELF_SERVICE para autoservicio, según la necesidad de tu negocio.
El modo PDV debe configurarse en modelos tradicionales de ventas, cuando la operación es conducida por un vendedor.
Para activar el modo PDV vía API por primera vez, es necesario consultar las terminals disponibles activas en tu cuenta. Para eso, envía un GET con el Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, utilizada en el backend durante el desarrollo de la integración. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Al salir a producción, reemplázalo por el Access Token de producción si se trata de una integración propia, o por el Access Token obtenido mediante OAuth en el caso de integraciones de terceros.Acceder a las credenciales de prueba al endpoint Obtener terminalsAPI. 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=12354567&pos_id=23545678'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer 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 | STANDALONE | SELF_SERVICE | UNDEFINED" } ] }, "paging": { "total": 1, "offset": 0, "limit": 50 } }
| Parámetro | Descripción |
terminals.id | Identificador único de la terminal. El formato en el que este campo es devuelto es "tipo de terminal + "__" + serial de la terminal". Por ejemplo, "NEWLAND_N950__N950NCB123456789". Podrás identificar el Point que deseas por medio de los últimos caracteres de este campo, que deberán coincidir con el serial que aparece en la etiqueta trasera de la terminal física. |
terminals.pos_id | Identificador de la caja a la que está asociada la terminal Point. |
terminals.store_id | Identificador de la sucursal a la que está asociada la terminal Point. |
terminals.operating_mode | Modo de operación en el que está funcionando la terminal al momento de la consulta. Puede ser: - PDV: modo de operación como Punto de Venta (PDV). Es el modo en el que opera la terminal cuando está integrada vía API para atención tradicional. - SELF_SERVICE: modo de operación para autoservicio. Es el modo en el que opera la terminal cuando está integrada vía API para escenarios de quiosco y tótems de autoservicio. - STANDALONE: configuración de la terminal por defecto. Es el modo en el que opera cuando no está integrada vía API. - UNDEFINED: la configuración que tiene la terminal no es reconocida. |
Para activar el modo PDV, envía un PATCH con el Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, utilizada en el backend durante el desarrollo de la integración. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Al salir a producción, reemplázalo por el Access Token de producción si se trata de una integración propia, o por el Access Token obtenido mediante OAuth en el caso de integraciones de terceros.Acceder a las credenciales de prueba al endpoint Actualizar el modo de operaciónAPI, 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 ACCESS_TOKEN' \ -d '{ "terminals": [ { "id": "NEWLAND_N950__N950NCB123456789", "operating_mode": "PDV" } ] }'
| Campo | Tipo | Descripción |
terminals.id | String | Identificador único de la terminal cuyo modo de operación se quiere modificar, obtenido en la solicitud para consultar las terminals disponibles. Debes enviarlo siguiendo el formato "tipo de terminal + "__" + serial de la terminal", como en el siguiente ejemplo: "NEWLAND_N950__N950NCB123456789". |
terminals.operating_mode | String | Modo operativo en el que quieres configurar la terminal. Para integrar tu terminal vía API para atención tradicional, el valor debe ser PDV, que corresponde al modo de operación con Punto de Venta. |
Si la solicitud fue exitosa, la respuesta deberá devolver el parámetro operating_mode=PDV.
json
{ "terminals": [ { "id": "NEWLAND_N950__N950NCB123456789", "operating_mode": "PDV" } ] }
Para finalizar la configuración de tu terminal, deberás reiniciarla y, luego, verificar que haya sido exitosa dirigiéndote a Más opciones > Configuraciones > Modo de vinculación. Si encuentras que el modo de vinculación es Punto de Venta (PDV), el cambio en el modo de operación fue efectivo y podrás continuar integrando el procesamiento de pagos.