Integrar o processamento de transações
O processamento de transações com é realizado por meio da criação de orders que incluem retiradas sem uma compra associada. Ao criar uma order, o cliente poderá realizar as transações de forma presencial escaneando o código.
Existem três modelos de disponíveis para integração, definidos no momento da criação da order:
- Modelo estático: Neste modelo, um único associado ao caixa criado previamente recebe as informações de cada order gerada.
- Modelo dinâmico: Um exclusivo e de processamento único é gerado para cada transação, contendo os dados específicos da order criada.
- Modelo híbrido: Permite que a transação seja realizada tanto pelo QR estático quanto pelo dinâmico. A order é vinculada ao estático do caixa, enquanto também é gerado um QR dinâmico simultaneamente. Uma vez que a transação seja realizada com qualquer um dos dois códigos, o outro ficará automaticamente desabilitado para uso.
Esta integração permite criar, processar e cancelar orders, além de realizar reembolsos e consultar informações e atualizações de status das transações de cash-out.
Para configurar o processamento de transações de retirada de dinheiro com é necessário identificar a loja e o caixa aos quais a order será associada. Lembre-se de que tanto a loja quanto o caixa devem ter sido criados previamente.
Em seguida, você poderá criar a order para cash-out. Para isso, envie uma solicitação POST ao endpoint /v1/ordersAPI, incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, que é utilizada no backend. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Durante a integração, utilize o Access Token de teste e, ao finalizar, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros. Para mais informações, acesse a documentação.Acessar as credenciais de teste. Além disso, certifique-se de incluir o external_pos_id do caixa ao qual deseja atribuir a order, obtido na etapa 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", "config": { "qr": { "external_pos_id": "EXTERNALPOS019285", "mode": "static" } }, "transactions": { "cash_outs": [ { "amount": "50.00", "additional_info":{ "external_cashier_id": 123445 } } ] } }'
| Parâmetro | Tipo | Descrição | Obrigatoriedade |
X-Idempotency-Key | header | Chave de idempotência. Esta chave garante que cada solicitação seja processada apenas uma vez, evitando duplicidades. Utilize um valor exclusivo no header da solicitação, como um UUID (Universally Unique Identifier - Identificador Universalmente Único) V4 ou uma string aleatória. | Obrigatório |
type | string | Tipo de order, associada à solução do Mercado Pago para a qual foi criada. Para transações com do Mercado Pago, o único valor possível é qr, que é o valor associado à criação de orders para transações com do Mercado Pago. | Obrigatório |
external_reference | string | É a referência externa da order, atribuída no momento da criação. O limite máximo permitido é de 64 caracteres e os permitidos são: letras maiúsculas e minúsculas, números e os símbolos hífen (-) e sublinhado (_). O campo não pode ser utilizado para enviar dados PII. | Obrigatório |
config.qr.external_pos_id | string | Identificador externo do caixa, definido pelo integrador durante sua criação. Ao incluí-lo, a informação da order fica associada ao caixa e à loja previamente criados dentro do sistema Mercado Pago. Importante: O campo external_pos_id deve ter o mesmo valor definido como external_id na criação do seu caixa. | Obrigatório |
config.qr.mode | string | Modo de associado à order. Os valores possíveis estão listados abaixo e, se nenhum for enviado, o valor padrão será static. static: Modo estático, em que o estático associado ao caixa definido no campo external_pos_id recebe a informação da order. dynamic: Modo dinâmico, em que um único é gerado para cada transação, incluindo os dados específicos da order criada. Este código deve ser construído a partir da informação retornada no campo qr_data da resposta, cujo valor é exclusivo para cada order. hybrid: Permite que a transação seja realizada usando qualquer um dos dois modos, estático ou dinâmico, já que a order será vinculada ao estático associado ao caixa (external_pos_id), e um QR será gerado dinamicamente em paralelo. No entanto, apenas um dos QR gerados poderá ser utilizado pelo cliente. | Opcional |
transactions.cash_outs | array | Array com informações sobre as transações de retirada de dinheiro associadas à order. | Obrigatório |
transactions.cash_outs.amount | string | Valor da retirada. Pode conter dois decimais ou nenhum. Exemplo: 100.00. | Obrigatório |
transactions.cash_outs.additional_info.external_cashier_id | Number | Identificador do caixa que realiza a transação. Pode assumir qualquer valor. | Obrigatório |
A resposta varia conforme o modelo de QR escolhido para a integração. Selecione abaixo a opção que corresponde ao seu caso.
Ao criar uma order especificando o campo config.qr.mode como static, o QR que deverá ser escaneado pelo cliente é o obtido na resposta à solicitação de criação da caixa, pois é esse que receberá as informações da order criada. Se a solicitação for bem-sucedida, a resposta retornará uma order com status created.
Consulte abaixo um exemplo de resposta para uma solicitação de criação de uma order para retirada de dinheiro (cash-out) no 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" } } }
A order criada será automaticamente vinculada ao caixa especificado na solicitação, permitindo que o cliente realize a transação no ponto de venda físico. Além disso, a vinculação também facilita a conciliação. Após a transação, ela será processada de forma integrada.
id da order retornado na criação. Ele é necessário para operações futuras e para validar notificações. Consulte Recursos para mais detalhes sobre status da order e transação.O cancelamento de uma order só pode ser realizado quando seu status for created. Se a solicitação de cancelamento for feita com outro status, a API retornará um erro informando o conflito.
Para cancelar uma order, envie um POST para o endpoint /v1/orders/{order_id}/cancelAPI, incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, que é utilizada no backend. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Durante a integração, utilize o Access Token de teste e, ao finalizar, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros. Para mais informações, acesse a documentação.Acessar as credenciais de teste. Também é necessário enviar o id da order que deseja cancelar, obtido na resposta à sua criação.
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' \
Se a solicitação for bem-sucedida, a resposta incluirá o campo status com o 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" } } }
É possível reembolsar uma order criada por meio da nossa API. Neste caso, o reembolso será sempre uma devolução total do valor da order. Para efetuar o reembolso de uma order via API, ela deve estar com o status processed. Se o status for diferente, a API retornará uma mensagem de erro indicando o conflito.
Para realizar o reembolso total de uma order, envie um POST para o endpoint /v1/orders/{order_id}/refundAPI, incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, que é utilizada no backend. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Durante a integração, utilize o Access Token de teste e, ao finalizar, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros. Para mais informações, acesse a documentação.Acessar as credenciais de teste. Também é necessário informar o id da order que deseja reembolsar, obtido na resposta à sua criação.
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}}'
Se a solicitação for bem-sucedida, a resposta trará o status accredited e um novo nó transactions.refunds, que conterá os detalhes do reembolso, além do id da retirada original e o id da transação 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" } ] } }
Na resposta da solicitação de reembolso, é criada uma nova transação do tipo refund com status processing. Para acompanhar o status final do reembolso, aguarde a notificação de atualização ou consulte os dados da order para verificar seu status. Quando o reembolso for confirmado, o status será alterado para refunded.
Após a confirmação do reembolso, o status da order pode ser consultado através de uma requisição GET, conforme o exemplo abaixo:
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" } } }
O campo transaction_id no refund identifica qual transação (cash_outs) está sendo reembolsada, por isso inicia com o prefixo CAS.
É possível consultar os dados de uma order e suas transações associadas, incluindo seus status ou valores.
Para realizar a consulta, envie um GET ao endpoint /v1/orders/{order_id}API incluindo seu Access Token de testeChave privada da aplicação criada no Mercado Pago, que é utilizada no backend. Você pode acessá-la através de Suas integrações > Detalhes da aplicação > Testes > Credenciais de teste. Durante a integração, utilize o Access Token de teste e, ao finalizar, substitua-o pelo Access Token de produção se se tratar de uma integração própria, ou pelo Access Token obtido mediante OAuth no caso de integrações de terceiros. Para mais informações, acesse a documentação.Acessar as credenciais de teste. Além disso, certifique-se de incluir o id da order obtido na resposta à sua criação.
curl
curl --location --request GET 'https://api.mercadopago.com/v1/orders/ORDER_ID' \ --header 'Authorization: Bearer {{ACCESS_TOKEN}}'
Se a solicitação for bem-sucedida, a resposta retornará toda a informação da order, incluindo seu status, o status da retirada e/ou o status do reembolso em tempo 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" } } }
Após a integração do processamento de transações, você poderá configurar as notificações.