Integrar el procesamiento de pagos
El procesamiento de pagos con Mercado Pago Point integrado a tu punto de venta se basa en la creación de orders que contienen asociada una transacción de pago. Al crear una order, esta será cargada automáticamente a la terminal indicada, y el comprador podrá realizar su pago de manera presencial.
En el modo PDV, el vendedor crea una order y esta es enviada automáticamente a la terminal Point indicada, permitiendo que el comprador realice el pago. En el caso del modo SELF-SERVICE, el procesamiento de la order ocurre en tiempo real entre el tótem utilizado por el comprador y Mercado Pago, sin necesidad de intervención manual. Además, en modo SELF_SERVICE la terminal quedará dedicada al procesamiento de pagos, con acceso restringido a configuraciones y funcionalidades avanzadas.
El procesamiento de pagos integrado con Mercado Pago Point te permitirá crear orders, procesarlas, cancelarlas o bien realizar reembolsos y consultar su información o actualizaciones de estado.
Para comenzar a procesar pagos con Point desde los puntos de venta, primero necesitas identificar a qué terminal deseas asignar la order. Recuerda que esta terminal debe haber sido configurada en modo PDV o SELF-SERVICE.
Para eso, envía un GET el endpoint Obtener lista de terminalsAPI. Utiliza tu 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 aplicación > Pruebas > Credenciales de prueba. Al pasar 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.
Recomendamos filtrar la búsqueda utilizando los query params opcionales query params store_id y pos_id, identificadores de la tienda y la caja devueltos en la respuesta a la creación de cada una.
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 TEST-232********97488-12********26f67454********f4c8b49c********9526408'
La respuesta a esta solicitud te permitirá ver las terminals asociadas a tu cuenta y seleccionar la que deseas usar para crear tu order. Podrás identificarla por medio de los últimos caracteres del campo id, que deberán coincidir con el serial de la etiqueta trasera de la terminal física.
json
{ "data": { "terminals": [ { "id": "NEWLAND_N950__N950NCB801293324", "pos_id": "23545678", "store_id": "12354567", "external_pos_id": "SUC0101POS", "operating_mode": "PDV" } ] }, "paging": { "total": 1, "offset": 0, "limit": 50 } }
Luego, deberás crear la order. Para eso, envía un POST al endpoint /v1/ordersAPI, cuidando de incluir tu 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 aplicación > Pruebas > Credenciales de prueba. Al pasar 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, y el id de la terminal a la que quieres asignar la order, obtenido en el paso anterior.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \ -H 'Authorization: Bearer TEST-232********97488-12********26f67454********f4c8b49c********9526408' \ -d '{ "type": "point", "external_reference": "ext_ref_1234", "expiration_time": "PT16M", "transactions": { "payments": [ { "amount": "24.00" } ] }, "config": { "point": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card" } }, "description": "Point Smart 2", "integration_data": { "platform_id": "dev_1234567890", "integrator_id": "dev_1234567890", "sponsor": { "id": "446566691" } } }'
Consulta en la tabla a continuación las descripciones de los parámetros que poseen alguna particularidad importante que debe destacarse.
| Atributo | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Hace referencia o bien a tu 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 aplicación > Pruebas > Credenciales de prueba. Al pasar 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, en caso de estar realizando una integración propia, o al obtenido 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. | Requerido |
X-Idempotency-Key | Header | Llave de idempotencia. Esta llave garantiza que cada solicitud sea procesada una única vez, evitando duplicidades. Utiliza un valor exclusivo en el encabezado de tu solicitud, como un UUID V4 o strings aleatorias. | Requerido |
type | Body.String | Tipo de order, asociado a la solución de Mercado Pago para la que se crea. Para pagos con Mercado Pago Point, el único valor posible es point. | Requerido |
external_reference | Body.String | Es una referencia externa de la order, asignada al momento de su creación. Debe ser un valor único para cada order, y no puede contener datos PII. El límite máximo permitido es de 64 caracteres y los permitidos son: letras mayúsculas y minúsculas, números y los símbolos de guion (-) y guion bajo (_). | Requerido |
expiration_time | Body. String | Indica el período de validez de la order de pago a partir de su creación. Durante este tiempo, la order estará habilitada para ser procesada por el cliente; si la orden no se procesa dentro del plazo especificado, expirará automáticamente y no podrá ser utilizada, siendo necesario generar una nueva order de pago para continuar. El valor mínimo permitido es 30 segundos (PT30S) y el máximo es 3 horas (PT3H). Ejemplos de uso: para una expiración de 30 segundos: "PT30S", para 10 minutos: "PT10M", y para 1 hora y 15 minutos: "PT1H15M". | Opcional |
transaction.payments.amount | Body.String | Monto total de la order de pago. El campo debe llevar obligatoriamente 2 números decimales, incluso cuando es un número entero (por ejemplo, "10.00"). | Requerido |
config.point.screen_time | Body.String | Permite especificar el tiempo durante el cual las pantallas de las terminals estarán habilitadas para procesar la order, usando el formato de duración ISO 8601 (por ejemplo: "PT1M15S" representa una duración de 1 minuto y 15 segundos, siendo el tiempo mínimo permitido de 5 segundos y el máximo de 5 minutos). Este tiempo se reinicia cada vez que cambia la pantalla o hay una interacción del usuario con la terminal. Si no configuras este campo, el valor por defecto será 15 segundos. Durante el período configurado, la order podrá ser procesada y, si no se procesa en ese lapso, será cancelada. Si quieres continuar con el pago, deberás crear una nueva order. Importante: la pantalla de lectura de la tarjeta para el pago se mostrará, como máximo, durante 60 segundos (1 minuto), independientemente de si el valor configurado en este campo es mayor a 60 segundos. | Opcional |
config.point.terminal_id | Body.String | Identificador de la terminal Point que obtendrá la order. Debes enviarlo tal cual fue devuelto en el llamado Obtener terminalsAPI, como en el siguiente ejemplo: "NEWLAND_N950__N950NCB801293324". | Requerido |
Si la solicitud fue exitosa, la respuesta devolverá una order con estado created.
json
{ "id": "ORD00001111222233334444555566", "type": "point", "user_id": "5238400195", "external_reference": "ext_ref_1234", "description": "Point Smart 2", "expiration_time": "PT16M", "processing_mode": "automatic", "country_code": "ARG", "integration_data": { "application_id": "1234567890", "platform_id": "dev_1234567890", "integrator_id": "dev_1234567890", "sponsor": { "id": "446566691" } }, "status": "created", "status_detail": "created", "created_date": "2024-09-10T14:26:42.109320977Z", "last_updated_date": "2024-09-10T14:26:42.109320977Z", "config": { "point": { "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card", } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "created" } ] }, }
id y el id del pago (transactions.payments.id) obtenidos al crearla, porque te permitirán realizar otras operaciones y consultar tus notificaciones de manera adecuada. Adicionalmente, puedes consultar nuestra documentación en la sección Recursos para conocer mejor sobre los posibles status de una order y de una transacción.Esta orden creada será recibida automáticamente por la terminal a la que fue asignada. Si la orden no se carga automáticamente en la terminal, debes presionar el botón Actualizar o, si la terminal lo tiene, el botón verde para recibir la orden. Así, el pago podrá ser realizado por el comprador en la terminal y luego procesado. Ten en cuenta que, si no completas el parámetro expiration_time, el pago debe realizarse dentro de los 15 minutos (para el modo PDV) o dentro de los 15 segundos (para el modo SELF_SERVICE) posteriores a la creación de la order. Pasado ese tiempo, la order expirará.
La cancelación de una order se puede realizar por dos vías, dependiendo del estado en el que se encuentre.
- Si el
statusde la order escreated, su cancelación debe realizarse vía API. - Si su
statusesat_terminal, significa que la order ya fue obtenida por la terminal y deberá ser cancelada desde allí.
expiration_time, si la order no es procesada en hasta 15 minutos después de su creación en el modo PDV, o en hasta 15 segundos en el modo SELF_SERVICE, su status pasará a ser expired y ya no podrás cancelarla.
Además, en el caso de cancelaciones desde la terminal, es importante tener previamente configuradas tus notificaciones Webhooks para recibir el aviso de la cancelación en tu sistema, lo que te permitirá mantener tu conciliación.
Elige la opción que mejor se adecúe a tus necesidades para conocer cómo cancelar tu order.
Si deseas cancelar una order con estado created, deberás enviar un POST al endpoint /v1/orders/{order_id}/cancelAPI, cuidando de incluir tu 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 aplicación > Pruebas > Credenciales de prueba. Al pasar 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. También es necesario enviar el id de la order cuya cancelación quieres realizar, obtenido en la respuesta a su creación.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders/ORDER_ID/cancel' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \ -H 'Authorization: Bearer ACCESS_TOKEN'
Si la solicitud fue exitosa, la respuesta mostrará un status=canceled.
json
{ "id": "ORD0000ABCD222233334444555566", "user_id": "5238400195", "type": "point", "external_reference": "ext_ref_1234", "description": "Point Smart 2", "expiration_time": "PT16M", "country_code": "ARG", "processing_mode": "automatic", "integration_data": { "application_id": "1234567890", "platform_id": "dev_1234567890", "integrator_id": "dev_1234567890", "sponsor": { "id": "446566691" } }, "status": "canceled", "status_detail": "canceled", "created_date": "2024-09-10T14:26:42.109320977Z", "last_updated_date": "2024-09-10T14:26:42.109320977Z", "config": { "point": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card", "default_installments": "6", "installments_cost": "seller" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "canceled", "status_detail": "canceled_by_api" } ] }, }
En caso de necesitarlo, es posible reembolsar una order creada a través de nuestra API. Este endpoint permite realizar la devolución total o parcial de una transacción de pago asociada a la order. Para solicitar un reembolso total, no es necesario enviar un body en la solicitud. En el caso de un reembolso parcial, es necesario informar en el body el monto a reembolsar y el identificador de la transacción.
Elige la opción que mejor se adapte a tus necesidades y sigue las instrucciones correspondientes.
Para realizar un reembolso total de una order, envía un POST al endpoint /v1/orders/{order_id}/refundAPI sin enviar el body en la solicitud. Asegúrate de incluir tu 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 aplicación > Pruebas > Credenciales de prueba. Al pasar 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. También es necesario informar el id de la order que deseas reembolsar, obtenido en la respuesta a su creación.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders/ORDER_ID/refund' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \ -H 'Authorization: Bearer ACCESS_TOKEN'
Si la solicitud fue exitosa, la respuesta mostrará un status=refunded y traerá consigo un nuevo nodo transactions.refunds, que contendrá los detalles del reembolso, junto con el identificador del pago original y de la transacción de reembolso.
json
{ "id": "ORD0000ABCD222233334444555566", "status": "refunded", "status_detail": "refunded", "transactions": { "refunds": [ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference_id": "12345678", "amount": "38.00", "status": "processed" } ] } }
Si lo necesitas, puedes consultar los datos de una order y sus transacciones asociadas, sean pagos o reembolsos, incluídos sus estados o valores.
Si bien la utilización recurrente de esta consulta vía API no es recomendada, sí puede resultar útil en caso de que requieras información adicional sobre la order.
Para consultar los datos de una order, envía un GET al endpoint /v1/orders/{order_id}API, cuidando de incluir tu 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 aplicación > Pruebas > Credenciales de prueba. Al pasar 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, además del id de la order cuya información quieres consultar, obtenido en la respuesta a su creación.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/orders/ORDER_ID' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ACCESS_TOKEN'
Si la solicitud fue exitosa, la respuesta te devolverá toda la información de la order, incluidos su estado y el estado del pago y/o del reembolso en tiempo real:
json
{ "id": "ORD00001111222233334444555566", "user_id": "5238400195", "type": "point", "external_reference": "ext_ref_1234", "processing_mode": "automatic", "description": "Point Smart 2", "expiration_time": "PT16M", "country_code": "ARG", "integration_data": { "application_id": "1234567890", "platform_id": "dev_1234567890", "integrator_id": "dev_1234567890", "sponsor": { "id": "446566691" } }, "status": "refunded", "status_detail": "refunded", "created_date": "2024-09-10T14:26:42.109320977Z", "last_updated_date": "2024-09-10T14:26:42.109320977Z", "config": { "point": { "screen_time": "PT15S", "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card", "default_installments": "6", "installments_cost": "seller" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "refunded_amount": "38.00", "tip_amount": "14.00", "paid_amount": "38.00", "status": "refunded", "status_detail": "created", "reference_id": "12345678", "payment_method": { "type": "credit_card", "installments": 1, "id": "master" } } ], "refunds": [ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference_id": "12345678", "amount": "38.00", "status": "processed" } ] }, }