Recursos para IA

Integrar o processamento de transações

O processamento de transações com código QR é realizado por meio da criação de orders que incluem transações de pagamento, seja com retiradas de dinheiro adicionais ou 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 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 a transação seja realizada 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 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 e extra-cash.

A funcionalidade de retirada de dinheiro está disponível apenas para clientes de Carteira Assessorada. Portanto, se você é vendedor e necessita dessa funcionalidade, é necessário solicitar a habilitação ao seu assessor comercial.

Criar uma order com cash-out

Para configurar o processamento de transações de retirada de dinheiro 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 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",
    "transactions": {
        "cash_outs": [
            {
                "amount": "100"
            }
        ]
    },
    "external_reference": "ExtRef_123456",
    "config": {
        "qr": {
            "external_pos_id": "POSDOC",
            "mode": "static"
        }
    }
}'

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 Código QR do Mercado Pago, o único valor possível é qr, que é o valor associado à criação de orders para transações com Código QR 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 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 a transação seja realizada 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 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. Não deve conter decimais.	Obrigatório

Para mais detalhes sobre os parâmetros que devem ser enviados nesta solicitação, consulte nossa Referência de API.

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.

Durante o desenvolvimento da integração, é possível escanear os códigos QR gerados utilizando o aplicativo do Mercado Pago, acessando-o com uma conta de teste de comprador. Para mais informações, consulte a documentação Testar a integração.

json
{
  "id": "ORD01JYHP5MGKC5PMPZBHSTMLNDQX",
  "type": "qr",
  "processing_mode": "automatic",
  "external_reference": "ExtRef_123456",
  "total_amount": "100",
  "expiration_time": "PT15M",
  "country_code": "CHL",
  "user_id": "1898180000",
  "status": "created",
  "status_detail": "created",
  "currency": "CLP",
  "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",
        "status": "created",
        "status_detail": "ready_to_process"
      }
    ]
  },
  "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.

Armazene o 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.

Criar uma order com pagamento

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 pagamento. 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,
  "description": "Smartphone",
  "external_reference": "ext_ref_1234",
  "config": {
    "qr": {
      "external_pos_id": "STORE001POS001",
      "mode": "static"
    }
  },
  "transactions": {
    "payments": [
      {
        "amount": 50
      }
    ]
  },
  "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
      }
    ]
  }
}'

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 Código QR do Mercado Pago, o único valor possível é qr, que é o valor associado à criação de orders para transações com Código QR do Mercado Pago.	Obrigatório
`total_amount`	string	Valor total da order. Representa a soma das transações. Não deve conter decimais.	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.	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 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 a transação seja realizada 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 utilizado pelo cliente.	Opcional
`transactions.payments`	array	Array com informações sobre as transações de pagamento associadas à order.	Obrigatório
`transactions.payments.amount`	string	Valor do pagamento. Não deve conter decimais.	Obrigatório

Para mais detalhes sobre os parâmetros que devem ser enviados nesta solicitação, consulte nossa Referência de API.

A resposta varia conforme o modelo de QR escolhido para a integração. Selecione abaixo a opção que corresponde ao seu caso.

Confira abaixo um exemplo de resposta para uma solicitação de criação de uma order para pagamentos no modelo 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": "240424235",
  "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": "147632494144930"
  },
  "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"
      }
    ]
  }
}

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.

Armazene o 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.

Criar uma order com extra-cash

Para configurar o processamento de transações combinadas (pagamento + retirada) 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 extra-cash. 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.

Quando a order criada contém retiradas de dinheiro e pagamentos, o valor do campo discounts.payment_methods.new_total_amount deve ser a soma do valor do cash_out mais o valor do payment com o desconto aplicado, e não pode ser menor ou igual ao valor do cash_out.

Para criar uma order extra-cash, você deve incluir ambas as transações (cash_outs e payments) na solicitação, conforme o seguinte exemplo:

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": "140.00",
  "transactions": {
    "cash_outs": [
      {
        "amount": "110.00"
      }
    ],
    "payments": [
      {
        "amount": "30.00"
      }
    ]
  },
  "external_reference": "ExtRef_123456",
  "config": {
    "qr": {
      "external_pos_id": "POSDOC",
      "mode": "static"
    }
  },
  "description": "Description test",
  "items": [
    {
      "title": "Item test",
      "unit_price": "30.00",
      "quantity": 1,
      "unit_measure": "unit",
      "external_code": "1234567"
    }
  ]
}'

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 Código QR do Mercado Pago, o único valor possível é qr, que é o valor associado à criação de orders para transações com Código QR do Mercado Pago.	Obrigatório
`total_amount`	string	Valor total da order. Representa a soma das transações, portanto, deve ser a soma do valor do `cash_out` mais o valor do `payment`. Não deve conter decimais.	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 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 a transação seja realizada 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 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. Não deve conter decimais.	Obrigatório
`transactions.payments`	array	Array com informações sobre as transações de pagamento associadas à order.	Obrigatório
`transactions.payments.amount`	string	Valor do pagamento. Não deve conter decimais.	Obrigatório
`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
`items`	array	Array com informações sobre os itens da order.	Opcional

Para mais detalhes sobre os parâmetros que devem ser enviados nesta solicitação, consulte nossa Referência de API.

Consulte abaixo um exemplo de resposta para uma solicitação de criação de uma order extra-cash (combinando pagamento e retirada).

json
{
  "id": "ORD01JYHP5MGKC5PMPZBHSTMLNDQX",
  "type": "qr",
  "processing_mode": "automatic",
  "external_reference": "ExtRef_123456",
  "total_amount": "140",
  "expiration_time": "PT15M",
  "country_code": "CHL",
  "user_id": "1898180000",
  "status": "created",
  "status_detail": "created",
  "currency": "CLP",
  "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": "110",
        "status": "created",
        "status_detail": "ready_to_process"
      }
    ],
    "payments": [
      {
        "id": "PAY01JYHP5MGKC5PMPZBHSW42LLPA",
        "amount": "30",
        "status": "created",
        "status_detail": "ready_to_process"
      }
    ]
  },
  "config": {
    "qr": {
      "external_pos_id": "POSDOC",
      "mode": "static"
    }
  },
  "description": "Description test",
  "items": [
    {
      "title": "Item test",
      "unit_price": "30",
      "quantity": 1,
      "unit_measure": "unit",
      "external_code": "1234567"
    }
  ]
}

Cancelar order

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 POST 'https://api.mercadopago.com/v1/orders/ORD01JYHP5MGKC5PMPZBHSTMLNDQX/cancel' \
--header 'X-Idempotency-Key: 42979d9d-ef66-453b-89b7-1d6f3efc6597' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}'

Se a solicitação for bem-sucedida, a resposta incluirá o campo status com o valor canceled.

json
{
  "id": "ORD01JYHV71X1XAE89DGDBJ93AYAM",
  "type": "qr",
  "processing_mode": "automatic",
  "external_reference": "ER_123456",
  "total_amount": "100.00",
  "expiration_time": "PT15M",
  "country_code": "URY",
  "user_id": "1898180608",
  "status": "canceled",
  "status_detail": "canceled",
  "currency": "UYU",
  "created_date": "2025-06-24T20:49:01.638Z",
  "last_updated_date": "2025-06-24T20:49:10.303Z",
  "integration_data": {
    "application_id": "8950412930771472"
  },
  "transactions": {
    "cash_outs": [
      {
        "id": "CAS01JYHV71X1XAE89DGDBMXPJQD6",
        "amount": "100.00",
        "status": "canceled",
        "status_detail": "canceled_by_api"
      }
    ]
  },
  "config": {
    "qr": {
      "external_pos_id": "SUC001POS001",
      "mode": "static"
    }
  }
}

Reembolsar uma order

É 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.

Uma order poderá ser reembolsada via API até 180 dias após a realização da transação. Após esse período, não será possível efetuar a devolução.

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 processed e um novo nó transactions.refunds, que conterá os detalhes do reembolso, além do id da transação 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 estorno, o status da order pode ser consultado através da 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"
      }
    ],
    "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 (payments ou cash_outs) está sendo reembolsada. Se identificar uma transação de pagamento, o valor começará com o prefixo PAY, e se identificar uma transação de retirada, o valor começará com o prefixo CAS.

Consultar dados de uma order

É possível consultar os dados de uma order e suas transações associadas, sejam pagamentos, retiradas 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}}'

Esta solicitação está disponível apenas para orders criadas há menos de 3 meses. Para acessar informações de orders mais antigas, é necessário contatar nosso atendimento ao cliente.

Se a solicitação for bem-sucedida, a resposta retornará toda a informação da order, incluindo seu status, o status das transações 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": "CHL",
  "user_id": "1898180608",
  "status": "created",
  "status_detail": "created",
  "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"
      }
    ]
  },
  "config": {
    "qr": {
      "external_pos_id": "SUC001POS001",
      "mode": "static"
    }
  }
}

Após a integração do processamento de transações, você poderá configurar as notificações.

Create store and POS

Configure notifications

Documentação

Começando agora?

Recursos

Suporte

Comunidade

Integrar o processamento de transações

Navegação

Recursos e Comunidade

Mercado Pago

País e idioma