Integrar o processamento de pagamentos
O processamento de pagamentos com código QR é realizado por meio da criação de orders que incluem uma transação de pagamento associada. Ao criar uma order, o comprador poderá realizar o pagamento de forma presencial escaneando o código.
Existem três modelos de Código QR disponíveis para integração, definidos no momento da criação da order:
- Modelo estático: Neste modelo, um único código QR associado ao caixa criado previamente recebe as informações de cada order gerada.
- Modelo dinâmico: Um código QR exclusivo e de pagamento único é gerado para cada transação, contendo os dados específicos da order criada.
- Modelo híbrido: Permite que o pagamento seja realizado tanto pelo QR estático quanto pelo dinâmico. A order é vinculada ao código QR estático do caixa, enquanto também é gerado um QR dinâmico simultaneamente. Uma vez que o pagamento seja realizado 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.
Para configurar o processamento de pagamentos com código QR, é 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 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 -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.00, "description": "Smartphone", "external_reference": "ext_ref_1234", "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "transactions": { "payments": [ { "amount": 50.00 } ] }, "items": [ { "title": "Smartphone", "unit_price": 50.00, "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": 47.28 } ] } }'
| 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 pagamentos com Código QR do Mercado Pago, o único valor possível é qr. | Obrigatório |
total_amount | string | Valor total da order. Representa a soma das transações. Pode conter dois decimais ou nenhum. Exemplo: 50.00. | Opcional |
description | string | Descrição do produto ou serviço. O limite máximo é de 150 caracteres e não pode ser utilizada para enviar dados PII. | Opcional |
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. Além disso, esse valor deve ser único para cada order, pois atua como identificador dessa order. | Obrigatório |
expiration_time | string | Especifica o período de validade da order no formato de duração ISO 8601 (ex.: P3Y6M4DT12H30M5S). Mínimo de 30 segundos e máximo de 3600 horas. O comportamento varia conforme o modelo de QR. O QR Dinâmico, por padrão, tem 15 minutos de validade e respeita o valor enviado. O QR Estático, por padrão, tem 10 minutos de validade e é limitado a 10 minutos, independentemente do valor enviado. O QR Híbrido segue as mesmas regras por tipo: o QR Dinâmico respeita o valor enviado, enquanto o QR Estático vinculado é sempre limitado a 10 minutos. | Opcional |
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 |
mode | string | Modo de código QR 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 código QR estático associado ao caixa definido no campo external_pos_id recebe a informação da order. dynamic: Modo dinâmico, em que um código QR ú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 o pagamento seja realizado usando qualquer um dos dois modos, estático ou dinâmico, já que a order será vinculada ao código QR 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 pago pelo cliente. | Opcional |
transactions.payments | array | O nó transactions contém informações sobre a transação associada à order. Quando o type for qr, podem ser incluídas transações de pagamento payments, que por sua vez contêm informações sobre a order de pagamento. Apenas uma transação de pagamento pode ser enviada por order. | Obrigatório |
transactions.payments.amount | string | Valor do pagamento. Pode conter dois decimais ou nenhum. Exemplo: 50.00. | 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.
Confira abaixo um exemplo de resposta para uma solicitação de criação de uma order para pagamentos com código QR estático.
json
{ "id": "ORD01K371WBFDS4MD9JG0K8ZMECBE", "type": "qr", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "description": "Smartphone", "total_amount": "50.00", "expiration_time": "PT16M", "country_code": "ARG", "user_id": "{{USER_ID}}", "status": "created", "status_detail": "created", "currency": "ARS", "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.00", "status": "created", "status_detail": "ready_to_process" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "items": [ { "title": "Smartphone", "unit_price": "50.00", "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": "47.28" } ] } }
id da order e o id do pagamento (transactions.payments.id) retornados na criação. Eles são necessários para operações futuras e para validar notificações. Consulte Recursos para mais detalhes sobre status da order e transação.A order criada será automaticamente vinculada ao caixa especificado na solicitação, permitindo que o comprador realize o pagamento no ponto de venda físico. Além disso, a vinculação também facilita a conciliação. Após o pagamento, a transação será processada de forma integrada.
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 --location --request PUT 'https://api.mercadopago.com/v1/orders/ORD01K371WBFDS4MD9JG0K8ZMECBE' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \ --data-raw '{ "status": "canceled" }'
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": "ARG", "user_id": "{{USER_ID}}", "status": "canceled", "status_detail": "canceled", "currency": "ARS", "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.00", "status": "canceled", "status_detail": "canceled_by_api" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "items": [ { "title": "Smartphone", "unit_price": "50.00", "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": "47.28" } ] } }
Caso necessário, é possível reembolsar uma order criada por meio da nossa API. Este endpoint permite realizar a devolução total ou parcial de uma transação de pagamento associada à order. Para solicitar um reembolso total, não é necessário enviar um body na requisição. Já para o reembolso parcial, é preciso informar no body o valor a ser reembolsado e o identificador da transação.
Escolha a opção que melhor se adequa às suas necessidades e siga as instruções correspondentes.
Para realizar o reembolso total de uma order, envie um POST para o endpoint /v1/orders/{order_id}/refundAPI sem enviar o body na requisição. Certifique-se de incluir 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 -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'
Se a solicitação for bem-sucedida, a resposta trará o status=refunded e um novo nó transactions.refunds, que irá conter os detalhes do reembolso, além do id do pagamento original e o id da transação de reembolso.
json
{ "id": "ORD0000ABCD222233334444555566", "status": "refunded", "status_detail": "refunded", "transactions": { "refunds": [ { "id": "REF01J67CQQH5904WDBVZEM1234D", "transaction_id": "PAY01J67CQQH5904WDBVZEM4JMEP3", "reference_id": "12345678", "amount": "38.00", "status": "processed" } ] } }
É possível consultar os dados de uma order e suas transações associadas, sejam pagamentos ou reembolsos, 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 do pagamento e/ou o status do reembolso em tempo real.
json
{ "id": "ORD01K371WBFDS4MD9JG0K8ZMECBE", "type": "qr", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "description": "Smartphone", "total_amount": "50.00", "expiration_time": "PT16M", "country_code": "ARG", "user_id": "{{USER_ID}}", "status": "canceled", "status_detail": "canceled", "currency": "ARS", "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.00", "status": "canceled", "status_detail": "canceled_by_api" } ] }, "config": { "qr": { "external_pos_id": "STORE001POS001", "mode": "static" } }, "items": [ { "title": "Smartphone", "unit_price": "50.00", "unit_measure": "kg", "external_code": "777489134", "quantity": 1, "external_categories": [ { "id": "device" } ] } ], "discounts": { "payment_methods": [ { "type": "account_money", "new_total_amount": "47.28" } ] } }
Após a integração do processamento de pagamentos, você poderá configurar as notificações.