Integrar el procesamiento de pagos
El procesamiento de pagos con código QR se realiza mediante la creación de orders que incluyen una transacción de pago asociada. Al crear una order, el comprador podrá realizar el pago de forma presencial escaneando el código.
Existen tres modelos de Código QR disponibles para integración, definidos en el momento de la creación de la order:
- Modelo estático: En este modelo, un único código QR asociado a la caja creada previamente recibe la información de cada order generada.
- Modelo dinámico: Un código QR exclusivo y de pago único es generado para cada transacción, conteniendo los datos específicos de la order creada.
- Modelo híbrido: Permite que el pago se realice tanto por el QR estático como por el dinámico. La order se vincula al código QR estático de la caja, mientras que también se genera un QR dinámico simultáneamente. Una vez que se realice el pago con cualquiera de los dos códigos, el otro quedará automáticamente inhabilitado para su uso.
Esta integración permite crear, procesar y cancelar orders, además de realizar reembolsos y consultar información y actualizaciones de estado de las transacciones.
Para configurar el procesamiento de pagos con Código QR, es necesario identificar la sucursal y la caja a los que se asociará la order. Recuerda que tanto la tienda como la caja deben haber sido creados previamente.
Luego, podrás crear la order. Para ello, envía una solicitud POST al endpoint /v1/orders APIAPI, incluyendo tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Durante la integración, utiliza el Access Token de prueba y, al finalizar, 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. Para más información, dirígete a la documentación.Acceder a las credenciales de prueba. Además, asegúrate de incluir el external_pos_id de la caja a la que deseas 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 ACCESS_TOKEN' \ -d '{ "type": "qr", "total_amount": "50", "description": "Smartphone", "external_reference": "ext_ref_1234", "expiration_time": "PT16M", "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static | dynamic | hibrid" } }, "transactions": { "payments": [ { "amount": "50" } ] }, "items": [ { "title": "Smartphone", "unit_price": "50", "quantity": 1, "unit_measure": "kg", "external_code": "777489134", "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "new_total_amount": "47", "type": "account_money" } ] } }'
Consulta en la tabla debajo las descripciones de los parámetros que tienen alguna particularidad importante que debe destacarse.
| Parámetro | Tipo | Descripción | Obligatoriedad |
Authorization | header | Clave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend en ambientes de desarrollo y al momento de recibir pagos reales. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Durante el proceso de integración, utiliza el Access Token de prueba. Una vez finalizado el desarrollo y las pruebas de la integración, reemplaza el Access Token de prueba por el Access Token de producción, en caso de estar realizando una integración propia, o el Access Token obtenido por medio de OAuth, en caso de estar realizando una integración para terceros. | Obligatorio |
X-Idempotency-Key | header | Clave de idempotencia. Esta clave garantiza que cada solicitud sea procesada solo una vez, evitando duplicidades. Utiliza un valor exclusivo en el header de la solicitud, como un UUID (Universally Unique Identifier - Identificador Universalmente Único) V4 o una string aleatoria. | Obligatorio |
type | string | Tipo de order, asociada a la solución de Mercado Pago para la cual fue creada. Para pagos con Código QR de Mercado Pago, el único valor posible es qr. | Obligatorio |
total_amount | string | Valor total de la order. Representa la suma de las transacciones. No debe contener decimales. | Opcional |
description | string | Descripción del producto o servicio. El límite máximo es de 150 caracteres y no puede utilizarse para enviar datos PII. | Opcional |
external_reference | string | Es la referencia externa de la order, asignada al momento de la creación. 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 guion (-) y guion bajo (_). El campo no puede utilizarse para enviar datos PII. Además, este valor debe ser único para cada order, ya que actúa como el identificador de dicha order. | Obligatorio |
expiration_time | string | Permite especificar la fecha de vencimiento de la order; es decir, el tiempo máximo que puede estar activa. El formato válido es ISO 8601, formato de duración. Por ejemplo, "P3Y6M4DT12H30M5S" representa una duración de 3 años, 6 meses, 4 días, 12 horas, 30 minutos y 5 segundos. El tiempo mínimo que puede ser establecido es de 30 segundos, y el máximo de 3600 horas. De no ser enviado, el valor por defecto será de 15 minutos. | Opcional |
config.qr.external_pos_id | string | Identificador externo de la caja, definido por el integrador durante su creación. Al incluirlo, la información de la order queda asociada a la caja y a la tienda previamente creados dentro del sistema Mercado Pago. Importante: El campo external_pos_id debe tener el mismo valor definido como external_id en la creación de tu caja. | Obligatorio |
mode | string | Modo de código QR asociado a la order. Los valores posibles están listados abajo y, si no se envía ninguno, el valor por defecto será static. static: Modo estático, donde el código QR estático asociado a la caja definido en el campo external_pos_id recibe la información de la order. dynamic: Modo dinámico, donde un código QR único es generado para cada transacción, incluyendo los datos específicos de la order creada. Este código debe construirse a partir de la información retornada en el campo qr_data de la respuesta, cuyo valor es exclusivo para cada order. hybrid: Permite que el pago se realice usando cualquiera de los dos modos, estático o dinámico, ya que la order será vinculada al código QR estático asociado a la caja (external_pos_id), y un QR se generará dinámicamente en paralelo. Sin embargo, solo uno de los QR generados podrá ser pagado por el cliente. | Opcional |
transactions.payments | array | El nodo transactions contiene información sobre la transacción asociada a la order. Cuando el type sea qr, pueden incluirse transacciones de pago payments, que a su vez contienen información sobre la order de pago. Solo una transacción de pago puede ser enviada por order. | Obligatorio |
transactions.payments.amount | string | Valor del pago. No debe contener decimales. | Obligatorio |
La respuesta varía según el modelo de QR elegido para la integración. Selecciona abajo la opción que corresponde a tu caso.
Al crear una order especificando el campo config.qr.mode como static, el QR que deberá ser escaneado por el cliente es el obtenido en la respuesta a la solicitud de creación de la caja, pues es el que recibirá la información de la order creada. Si la solicitud es exitosa, la respuesta devolverá una order con status created.
Consulta debajo un ejemplo de respuesta para una solicitud de creación de una order para pagos con código QR estático.
json
{ "id": "ORD01K371WBFDS4MD9JG0K8ZMECBE", "type": "qr", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "description": "Smartphone", "total_amount": "50", "expiration_time": "PT16M", "country_code": "CHL", "user_id": "{{USER_ID}}", "status": "created", "status_detail": "created", "currency": "CLP", "created_date": "2025-08-21T19:32:21.621Z", "last_updated_date": "2025-08-21T19:32:21.621Z", "integration_data": { "application_id": "{{APPLICATION_ID}}" }, "transactions": { "payments": [ { "id": "PAY01K371WBFDS4MD9JG0KCV6PRKQ", "amount": "50", "status": "created", "status_detail": "ready_to_process" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "items": [ { "title": "Smartphone", "unit_price": "50", "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": "47" } ] } }
id de la order y el id del pago (transactions.payments.id) retornados en la creación. Son necesarios para futuras operaciones y para validar notificaciones. Consulta Recursos para más detalles sobre el status de la order y la transacción.La order creada será vinculada automáticamente a la caja especificada en la solicitud, permitiendo que el comprador realice el pago en el punto de venta físico. Además, esta vinculación también facilita la conciliación. Tras el pago, la transacción será procesada de forma integrada.
La cancelación de una order solo puede realizarse cuando su status es created. Si la solicitud de cancelación se realiza con otro status, la API devolverá un error informando el conflicto.
Para cancelar una order, envía un POST al endpoint /v1/orders/{order_id}/cancelAPI, incluyendo tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Durante la integración, utiliza el Access Token de prueba y, al finalizar, 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. Para más información, dirígete a la documentación.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.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders/ORD01K371WBFDS4MD9JG0K8ZMECBE/cancel'\ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \ -H 'Authorization: Bearer ACCESS_TOKEN' \
Si la solicitud es exitosa, la respuesta incluirá el campo status con el valor canceled.
json
{ "id": "ORD01K371WBFDS4MD9JG0K8ZMECBE", "type": "qr", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "description": "Smartphone", "total_amount": "50", "expiration_time": "PT16M", "country_code": "CHL", "user_id": "{{USER_ID}}", "status": "canceled", "status_detail": "canceled", "currency": "CLP", "created_date": "2025-08-21T19:32:21.621Z", "last_updated_date": "2025-08-21T19:33:52.012Z", "integration_data": { "application_id": "{{APPLICATION_ID}}" }, "transactions": { "payments": [ { "id": "PAY01K371WBFDS4MD9JG0KCV6PRKQ", "amount": "50", "status": "canceled", "status_detail": "canceled_by_api" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "items": [ { "title": "Smartphone", "unit_price": "50", "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": "47" } ] } }
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 llamada. 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 un POST al endpoint /v1/orders/{order_id}/refundAPI sin enviar body en la requisición. Asegúrate de incluir tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Durante la integración, utiliza el Access Token de prueba y, al finalizar, 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. Para más información, dirígete a la documentación.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á el status=refunded y un nuevo nodo transactions.refunds, que contendrá los detalles del reembolso, junto con el id del pago original y el id 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", "status": "processed" } ] } }
Es posible consultar los datos de una order y sus transacciones asociadas, ya sean pagos o reembolsos, incluyendo sus estados o valores.
Para realizar la consulta, envía un GET al endpoint /v1/orders/{order_id}API incluyendo tu Access Token de pruebaClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de la aplicación > Pruebas > Credenciales de prueba. Durante la integración, utiliza el Access Token de prueba y, al finalizar, 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. Para más información, dirígete a la documentación.Acceder a las credenciales de prueba. Además, asegúrate de incluir el id de la order obtenido en la respuesta a su creación.
curl
curl --location --request GET 'https://api.mercadopago.com/v1/orders/ORDER_ID' \ --header 'Authorization: Bearer {{ACCESS_TOKEN}}'
Si la solicitud es exitosa, la respuesta devolverá toda la información de la order, incluyendo su status, el status del pago y/o el status del reembolso en tiempo real.
json
{ "id": "ORD01K371WBFDS4MD9JG0K8ZMECBE", "type": "qr", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "description": "Smartphone", "total_amount": "50", "expiration_time": "PT16M", "country_code": "CHL", "user_id": "{{USER_ID}}", "status": "canceled", "status_detail": "canceled", "currency": "CLP", "created_date": "2025-08-21T19:32:21.621Z", "last_updated_date": "2025-08-21T19:33:52.012Z", "integration_data": { "application_id": "{{APPLICATION_ID}}" }, "transactions": { "payments": [ { "id": "PAY01K371WBFDS4MD9JG0K8ZMECBE", "amount": "50", "status": "canceled", "status_detail": "canceled_by_api" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "items": [ { "title": "Smartphone", "unit_price": "50", "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": "47" } ] } }
Después de la integración del procesamiento de pagos, podrás configurar las notificaciones.