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.
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 PDVPATCH.
Para eso, envía una solicitud al endpoint Obtener lista de terminalsGET, utilizando 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 > Datos de integració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. El Access Token de prueba comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba.
Si es necesario, puedes filtrar la búsqueda utilizando los query params opcionales store_id y pos_id, que corresponden a los identificadores de la tienda y la caja devueltos en la respuesta a la creación de cada uno.
curlcurl -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 {{YOUR_ACCESS_TOKEN}}'
La respuesta a esta solicitud mostrará las terminals asociadas a tu cuenta, lo que te permitirá seleccionar la que deseas usar para crear tu order.
La terminal puede identificarse por los últimos caracteres del campo id, que corresponden al número de serie impreso en 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 una solicitud al endpoint /v1/ordersPOST, 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 > Datos de integració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. El Access Token de prueba comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba, y el ID de la terminal a la que quieres asignar la order, obtenido en el paso anterior.
Si lo deseas, al definir tarjeta de crédito como medio de pago predeterminado (default_type=credit_card), podrás utilizar la pre-configuración de cuotas y definir el tipo de financiamiento (con o sin interés), la cantidad de cuotas y quién asumirá el costo financiero. Para activar la pre-configuración, incluye los campos default_installments e installments_cost dentro del objeto config.payment_method al crear la order.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "type": "point", "external_reference": "ext_ref_1234", "expiration_time": "PT16M", "transactions": { "payments": [ { "amount": "24.00" } ] }, "config": { "point": { "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket" }, "payment_method": { "default_type": "credit_card", "default_installments": 3, "installments_cost": "seller" } }, "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 tienen alguna particularidad importante que debe destacarse.
| Atributo | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Hace referencia 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 > Datos de integració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. El Access Token de prueba comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba. | 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 order 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 |
transactions.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.terminal_id | Body.String | Identificador de la terminal Point que obtendrá la order. Debes enviarlo tal cual fue devuelto en el llamado Obtener terminalsGET, como en el siguiente ejemplo: NEWLAND_N950__N950NCB801293324. | Requerido |
config.payment_method.default_type | Body.String | Indica el medio de pago que aceptará la terminal. Por defecto, aceptará todos los medios de pago y permitirá al cliente seleccionar el que desee. El envío de este parámetro como credit_card y de sus atributos es obligatorio al utilizar la funcionalidad de preconfiguración de cuotas. De lo contrario, los valores posibles son los siguientes: | Opcional |
config.payment_method.default_installments | Body.Integer | Cuando el medio de pago predeterminado sea tarjeta de crédito (default_type = credit_card), envía este parámetro para indicar al terminal que la cantidad de cuotas fue preseleccionada, omitiendo la pantalla de selección. Si la tarjeta utilizada para el pago no admite el número de cuotas definido, el terminal mostrará la pantalla de selección. Este recurso está disponible únicamente en los dispositivos Point Pro 2 y Point Pro 3. | Condicional |
config.payment_method.installments_cost | Body.String | Cuando el medio de pago predeterminado sea tarjeta de crédito (default_type=credit_card) y default_installments sea mayor que 1, envía este parámetro para definir quién asumirá el costo financiero de las cuotas. Si el valor predefinido es de 1 cuota (default_installments=1), este campo debe enviarse como seller u omitirse, ya que una única cuota no tiene costo financiero para el comprador (buyer). | Condicional |
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": "BRA", "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" }, "payment_method": { "default_type": "credit_card" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "created" } ] } }
order_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 order creada será recibida automáticamente por la terminal a la que fue asignada. Si la order 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 order. 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 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í.
Elige la opción que mejor se adecúe a tus necesidades para conocer cómo cancelar tu order.
Para cancelar una order vía API, envía una solicitud al endpoint /v1/orders/{order_id}/cancelPOST, 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 > Datos de integració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. El Access Token de prueba comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba. También es necesario enviar el ID de la order que deseas cancelar, obtenido en la respuesta a su creación.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/orders/{order_id}/cancel' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_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": "BRA", "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": { "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket" }, "payment_method": { "default_type": "credit_card" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "canceled", "status_detail": "canceled_by_api" } ] } }
Es posible reembolsar una order creada mediante nuestra API. En este caso, el reembolso será siempre una devolución total del valor de la order.
Para realizar el reembolso de una order, envía una solicitud al endpoint /v1/orders/{order_id}/refundPOST sin enviar 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 > Datos de integració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. El Access Token de prueba comienza con el prefijo `APP_USR`.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.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
Si la solicitud fue exitosa, la respuesta mostrará el status=refunded y un nuevo nodo transactions.refunds, que contendrá los detalles del reembolso, junto con el ID del pago original (transactions.payments.id) y el ID de la transacción de reembolso (transaction_id).
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 una solicitud al endpoint /v1/orders/{order_id}GET, 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 > Datos de integració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. El Access Token de prueba comienza con el prefijo `APP_USR`.Acceder a las credenciales de prueba, y el ID de la order (order_id) cuya información quieres consultar, obtenido en la respuesta a su creación.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_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": "BRA", "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": { "terminal_id": "NEWLAND_N950__N950NCB801293324", "print_on_terminal": "no_ticket" }, "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": 6, "id": "master" } } ], "refunds": [ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference_id": "12345678", "amount": "38.00", "status": "processed" } ] } }