Integrar el procesamiento de transacciones
El procesamiento de transacciones con se realiza mediante la creación de orders que incluyen retiros sin una compra asociada. Al crear una order, el cliente podrá realizar las transacciones de forma presencial escaneando el código.
Existen tres modelos de disponibles para integración, definidos en el momento de la creación de la order:
- Modelo estático: En este modelo, un único asociado a la caja creada previamente recibe la información de cada order generada.
- Modelo dinámico: Un exclusivo y de procesamiento único es generado para cada transacción, conteniendo los datos específicos de la order creada.
- Modelo híbrido: Permite que el retiro se realice tanto por el QR estático como por el dinámico. La order se vincula al estático de la caja, mientras que también se genera un QR dinámico simultáneamente. Una vez que se realice el retiro 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 de cash-out.
Para configurar el procesamiento de transacciones de retiro de dinero con es necesario identificar la sucursal y la caja a los que se asociará la order. Recuerda que tanto la sucursal como la caja deben haber sido creados previamente.
Luego, podrás crear la order para cash-out. Para ello, envía una solicitud POST al endpoint /v1/ordersAPI, 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 --location --request POST 'https://api.mercadopago.com/v1/orders' \ --header 'X-Idempotency-Key: 02ff8cd0-c4e9-4fe8-a977-6c3c2bc6336c' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \ --data '{ "type": "qr", "total_amount": "50.00", "expiration_time": "PT15M", "config": { "qr": { "external_pos_id": "EXTERNALPOS019285", "mode": "static" } }, "transactions": { "cash_outs": [ { "amount": "50.00", "additional_info":{ "external_cashier_id": 123445 } } ] } }'
| Parámetro | Tipo | Descripción | Obligatoriedad |
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 transacciones con de Mercado Pago, el único valor posible es qr, que es el valor asociado a la creación de orders para transacciones con de Mercado Pago. | Obligatorio |
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. | Obligatorio |
expiration_time | string | Especifica el período de validez de la order en formato de duración ISO 8601 (ej.: P3Y6M4DT12H30M5S). Mínimo de 30 segundos y máximo de 3600 horas. El comportamiento varía según el modelo de QR. El QR Dinámico, por defecto, tiene 15 minutos de validez y respeta el valor enviado. El QR Estático, por defecto, tiene 10 minutos de validez y está limitado a 10 minutos independientemente del valor enviado. El QR Híbrido aplica las mismas reglas por tipo: el QR Dinámico respeta el valor enviado, mientras que el QR Estático vinculado siempre está limitado a 10 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 sucursal 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 |
config.qr.mode | string | Modo de 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 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 ú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 la transacción se realice usando cualquiera de los dos modos, estático o dinámico, ya que la order será vinculada al 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 utilizado por el cliente. | Opcional |
transactions.cash_outs | array | Array con información sobre las transacciones de retiro de dinero asociadas a la order. | Obligatorio |
transactions.cash_outs.amount | string | Valor del retiro. Puede contener dos decimales o ninguno. Ejemplo: 100.00. | Obligatorio |
transactions.cash_outs.additional_info.external_cashier_id | Number | Identificador del cajero que realiza la transacción. Puede asumir cualquier valor. | 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 de la solicitud de creación de la caja, pues es ese el que recibe la información de la order creada. Si la solicitud es exitosa, la respuesta devolverá una order con status created.
Consulta abajo un ejemplo de respuesta para una solicitud de creación de una order para retiro de dinero (cash-out) en el modelo estático.
json
{ "id": "ORD01JYHP5MGKC5PMPZBHSTMLNDQX", "type": "qr", "processing_mode": "automatic", "external_reference": "ExtRef_123456", "total_amount": "100.00", "expiration_time": "PT15M", "country_code": "MX", "user_id": "1898180000", "status": "created", "status_detail": "created", "currency": "MXN", "created_date": "2025-06-24T19:20:52.429Z", "last_updated_date": "2025-06-24T19:20:52.429Z", "integration_data": { "application_id": "8950412930770000" }, "transactions": { "cash_outs": [ { "id": "CAS01JYHP5MGKC5PMPZBHSW42LLPA", "amount": "100.00", "status": "created", "status_detail": "ready_to_process", "additional_info":{ "external_cashier_id": 123445 } } ] }, "config": { "qr": { "external_pos_id": "POSDOC", "mode": "static" } } }
La order creada será automáticamente vinculada a la caja especificada en la solicitud, permitiendo que el cliente realice la transacción en el punto de venta físico. Además, la vinculación también facilita la conciliación. Tras la transacción, será procesada de forma integrada.
id de la order retornado en la creación. Es necesario para operaciones futuras y para validar notificaciones. Consulta Recursos para más detalles sobre el status de la order y la transacción.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/ORDER_ID/cancel'\ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \ -H 'Authorization: Bearer TEST-751********69209-05********101e5ea9********17b9d2fb********0424235' \
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.00", "expiration_time": "PT16M", "country_code": "MX", "user_id": "240424235", "status": "canceled", "status_detail": "canceled", "currency": "MXN", "created_date": "2025-08-21T19:32:21.621Z", "last_updated_date": "2025-08-21T19:33:52.012Z", "integration_data": { "application_id": "147632494144930", "integrator_id": "dev_1234", "platform_id": "dev_1234567890" }, "transactions": { "cash_outs": [ { "id": "CAS01JYHP5MGKC5PMPZBHSW42LLPA", "amount": "100.00", "status": "canceled", "status_detail": "canceled_by_api" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } } }
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 efectuar el reembolso de una order vía API, debe tener el status processed. Si el estado es diferente, la API devolverá un mensaje de error indicando el conflicto.
Para realizar el reembolso total de una order, envía un POST al endpoint /v1/orders/{order_id}/refundAPI, 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 informar el id de la order que deseas reembolsar, obtenido en la respuesta a su creación.
curl
curl --location --request POST 'https://api.mercadopago.com/v1/orders/ORDER_ID/refund' \ --header 'X-Idempotency-Key: 91b59be9-27b8-449f-a6bd-32dca8b424cd' \ --header 'Authorization: Bearer {{ACCESS_TOKEN}}'
Si la solicitud es exitosa, la respuesta traerá el status accredited y un nuevo nodo transactions.refunds, que contendrá los detalles del reembolso, además del id del retiro original y el id de la transacción de reembolso.
json
{ "id": "ORD01JYHREYXTR31HRB5S9Q9G8QS7", "status": "processed", "status_detail": "accredited", "transactions": { "refunds": [ { "id": "REF01JYHRNEK69845P0E6VBXKXAKK", "transaction_id": "CAS01JYHREYXTR31HRB5S9QE68G0N", "reference_id": "116228240060", "amount": "100.00", "status": "processing" } ] } }
En la respuesta de la solicitud de reembolso, se crea una nueva transacción del tipo refund con status processing. Para acompañar el estado final del reembolso, espera la notificación de actualización o consulta los datos de la order para verificar su status. Cuando el reembolso sea confirmado, el status será cambiado a refunded.
Después de la confirmación del reembolso, el estado de la order puede consultarse a través de la solicitud GET, como se muestra en el siguiente ejemplo:
json
{ "id": "ORD01JYHREYXTR31HRB5S9Q9G8QS7", "type": "qr", "processing_mode": "automatic", "external_reference": "ExtRef_123456", "total_amount": "100.00", "expiration_time": "PT15M", "country_code": "URY", "user_id": "1898180608", "status": "refunded", "status_detail": "refunded", "created_date": "2025-06-24T20:00:55.137Z", "last_updated_date": "2025-06-24T20:04:27.622Z", "integration_data": { "application_id": "8950412930771472" }, "transactions": { "cash_outs": [ { "id": "CAS01JYHREYXTR31HRB5S9QE68G0N", "reference_id": "116228240060", "amount": "100.00", "status": "refunded", "status_detail": "refunded", "additional_info":{ "external_cashier_id": 123445 } } ], "refunds": [ { "id": "REF01JYHRNEK69845P0E6VBXKXAKK", "transaction_id": "CAS01JYHREYXTR31HRB5S9QE68G0N", "reference_id": "116228240060", "amount": "100.00", "status": "processed" } ] }, "config": { "qr": { "external_pos_id": "SUC001POS001", "mode": "static" } } }
El campo transaction_id en el refund identifica qué transacción (cash_outs) está siendo reembolsada, de ahí que inicie con el prefijo CAS.
Es posible consultar los datos de una order y sus transacciones asociadas, incluyendo sus estado 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 retiro y/o el status del reembolso en tiempo real.
json
{ "id": "ORD01JYHP5MGKC5PMPZBHSTMLNDQX", "type": "qr", "processing_mode": "automatic", "external_reference": "ExtRef_123456", "total_amount": "100.00", "expiration_time": "PT15M", "country_code": "MX", "user_id": "1898180608", "status": "created", "status_detail": "created", "currency": "MXN", "created_date": "2025-06-24T19:46:02.381Z", "last_updated_date": "2025-06-24T19:46:02.381Z", "integration_data": { "application_id": "8950412930771472" }, "transactions": { "cash_outs": [ { "id": "CAS01JYHQKQ2D39PCBEK3K36G0SQD", "amount": "100.00", "status": "created", "status_detail": "ready_to_process", "additional_info":{ "external_cashier_id": 123445 } } ] }, "config": { "qr": { "external_pos_id": "SUC001POS001", "mode": "static" } } }
Después de la integración del procesamiento de transacciones, podrás configurar las notificaciones.