Recursos para IA

Como migrar da API de Intenção de Pagamento para a API de Orders

A API de Orders unifica o processamento de pagamentos presenciais em Mercado Pago Point, oferecendo endpoints padronizados, um modelo de status mais completo e novos recursos nativos que não existiam na API de Intenção de Pagamento. Além disso, todas as novas funcionalidades do Mercado Pago serão desenvolvidas sobre a API de Orders.

A migração da integração de Mercado Pago Point da API de Intenção de Pagamento para a API de Orders envolve a atualização de endpoints e campos da requisição, a adaptação do modelo de status e o aproveitamento de novos recursos nativos, como o endpoint dedicado de reembolso. A migração não implica mudanças no fluxo de negócio: o terminal continua recebendo as orders criadas pelo backend e processando os pagamentos de forma autônoma.

Veja a seguir como realizar esta migração de forma completa.

Mapear as mudanças de endpoint

Antes de iniciar os passos de migração, consulte a tabela abaixo para ter uma visão geral de todas as mudanças de endpoint. Na API de Intenção de Pagamento, cada operação utilizava uma estrutura de URL própria com o identificador do dispositivo no path. A API de Orders consolida essas operações em endpoints padronizados e remove o {deviceid} do path em todas as operações.

Operação	API de Intenção de Pagamento	API de Orders
Listar terminais	GET /point/integration-api/devicesAPI	GET /terminals/v1/listAPI
Atualizar modo de operação do terminal	PATCH /point/integration-api/devices/{device_id}API	PATCH /terminals/v1/setupAPI
Criar intenção de pagamento vs. Criar order	POST /point/integration-api/devices/{deviceid}/payment-intentsAPI	POST /v1/ordersAPI
Obter intenção de pagamento vs. Obter order	GET /point/integration-api/payment-intents/{paymentintentid}API	GET /v1/orders/{orderid}API
Cancelar intenção de pagamento vs. Cancelar order	DELETE /point/integration-api/devices/{deviceid}/payment-intents/{paymentintentid}API	POST /v1/orders/{orderid}/cancelAPI
Reembolsar order	Não existia endpoint dedicado	POST /v1/orders/{orderid}/refundAPI

Adaptar os headers

A API de Orders introduz duas mudanças obrigatórias de headers que afetam todos os endpoints: o mecanismo de sandbox foi eliminado e um novo controle de idempotência foi introduzido. Aplique as alterações a seguir antes de testar qualquer outro recurso.

Remover o header x-test-scope

O header x-test-scope: sandbox era utilizado na API de Intenção de Pagamento para identificar requisições de teste. Na API de Orders, o mecanismo de sandbox foi reestruturado e esse header não existe mais. Remova-o de todas as requisições da integração. Para operar em ambiente de teste na API de Orders, utilize usuários de teste. Consulte a documentação de testes para mais informações.

Adicionar o header X-Idempotency-Key

O header X-Idempotency-Key é obrigatório nas operações de criação, cancelamento e reembolso de orders. Ele garante que uma requisição repetida com a mesma chave retorne o resultado original sem processar a operação novamente. Envie um UUID v4 ou string aleatória única por requisição. Operações do tipo GET não requerem este header.

Se a mesma X-Idempotency-Key for reutilizada com um body diferente, a API retornará o erro idempotency_key_already_used. Gere uma nova chave para cada operação distinta.

Atualizar a listagem e configuração de terminais

Os endpoints de terminais mudaram de URL: a listagem passa de GET /point/integration-api/devices para GET /terminals/v1/list e a atualização de modo passa de PATCH /point/integration-api/devices/{device_id} para PATCH /terminals/v1/setup. Na atualização de modo, o identificador do terminal também deixa o path e passa para o body, o que permite atualizar múltiplos terminais em uma única chamada.

Migrar a listagem de terminais

Na API de Intenção de Pagamento, os dispositivos eram retornados no array devices. Na API de Orders, passam para data.terminals. Os query params store_id, pos_id, limit e offset permanecem os mesmos. A tabela abaixo descreve as alterações no response.

API de Intenção de Pagamento	API de Orders	Descrição	Alteração
`devices[]`	`data.terminals[]`	Lista de terminais associados à conta. Na API de Intenção de Pagamento, era retornado diretamente como array em `devices`. Na API de Orders, é movido para dentro do objeto `data` e renomeado para `terminals`.	Renomeado e movido para dentro do objeto `data`.
`devices[].id`	`data.terminals[].id`	Identificador único do terminal. Os últimos caracteres coincidem com o serial na etiqueta traseira do terminal.	Mesmo conceito. O formato do ID pode variar conforme o modelo do terminal.
`devices[].pos_id`	`data.terminals[].pos_id`	Identificador da caixa associada ao terminal.	Sem alteração.
`devices[].store_id` (integer)	`data.terminals[].store_id` (string)	Identificador da loja associada ao terminal. Na API de Intenção de Pagamento, era retornado como inteiro. Na API de Orders, é retornado como string.	Muda de integer para string.
`devices[].external_pos_id`	`data.terminals[].external_pos_id`	Identificador externo de caixa, definido pelo integrador.	Sem alteração.
`devices[].operating_mode`	`data.terminals[].operating_mode`	Modo de operação do terminal. Na API de Intenção de Pagamento, os valores possíveis são `PDV` e `STANDALONE`. Na API de Orders, o valor `UNDEFINED` é adicionado para configurações não reconhecidas.	Ganha o valor `UNDEFINED` para configuração não reconhecida.
`paging.total` / `paging.offset` / `paging.limit`	`paging.total` / `paging.offset` / `paging.limit`	Dados de paginação da listagem: total de registros, ponto de início e limite.	Sem alteração.

Na listagem de terminais, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Erros não documentados na API de Orders

Os seguintes erros existem na API de Intenção de Pagamento mas não estão documentados na API de Orders.

HTTP	API de Intenção de Pagamento	Observação
`400`	`bad_request`	Parâmetro obrigatório ausente ou com formato incorreto.
`400`	`bad_request`	Formato de requisição inválido.
`403`	`forbidden`	Presente na API de Intenção de Pagamento.

Erros que permanecem iguais

Os seguintes erros têm o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
`401`	`unauthorized`	Token inválido ou expirado.
`500`	`internal_error`	Erro interno. Verifique o retorno e repita a requisição.

Migrar a atualização de modo de operação

Na API de Intenção de Pagamento, apenas um terminal podia ser atualizado por chamada e seu identificador era enviado no path. Na API de Orders, o identificador migra para o body dentro do array terminals[], o que permite atualizar múltiplos terminais em uma única chamada.

Veja a seguir um exemplo comparativo de atualização de modo de operação.

Atualização de modo de operação via API de Intenção de Pagamento. O identificador do terminal é enviado como path param.

curl
curl -X PATCH \
  'https://api.mercadopago.com/point/integration-api/devices/{{DEVICE_ID}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "operating_mode": "PDV"
  }'

Na API de Intenção de Pagamento, o response retorna apenas o campo operating_mode. Na API de Orders, o response retorna o array terminals[] com id e operating_mode, identificando cada terminal atualizado. Consulte a tabela abaixo para o mapeamento completo.

API de Intenção de Pagamento	API de Orders	Descrição	Alteração
`operating_mode`	`terminals[].operating_mode`	Modo de operação definido para o terminal. Na API de Intenção de Pagamento, era retornado como campo único. Na API de Orders, é retornado dentro do array `terminals[]`. Os valores possíveis são `PDV` e `STANDALONE`.	Passa para dentro do array `terminals[]`.

A API de Orders também introduz o seguinte campo sem equivalente na API de Intenção de Pagamento.

Campo	Descrição
`terminals[].id`	Identificador único do terminal atualizado. É retornado apenas na API de Orders.

Na atualização de modo de operação, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Erros que desaparecem

O seguinte erro existe na API de Intenção de Pagamento mas foi eliminado na API de Orders.

HTTP	API de Intenção de Pagamento	Observação
`424`	`failed_dependency`	Código eliminado na API de Orders.

Erros renomeados

O seguinte erro foi renomeado na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`403`	`forbidden`	`store_pos_not_found`	Terminal sem loja ou caixa associada.

Erros que mudam de comportamento

O seguinte erro existe em ambas as APIs mas com significado diferente na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`400`	`bad_request`	`property_value`	`device_id` ou `operating_mode` com valor inválido.

Erros que permanecem iguais

Os seguintes erros têm o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
`401`	`unauthorized`	Token inválido ou expirado.
`500`	`internal_error`	Erro interno. Verifique o retorno e repita a requisição.

Erros introduzidos pela API de Orders

Os seguintes erros não têm equivalente na API de Intenção de Pagamento.

HTTP	Erro	Observação
`400`	`unsupported_site`	Site inválido.
`400`	`required_properties`	Propriedade obrigatória ausente.
`400`	`unsupported_properties`	Campo não suportado enviado.
`400`	`invalid_payload`	Payload inválido. Verificar os campos enviados.
`403`	`terminal_not_allowed_action`	Ação não permitida para este modelo de terminal.
`404`	`not_found`	Recurso não encontrado ou ID inválido.
`412`	(sem código string)	Operação não permitida: já existe um terminal associado à caixa em modo PDV. Apenas um terminal por caixa é permitido em modo PDV.

Migrar a criação de intenções de pagamento para a criação de orders

O endpoint de criação muda de POST /point/integration-api/devices/{deviceid}/payment-intents para POST /v1/orders. Além da mudança de URL, a estrutura da requisição foi significativamente reorganizada: o identificador do terminal deixa o path e passa para o body, novos campos obrigatórios foram introduzidos e a API de Orders possui uma estrutura distinta. Siga os passos abaixo para adaptar a requisição, a resposta e o tratamento de erros.

curl
curl -X POST \
  'https://api.mercadopago.com/v1/orders' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "type": "point",
    "external_reference": "ext_ref_1234",
    "transactions": {
      "payments": [
        {
          "amount": "24.00"
        }
      ]
    },
    "config": {
      "point": {
        "terminal_id": "{{TERMINAL_ID}}",
        "print_on_terminal": "no_ticket"
      }
    },
    "description": "Point Smart 2"
  }'

Mapear os campos do body da requisição

A API de Orders possui uma estrutura distinta da API de Intenção de Pagamento: o identificador do terminal deve ser enviado no body, os campos de configuração de pagamento e impressão estão em novos nós, e os headers de identificação fazem parte do body. Os novos campos obrigatórios são type (com valor "point") e external_reference. Consulte a tabela abaixo para o mapeamento completo dos campos.

Veja a seguir um exemplo comparativo entre a criação de uma intenção de pagamento e a criação de uma order, seguido da tabela de mapeamento completo dos campos.

Requisição para criar uma intenção de pagamento. O identificador do terminal é enviado como path param e o amount é um valor inteiro.

curl
curl -X POST \
  'https://api.mercadopago.com/point/integration-api/devices/{{DEVICE_ID}}/payment-intents' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-test-scope: sandbox' \
  -d '{
    "amount": 1500,
    "additional_info": {
      "external_reference": "order-ref-001",
      "print_on_terminal": true
    },
    "description": "Produto de teste"
  }'

API de Intenção de Pagamento	API de Orders	Descrição	Alteração
`{deviceid}` (path param)	`config.point.terminal_id`	Identifica o terminal que receberá a order. Na API de Intenção de Pagamento, é enviado no path. Na API de Orders, é enviado no body no formato `{tipo_terminal}__{serial_terminal}`.	Passa de path param para campo no body.
`amount` (integer)	`transactions.payments[].amount` (string)	Montante a cobrar. Na API de Intenção de Pagamento, é representado como inteiro com dois decimais implícitos (ex.: `1500` para $15,00). Na API de Orders, é representado como string dentro do array `transactions.payments`. Aceita dois decimais (ex.: `"15.00"`) ou nenhum. Apenas 1 transação é permitida por order quando `type` é `point`.	Muda de inteiro para string e entra no array `transactions.payments`.
`additional_info.external_reference`	`external_reference`	Identificador alfanumérico da transação no sistema do integrador, retornado nas notificações de webhook. Na API de Orders, é obrigatório, com no máximo 64 caracteres, apenas letras, números, `-` e `_`. Deve ser único por order e não pode conter dados PII.	Sobe ao nível raiz e passa a ser obrigatório.
`additional_info.print_on_terminal` (boolean)	`config.point.print_on_terminal` (string)	Controla a impressão do ticket no terminal. Na API de Intenção de Pagamento, aceita os valores booleanos `true` e `false`. Na API de Orders, aceita os valores `seller_ticket` (imprime) e `no_ticket` (não imprime). Valor padrão: `seller_ticket`.	Muda de booleano para enum string.
`payment.type`	`config.payment_method.default_type`	Define o meio de pagamento aceito pelo terminal. Na API de Intenção de Pagamento, os valores possíveis são `credit_card`, `debit_card`. Na API de Orders, os valores possíveis são `credit_card`, `debit_card` e `qr`. Se não for enviado, o terminal aceita todos os meios de pagamento.	Muda de nó e passa a aceitar também `qr`.
`description`	`description`	Descreve o produto, serviço ou motivo do pagamento. Na API de Orders, aceita até 150 caracteres.	Sem alteração.
`X-platform-id` (header)	`integration_data.platform_id`	Identifica a plataforma da integração, atribuído pelo Mercado Pago. Na API de Intenção de Pagamento, era enviado como header. Na API de Orders, é enviado no body dentro de `integration_data`.	Deixa de ser header e passa para o body.
`X-integrator-id` (header)	`integration_data.integrator_id`	Identifica o integrador da integração, atribuído pelo Mercado Pago. Na API de Intenção de Pagamento, era enviado como header. Na API de Orders, é enviado no body dentro de `integration_data`.	Deixa de ser header e passa para o body.
`additional_info.ticket_number`	`config.point.ticket_number`	Valor alfanumérico para identificar o número de fatura ou ticket, impresso no terminal quando a impressão estiver habilitada.	Passa para `config.point`.

A API de Orders também introduz os seguintes campos sem equivalente na API de Intenção de Pagamento.

Campo	Descrição
`integration_data.sponsor.id`	USER_ID da conta do Mercado Pago do sistema integrador.
`type`	Tipo de order. Para Point, o único valor aceito é `"point"`. Obrigatório.
`expiration_time`	Define o tempo de validade da order desde sua criação, no formato ISO 8601. O valor mínimo é `PT30S` (30 segundos), o valor máximo é `PT3H` (3 horas) e o valor padrão é `PT15M` (15 minutos). Exemplos: `PT30S` para 30 segundos, `PT10M` para 10 minutos, `PT1H15M` para 1 hora e 15 minutos. Se a order expirar sem ser processada, ela é cancelada automaticamente. Opcional.

O formato do ID da order muda de UUID (ex.: 7f25f9aa-eea6-...) para alfanumérico (ex.: ORD00001111222233334444555566). Atualize qualquer lógica de armazenamento ou consulta que dependa do formato do ID antes de avançar.

Consulte todos os parâmetros disponíveis na Referência de APIAPI.

Adaptar os campos da resposta de criação

A tabela abaixo apresenta os campos do response de criação que existiam em ambas as APIs e sofreram alterações na migração.

API de Intenção de Pagamento	API de Orders	Descrição	Alteração
`id` (UUID)	`id` (alfanumérico)	Identificador da order criada, gerado pelo Mercado Pago. Na API de Intenção de Pagamento, é retornado no formato UUID. Na API de Orders, é retornado no formato alfanumérico com prefixo `ORD`.	Formato do ID muda para `ORD...`.
`device_id`	`config.point.terminal_id`	Identificador do terminal que recebeu a order.	Passa para `config.point`.
`amount` (integer)	`transactions.payments[].amount` (string)	Valor do pagamento. Na API de Intenção de Pagamento, é retornado como inteiro. Na API de Orders, é retornado como string decimal dentro do array de pagamentos.	Passa para o array de pagamentos.
`additional_info.external_reference`	`external_reference`	Referência externa da order no sistema do integrador.	Sobe ao nível raiz.
`additional_info.print_on_terminal` (boolean)	`config.point.print_on_terminal` (string)	Indica se o terminal imprimiu o ticket. Na API de Intenção de Pagamento, é retornado como booleano. Na API de Orders, é retornado como enum string: `seller_ticket` ou `no_ticket`.	Muda de booleano para enum string.
`additional_info.ticket_number`	`config.point.ticket_number`	Valor alfanumérico para identificar o número de fatura ou ticket, impresso no terminal quando a impressão estiver habilitada.	Passa para `config.point`.

A API de Orders também introduz os seguintes campos sem equivalente na API de Intenção de Pagamento.

Campo	Descrição
`status`	Estado atual da order. Ao criar: `created`.
`status_detail`	Detalhe do estado da order. Ao criar: `created`.
`type`	Tipo de order. Para Point: sempre `point`.
`expiration_time`	Tempo de validade da order em formato ISO 8601. Se a order expirar sem ser processada, ela é cancelada automaticamente.
`created_date` / `last_updated_date`	Registra as datas de criação e última atualização da order no formato `yyyy-MM-ddTHH:mm:ss.sssZ`.
`transactions.payments[].id`	Identificador da transação de pagamento, gerado pelo Mercado Pago. Necessário para reembolsos parciais.
`transactions.payments[].status`	Estado da transação de pagamento. Ao criar: `created`.
`user_id`	Identificador do usuário do Mercado Pago que criou a order.
`processing_mode`	Modo de processamento da order. Para Point: sempre `automatic`.
`country_code`	Identificador do site/país da aplicação.
`integration_data.application_id`	Identificador da aplicação do Mercado Pago.
`integration_data.platform_id`	Identificador da plataforma, atribuído pelo Mercado Pago.
`integration_data.integrator_id`	Identificador do integrador, atribuído pelo Mercado Pago.
`integration_data.sponsor.id`	USER_ID do sistema integrador.

Atualizar o tratamento de erros na criação

Na criação, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Erros que mudam de comportamento

Na API de Intenção de Pagamento, os seguintes erros retornavam o código genérico bad_request. Na API de Orders, são substituídos por códigos específicos.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`400`	`bad_request`	`required_properties`	Propriedade obrigatória ausente.
`400`	`bad_request`	`property_value`	Valor inválido em uma propriedade.
`400`	`bad_request`	`property_type`	Tipo incorreto. Por exemplo: integer em vez de string.
`400`	`bad_request`	`json_syntax_error`	JSON inválido.
`400`	`bad_request`	`unsupported_properties`	Propriedade não suportada enviada.

Erros renomeados

Os seguintes erros foram renomeados na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`403`	`forbidden`	`forbidden_checking_terminal_owner`	Terminal não vinculado à conta.
`409`	`conflict_error`	`already_queued_order_for_terminal`	Já existe uma order em espera para este terminal.

Erros que desaparecem

O seguinte erro existe na API de Intenção de Pagamento mas foi eliminado na API de Orders.

HTTP	API de Intenção de Pagamento	Observação
`424`	`failed_dependency`	Código eliminado na API de Orders.

Erros que permanecem iguais

O seguinte erro tem o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
`401`	`unauthorized`	Token inválido ou expirado.
`500`	`internal_error`	Erro interno. Verifique o retorno e repita a requisição.

Erros introduzidos pela API de Orders

Os seguintes erros não têm equivalente na API de Intenção de Pagamento.

HTTP	Erro	Observação
`400`	`empty_required_header`	`X-Idempotency-Key` ausente.
`400`	`minimum_properties`	Número mínimo de propriedades obrigatórias não enviado.
`400`	`minimum_items` / `maximum_items`	Número inválido de itens no array `transactions.payments`.
`409`	`idempotency_key_already_used`	Chave de idempotência reutilizada com body diferente.
`500`	`idempotency_validation_failed`	Falha na validação de idempotência. Repita a requisição.

Atualizar o mecanismo de consulta de Intenção de Pagamento para Orders

O endpoint de consulta muda de GET /point/integration-api/payment-intents/{paymentintentid}API para GET /v1/orders/{orderid}API. O identificador da order no path também muda de formato UUID para alfanumérico. O response inclui campos novos com informações sobre o resultado do pagamento, reembolsos e dados do cartão utilizado.

curl
curl -X GET \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Adaptar os campos da resposta de consulta

Além dos campos documentados na resposta de criação, a resposta do GET inclui campos adicionais relevantes para a migração. Consulte a tabela abaixo para mais detalhes.

API de Intenção de Pagamento	API de Orders	Descrição	Alteração
`state`	`status`	Estado da order. Na API de Intenção de Pagamento, campo `state` com valores em maiúsculas. Na API de Orders, campo `status` com valores em minúsculas e conjunto de estados expandido.	Renomeado. Veja o mapeamento completo em Atualizar o tratamento de status.
`payment.id` (integer)	`transactions.payments[].reference_id` (string)	Identificador do pagamento processado, disponível quando o fluxo é concluído com sucesso. Na API de Intenção de Pagamento, era retornado como inteiro em `payment.id`. Na API de Orders, é retornado como string em `transactions.payments[].reference_id`.	Identificador do pagamento processado. Muda de integer para string.

A API de Orders também introduz os seguintes campos sem equivalente na API de Intenção de Pagamento.

Campo	Descrição
`status_detail`	Detalhe do estado da order. Valores possíveis: `accredited`, `canceled_by_api`, `bad_filled_card_data`, `insufficient_amount`, entre outros. Consulte a Referência de API para a lista completa.
`transactions.payments[].paid_amount`	Valor efetivamente pago na transação.
`transactions.payments[].refunded_amount`	Valor reembolsado na transação.
`transactions.payments[].status`	Estado da transação de pagamento.
`transactions.payments[].status_detail`	Detalhe do estado da transação. Mesmos valores possíveis de `status_detail` da order.
`transactions.payments[].payment_method.type`	Meio de pagamento utilizado na transação (ex.: `credit_card`, `debit_card`).
`transactions.payments[].payment_method.installments`	Quantidade de parcelas selecionada na transação.
`transactions.payments[].payment_method.id`	Identificador do meio de pagamento ou bandeira do cartão. Consulte em GET /v1/payment_methodsAPI.
`transactions.payments[].card.first_digits` / `last_digits`	Primeiros e últimos dígitos do cartão utilizado na transação, disponíveis quando o pagamento foi feito com cartão.
`transactions.refunds[]`	Array com os dados dos reembolsos realizados na order (`id`, `transaction_id`, `reference_id`, `amount`, `status`).

Atualizar o tratamento de erros na consulta

Na consulta, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Erros que desaparecem

Os seguintes erros existem na API de Intenção de Pagamento mas não têm equivalente na API de Orders.

HTTP	API de Intenção de Pagamento	Observação
`401`	`unauthorized` (Unauthorized use of live credentials)	O header `x-test-scope` foi eliminado na API de Orders.
`403`	`forbidden`	A validação de propriedade do terminal ocorre apenas na criação.
`429`	`too_many_requests`	Presente na API de Intenção de Pagamento. Não documentado na API de Orders.

Erros renomeados

O seguinte erro foi renomeado na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`404`	`not_found`	`order_not_found`	Order não encontrada. Verificar se o ID enviado é correto.

Erros que mudam de comportamento

O seguinte erro existe em ambas as APIs mas com significado diferente na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`400`	`bad_request`	`bad_request`	Formato do `order_id` inválido. O ID muda de UUID para alfanumérico.

Erros que permanecem iguais

Os seguintes erros têm o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
`401`	`unauthorized`	Token inválido ou expirado.
`500`	`internal_error`	Erro interno. Verifique o retorno e repita a requisição.

Atualizar o tratamento de status

Uma das mudanças mais significativas entre a API de Intenção de Pagamento e a API de Orders é o campo state, que passa a se chamar status na nova API e recebe novos valores. Na API de Intenção de Pagamento, o estado FINISHED exigia chamadas adicionais para determinar o resultado real do pagamento. Na API de Orders, os status processed e failed são autocontidos e eliminam essa necessidade. Atualize todas as verificações de status da integração conforme a tabela a seguir.

Mapear os valores de status

API de Intenção de Pagamento (`state`)	API de Orders (`status`)	Observação
`OPEN`	`created`	Renomeado
`ON_TERMINAL`	`at_terminal`	Renomeado
`PROCESSING`	Absorvido	Não há estado intermediário na API de Orders
`PROCESSED`	Absorvido	Não há estado intermediário na API de Orders
`FINISHED` (pagamento aprovado)	`processed`	O resultado do pagamento aprovado está contido na própria order, sem necessidade de consultas adicionais.
`FINISHED` (pagamento recusado)	`failed`	O resultado do pagamento recusado está contido na própria order, sem necessidade de consultas adicionais.
`CONFIRMATION_REQUIRED`	`action_required`	Renomeado
`ERROR`	`failed`	Renomeado
`ABANDONED`	`expired`	Renomeado (baseado em timeout)
`CANCELED`	`canceled`	Mesmo significado. Agora em minúsculas

Na API de Intenção de Pagamento, para confirmar o resultado de um pagamento com state: FINISHED, era necessário inspecionar payment.state no webhook, chamar GET /v1/payments/{id} ou buscar pela external_reference. Na API de Orders, os status processed e failed são autocontidos: o resultado do pagamento está disponível diretamente na order, sem consultas adicionais.

A API de Orders também introduz o seguinte status sem equivalente na API de Intenção de Pagamento.

Status (API de Orders)	Observação
`refunded`	Novo status. Deve ser tratado explicitamente em todos os fluxos.

Atualizar o cancelamento de orders

O novo endpoint para cancelar uma order é POST /v1/orders/{orderid}/cancel, substituindo o DELETE da API de Intenção de Pagamento. O {deviceid} desaparece do path e o cancelamento passa a ser identificado apenas pelo {orderid}.

Na API de Intenção de Pagamento, só era possível cancelar intenções de pagamento que ainda não tinham chegado ao terminal. Na API de Orders, é possível cancelar uma order mesmo depois de ela ter chegado ao terminal, por meio de um novo header específico.

curl
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/cancel' \
  -H 'Content-Type: application/json' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Adaptar os headers de cancelamento

O response passa a retornar o objeto completo da order com status: "canceled", em vez de apenas o id. Os headers necessários nesta operação são:

Header	Obrigatoriedade	Descrição
`X-Idempotency-Key`	Obrigatório	Chave única por requisição
`x-allow-cancelable-status`	Condicional	Obrigatório para cancelar orders em `at_terminal`. Valor: `"at_terminal"`

Para cancelar orders em status at_terminal, envie o header x-allow-cancelable-status: at_terminal. Sem este header, apenas orders com status: created serão canceladas.

Atualizar o tratamento de erros no cancelamento

No cancelamento, os erros foram agrupados conforme o tipo de alteração. Consulte as tabelas abaixo para mais detalhes.

Erros que desaparecem

Os seguintes erros existem na API de Intenção de Pagamento mas não têm equivalente na API de Orders.

HTTP	API de Intenção de Pagamento	Observação
`400`	`bad_request` (deviceID format)	`deviceid` foi removido do path na API de Orders.
`429`	`too_many_requests`	Presente na API de Intenção de Pagamento. Não documentado na API de Orders.

Erros renomeados

O seguinte erro foi renomeado na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`409`	`conflict_error`	`cannot_cancel_order`	Estado da order não permite cancelamento. Para `at_terminal`, enviar `x-allow-cancelable-status: at_terminal`.

Erros que mudam de comportamento

Os seguintes erros existem em ambas as APIs mas com comportamento diferente na API de Orders.

HTTP	API de Intenção de Pagamento	API de Orders	Observação
`400`	`bad_request`	`bad_request`	Formato do `order_id` inválido. O ID muda de UUID para alfanumérico.
`404`	`101`	`order_not_found`	Order não encontrada. Na API de Intenção de Pagamento, o campo `error` usa o código numérico `"101"`.
`409`	`101`	`order_already_canceled`	Na API de Intenção de Pagamento, order inexistente e order já cancelada retornavam o mesmo erro `"101"`. Na API de Orders são diferenciados em dois erros distintos: `404` para order não encontrada e `409` para order já cancelada.
`500`	`internal_error`	`idempotency_validation_failed`	Falha na validação de idempotência. Repetir a requisição.

Erros que permanecem iguais

O seguinte erro tem o mesmo comportamento em ambas as APIs.

HTTP	Erro	Observação
`401`	`unauthorized`	Token inválido ou expirado.

Erros introduzidos pela API de Orders

Os seguintes erros não têm equivalente na API de Intenção de Pagamento.

HTTP	Erro	Observação
`400`	`empty_required_header`	`X-Idempotency-Key` ausente.
`409`	`idempotency_key_already_used`	Chave de idempotência reutilizada.

Implementar reembolsos com o endpoint dedicado

A API de Orders introduz o endpoint dedicado POST /v1/orders/{orderid}/refund para reembolsos, que não existia na API de Intenção de Pagamento. Antes, era necessário receber o webhook do pagamento, obter o payment_id e executar o reembolso pela API de Payments separadamente. Agora, o reembolso é realizado diretamente sobre a order.

Substituir o fluxo de reembolso via API de Intenção de Pagamento

Escolha entre reembolso total ou parcial de acordo com o valor a ser devolvido.

Para reembolsar o valor total da order, envie a requisição ao endpoint POST /v1/orders/{orderid}/refundAPI sem body.

curl
curl -X POST \
  'https://api.mercadopago.com/v1/orders/{{ORDER_ID}}/refund' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}'

Reembolsos são aceitos em até 90 dias a partir da data do pagamento.

Consulte todos os códigos de erro possíveis nesta operação em Erros de reembolso.

Adaptar os campos da resposta de reembolso

O response do reembolso varia conforme o tipo de operação realizada.

Campo	Tipo	Descrição
`id`	string	Identificador da order reembolsada
`status`	string	`refunded` para reembolso total. `processed` para reembolso parcial (ainda há saldo disponível)
`status_detail`	string	`refunded` para reembolso total. `partially_refunded` para reembolso parcial
`transactions.refunds[].id`	string	Identificador do reembolso, gerado pelo Mercado Pago
`transactions.refunds[].transaction_id`	string	Identificador da transação de pagamento que está sendo reembolsada
`transactions.refunds[].reference_id`	string	Identificador que associa o pagamento e seu respectivo reembolso
`transactions.refunds[].amount`	string	Valor do reembolso
`transactions.refunds[].status`	string	`processing` quando o reembolso total foi solicitado e está em processamento. `processed` quando o reembolso parcial foi concluído com sucesso

Validar a migração

Após aplicar as alterações, verifique se a integração opera corretamente em todos os fluxos antes de ir a produção.

Header x-test-scope removido

O header x-test-scope foi removido de todas as requisições da integração.

Header X-Idempotency-Key configurado

O header X-Idempotency-Key deve estar presente em todas as operações de criação, cancelamento e reembolso.

Terminais configurados

Terminais listados com o endpoint GET /terminals/v1/listAPI e modo de operação atualizado com PATCH /terminals/v1/setupAPI.

Criação de orders validada

Orders criadas com sucesso com o novo payload no endpoint POST /v1/ordersAPI e recebidas no terminal.

Consulta de orders validada

Orders consultadas com sucesso pelo endpoint GET /v1/orders/{orderid}API.

Webhook de status configurado

Status de orders monitorados via webhook com os novos valores: created, at_terminal, processed, failed, canceled e refunded.

Cancelamento de orders validado

Orders canceladas com sucesso pelo endpoint POST /v1/orders/{orderid}/cancelAPI.

Reembolsos validados

Reembolsos executados pelo endpoint dedicado POST /v1/orders/{orderid}/refundAPI.

Acesse a documentação para saber como testar a integração.

Adobe Commerce

Mercado Pago in your store

Documentação

Começando agora?

Recursos

Suporte

Parcerias

Comunidade

Como migrar da API de Intenção de Pagamento para a API de Orders

Mapear as mudanças de endpoint

Adaptar os headers

Atualizar a listagem e configuração de terminais

Migrar a criação de intenções de pagamento para a criação de orders

Atualizar o mecanismo de consulta de Intenção de Pagamento para Orders

Atualizar o tratamento de status

Atualizar o cancelamento de orders

Implementar reembolsos com o endpoint dedicado

Validar a migração

Navegação

Recursos e Comunidade

Mercado Pago

País e idioma