Integrar el procesamiento de pagos
El procesamiento de pagos con Mercado Pago Point se basa en la creación de orders asociadas a una transacción de pago. Estas orders permiten que tu sistema inicie y acompañe cada cobro procesado en la terminal, lo relacione con la operación correspondiente mediante external_reference y mantenga actualizada su conciliación a partir de los cambios de estado.
En el modo PDV, el vendedor crea una order y esta se envía automáticamente a la terminal Point indicada para que el comprador realice el pago.
En el modo SELF_SERVICE, la order se procesa en tiempo real entre el tótem utilizado por el comprador y Mercado Pago, sin intervención manual. En este modo, la terminal queda 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 la terminal debe estar configurada en modo PDV o SELF_SERVICE.
Para eso, envía una solicitud al endpoint Obtener terminalsGET, utilizando tu 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.
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 | SELF_SERVICE" } ] }, "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 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, y el ID de la terminal a la que quieres asignar la order, obtenido en el paso anterior.
La misma solicitud de creación se utiliza para los modos PDV y SELF_SERVICE. En el modo SELF_SERVICE, puedes definir cuánto tiempo permanecerá disponible cada pantalla mediante el parámetro opcional config.point.screen_time. En el modo PDV, config.point.screen_time no aplica.
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", "ticket_number": "S0392JED" }, "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 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. | 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. Puede contener dos decimales o ninguno. | Requerido |
config.point.screen_time | Body.String | Disponible únicamente en el modo SELF_SERVICE. Define, en formato ISO 8601, durante cuánto tiempo las pantallas de la terminal permanecen disponibles para procesar la order. Admite entre 5 segundos (PT5S) y 5 minutos (PT5M); si se omite, utiliza 15 segundos (PT15S). El tiempo se reinicia cuando cambia la pantalla o el usuario interactúa con la terminal. Si la order no se procesa en ese lapso, se cancela. La pantalla de lectura de la tarjeta se muestra durante un máximo de 60 segundos, aunque se configure un valor superior. | 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 terminalsGET, como en el siguiente ejemplo: NEWLAND_N950__N950NCB801293324. | Requerido |
config.point.print_on_terminal | Body.String | Define si la terminal imprime el comprobante de la transacción. En el modo PDV, admite seller_ticket —valor predeterminado— o no_ticket. En el modo SELF_SERVICE, admite seller_ticket, no_ticket o buyer_ticket —valor predeterminado—. | Opcional |
config.payment_method.default_type | Body.String | Indica el medio de pago que aceptará la terminal. Si no se envía, la terminal aceptará todos los medios de pago y el cliente podrá elegir el que desee. Para usar la preconfiguración de cuotas, es obligatorio enviarlo como credit_card. Valores posibles: debit_card (solo acepta pagos con tarjeta de débito), credit_card (solo acepta pagos con tarjeta de crédito) y qr (solo acepta pagos con código QR). En modo SELF_SERVICE, los valores admitidos son credit_card y debit_card; qr está disponible únicamente en modo PDV. | 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 a la 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, la terminal mostrará la pantalla de selección. | 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. Valores posibles: seller (el vendedor asume el costo financiero, por lo que las cuotas son sin interés; debe tener las cuotas habilitadas en su cuenta de Mercado Pago, con al menos un plan activo que incluya la cantidad de cuotas solicitada y el monto de la transacción debe alcanzar el mínimo requerido por ese plan) y buyer (el comprador asume el costo financiero, por lo que las cuotas son con interés). Si default_installments=1, envía seller u omite este campo, ya que una sola cuota no tiene costo financiero. Si default_installments es mayor que 1 y no envías este campo, la API devuelve el error 400 - missing_installments_cost. | 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": "AR", "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", "installments_cost": "seller", "default_installments": 3 } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "status": "created" } ] } }
order_id) y el ID del pago (transactions.payments.id) obtenidos al crearla, y relaciónalos con external_reference. Estos datos te permitirán realizar otras operaciones, consultar tus notificaciones y mantener la conciliación con tu sistema. Además, puedes consultar nuestra documentación en la sección Recursos para conocer los posibles status de una order y de una transacción.Una vez creada, la order será enviada a la terminal asignada.
En el modo PDV, si la order no se carga automáticamente, presiona el botón Actualizar o, si la terminal lo tiene, el botón verde para recibirla. Si no completas el parámetro expiration_time, la order expirará 15 minutos después de su creación.
En el modo SELF_SERVICE, la order se procesa sin intervención manual. Si no completas el parámetro expiration_time, la order expirará 15 segundos después de su creación. Si el comprobante de pago se imprime desde el tótem, envía no_ticket en config.point.print_on_terminal para evitar su impresión en la terminal Point.
La cancelación de una order se puede solicitar vía API o, cuando se encuentre en estado at_terminal, realizar directamente desde la terminal.
at_terminal, ya sea solicitada vía API o realizada desde la terminal, configura previamente tus notificaciones Webhooks. La notificación confirma que la cancelación se hizo efectiva y te permite mantener tu conciliación.-
Si el
statusde la order escreated, la cancelación debe realizarse vía API y se procesa de forma síncrona. -
Si su
statusesat_terminal, significa que la order ya fue obtenida por la terminal. En este caso, la cancelación puede solicitarse de forma asíncrona vía API o realizarse directamente desde la terminal.
Elige la opción que mejor se adecúe a tus necesidades para conocer cómo cancelar tu order.
Para cancelar una order con estado created o at_terminal vía API, envía una solicitud al endpoint /v1/orders/{order_id}/cancelPOST, incluyendo tu 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 y el ID de la order obtenido en la respuesta a su creación.
x-allow-cancelable-status no se envía o tiene un valor diferente de at_terminal, la solicitud de cancelación vía API de una order en status=at_terminal devolverá el error 409 cannot_cancel_order.
Además, la funcionalidad está disponible en terminales Point Smart 1 y Point Smart 2 que tengan la versión de software actualizada a la última disponible. De lo contrario, la solicitud se tratará como si el header no se hubiera enviado y devolverá el mismo error.
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 'x-allow-cancelable-status: at_terminal' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
El resultado depende del estado de la order al momento de la solicitud:
- Para
created, la cancelación es síncrona y la API devuelveHTTP 200, con la order enstatus=canceledy el pago enstatus_detail=canceled_by_api. El headerx-allow-cancelable-statuses opcional y, cuando se envía, se ignora. - Para
at_terminal, la API acepta la solicitud de forma asíncrona y devuelveHTTP 202. La order permanece enstatus=at_terminal, mientras que el pago pasa a tenerstatus_detail=cancellation_requested, hasta que una notificación Webhook confirme la cancelación. Si el pago ya está en procesamiento, la terminal podrá priorizarlo y no completar la cancelación; por eso, la respuestaHTTP 202no debe interpretarse como la confirmación final.
Respuesta para una order en created
json{ "id": "ORD00009999222233334444555566", "user_id": "5238400195", "type": "point", "external_reference": "ext_ref_1234", "description": "Point Smart 2", "expiration_time": "PT16M", "country_code": "AR", "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", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card", "default_installments": 3, "installments_cost": "seller" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP4", "amount": "24.00", "status": "canceled", "status_detail": "canceled_by_api" } ] } }
Respuesta para una order en at_terminal
json{ "id": "ORD00009999222233334444555566", "status": "at_terminal", "status_detail": "at_terminal", "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP4", "status": "at_terminal", "status_detail": "cancellation_requested" } ] } }
La respuesta HTTP 202 solo confirma que la solicitud fue aceptada. Considera la order cancelada únicamente después de recibir la confirmación mediante las notificaciones Webhooks.
En caso de necesitarlo, es posible reembolsar una order creada mediante 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. Para el reembolso parcial, es necesario informar en el body el valor 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 el reembolso total 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 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. También es necesario informar el ID de la order (order_id) 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": "ORD00001111222233334444555566", "status": "refunded", "status_detail": "refunded", "transactions": { "refunds": [ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference_id": "12345678", "amount": "24.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 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, 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": "AR", "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", "ticket_number": "S0392JED" }, "payment_method": { "default_type": "credit_card", "default_installments": 3, "installments_cost": "seller" } }, "transactions": { "payments": [ { "id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "amount": "24.00", "refunded_amount": "24.00", "paid_amount": "24.00", "status": "refunded", "status_detail": "refunded", "reference_id": "12345678", "payment_method": { "type": "credit_card", "installments": 6, "id": "master" } } ], "refunds": [ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference_id": "12345678", "amount": "24.00", "status": "processed" } ] } }