Recursos para IA

Como migrar da Payment Intent API para a Orders API

A Orders API 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 Payment Intent API. Além disso, todas as novas funcionalidades do Mercado Pago serão desenvolvidas sobre a Orders API.

A migração da integração de Mercado Pago Point da Payment Intent API para a Orders API 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. A nova API incorpora status autocontidos, validade configurável da order (expiration_time), cancelamento depois do envio ao terminal e um 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.

Este guia contempla os modos PDV e SELF_SERVICE. No SELF_SERVICE, você também deverá adaptar o controle do tempo de tela (screen_time) e os valores de impressão do comprovante.

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 Payment Intent API, cada operação utilizava uma estrutura de URL própria com o identificador do dispositivo no path. A Orders API consolida essas operações em endpoints padronizados e remove o {deviceid} do path em todas as operações.

Operação	Payment Intent API	Orders API
Listar terminais	GET /point/integration-api/devicesGET	GET /terminals/v1/listGET
Atualizar modo de operação do terminal	PATCH /point/integration-api/devices/{device_id}PATCH	PATCH /terminals/v1/setupPATCH
Criar intenção de pagamento vs. Criar order	POST /point/integration-api/devices/{deviceid}/payment-intentsPOST	POST /v1/ordersPOST
Obter intenção de pagamento vs. Obter order	GET /point/integration-api/payment-intents/{paymentintentid}GET	GET /v1/orders/{orderid}GET
Cancelar intenção de pagamento vs. Cancelar order	DELETE /point/integration-api/devices/{deviceid}/payment-intents/{paymentintentid}DELETE	POST /v1/orders/{orderid}/cancelPOST
Reembolsar order	Não existia endpoint dedicado	POST /v1/orders/{orderid}/refundPOST

Adaptar os headers

A Orders API 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

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, dentro do array terminals[]. Atualmente, o array aceita um único elemento, então você só pode atualizar um terminal por requisição.

Migrar a listagem de terminais

Na Payment Intent API, os dispositivos eram retornados no array devices. Na Orders API, 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.

Payment Intent API	Orders API	Descrição	Alteração
`devices[]`	`data.terminals[]`	Lista de terminais associados à conta. Na Payment Intent API, era retornado diretamente como array em `devices`. Na Orders API, é 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 Payment Intent API, era retornado como inteiro. Na Orders API, é 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 Orders API, os valores possíveis são PDV, STANDALONE, SELF_SERVICE e UNDEFINED, sendo este último usado para configurações não reconhecidas. | Ganha os valores SELF_SERVICE e UNDEFINED. |

| 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 Orders API

Os seguintes erros existem na Payment Intent API mas não estão documentados na Orders API.

HTTP	Payment Intent API	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 Payment Intent API.

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 Payment Intent API, o identificador do terminal era enviado no path. Na Orders API, o identificador migra para o body dentro do array terminals[]. Atualmente, o array aceita um único elemento, então você só pode atualizar um terminal por requisição.

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

O exemplo utiliza o modo PDV. Para configurar o terminal no modo SELF_SERVICE, substitua esse valor em operating_mode; a estrutura da requisição não muda.

Atualização de modo de operação via Payment Intent API. 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 Payment Intent API, o response retorna apenas o campo operating_mode. Na Orders API, o response retorna o array terminals[] com id e operating_mode, identificando cada terminal atualizado. Consulte a tabela abaixo para o mapeamento completo.

Payment Intent API	Orders API	Descrição	Alteração

| operating_mode | terminals[].operating_mode | Modo de operação definido para o terminal. Na Payment Intent API, era retornado como campo único. Na Orders API, é retornado dentro do array terminals[]. Os modos integrados disponíveis são PDV e SELF_SERVICE. | Passa para dentro do array terminals[]. |

A Orders API também introduz o seguinte campo sem equivalente na Payment Intent API.

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

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 Payment Intent API mas foi eliminado na Orders API.

HTTP	Payment Intent API	Observação
`424`	`failed_dependency`	Código eliminado na Orders API.

Erros renomeados

O seguinte erro foi renomeado na Orders API.

HTTP	Payment Intent API	Orders API	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 Orders API.

HTTP	Payment Intent API	Orders API	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 Orders API

Os seguintes erros não têm equivalente na Payment Intent API.

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 Orders API possui uma estrutura distinta. Siga os passos abaixo para adaptar a requisição, a resposta e o tratamento de erros.

A mesma requisição de criação é utilizada em PDV e SELF_SERVICE. Para SELF_SERVICE, você pode adicionar o parâmetro opcional config.point.screen_time. Se o comprovante de pagamento for impresso pelo totem, envie no_ticket em config.point.print_on_terminal para evitar sua impressão pelo terminal Point.

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 Orders API possui uma estrutura distinta da Payment Intent API: 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"
  }'

Payment Intent API	Orders API	Descrição	Alteração
`{deviceid}` (path param)	`config.point.terminal_id`	Identifica o terminal que receberá a order. Na Payment Intent API, é enviado no path. Na Orders API, é 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 Payment Intent API, é representado como inteiro com dois decimais implícitos (ex.: `1500` para $15,00). Na Orders API, é 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 Orders API, é 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 Orders API, o parâmetro é opcional. Em `PDV`, aceita `seller_ticket` —valor padrão— ou `no_ticket`. Em `SELF_SERVICE`, aceita `seller_ticket`, `no_ticket` ou `buyer_ticket` —valor padrão—.	Muda de booleano para enum string.
(não existe)	`config.point.screen_time`	Disponível somente em `SELF_SERVICE`. Define, no formato ISO 8601, por quanto tempo as telas do terminal permanecem disponíveis para processar a order. Aceita valores entre `PT5S` e `PT5M`; se omitido, utiliza `PT15S`. A tela de leitura do cartão é exibida por no máximo 60 segundos.	Campo novo sem equivalente na Payment Intent API.
`payment.type`	`config.payment_method.default_type`	Define o meio de pagamento aceito pelo terminal. Na Orders API, `PDV` aceita `credit_card`, `debit_card` e `qr`, enquanto `SELF_SERVICE` aceita `credit_card` e `debit_card`. Se omitido, o terminal aceita todos os meios de pagamento disponíveis para o modo.	Muda de nó.
`description`	`description`	Descreve o produto, serviço ou motivo do pagamento. Na Orders API, 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 Payment Intent API, era enviado como header. Na Orders API, é 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 Payment Intent API, era enviado como header. Na Orders API, é 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 Orders API também introduz os seguintes campos sem equivalente na Payment Intent API.

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. Se você enviar este campo, o valor mínimo é PT30S e o máximo é PT3H. Se omitido, o valor padrão é PT15M em PDV e PT15S em SELF_SERVICE. 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.

Payment Intent API	Orders API	Descrição	Alteração
`id` (UUID)	`id` (alfanumérico)	Identificador da order criada, gerado pelo Mercado Pago. Na Payment Intent API, é retornado no formato UUID. Na Orders API, é 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 Payment Intent API, é retornado como inteiro. Na Orders API, é 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 a configuração de impressão. Na Orders API, retorna seller_ticket ou no_ticket em PDV e seller_ticket, no_ticket ou buyer_ticket em SELF_SERVICE, conforme a configuração de impressão. | Muda de booleano para enum string. |

A Orders API também introduz os seguintes campos sem equivalente na Payment Intent API.

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

No modo SELF_SERVICE, a resposta também inclui config.point.screen_time, com o tempo configurado durante o qual as telas do terminal permanecem disponíveis.

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 Payment Intent API, os seguintes erros retornavam o código genérico bad_request. Na Orders API, são substituídos por códigos específicos.

HTTP	Payment Intent API	Orders API	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 Orders API.

HTTP	Payment Intent API	Orders API	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 Payment Intent API mas foi eliminado na Orders API.

HTTP	Payment Intent API	Observação
`424`	`failed_dependency`	Código eliminado na Orders API.

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 Orders API

Os seguintes erros não têm equivalente na Payment Intent API.

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}GET para GET /v1/orders/{orderid}GET. 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.

Payment Intent API	Orders API	Descrição	Alteração
`state`	`status`	Estado da order. Na Payment Intent API, campo `state` com valores em maiúsculas. Na Orders API, 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 Payment Intent API, era retornado como inteiro em `payment.id`. Na Orders API, é retornado como string em `transactions.payments[].reference_id`.	Identificador do pagamento processado. Muda de integer para string.

A Orders API também introduz os seguintes campos sem equivalente na Payment Intent API.

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 APIGET 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_methodsGET.
`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`).

Em SELF_SERVICE, a resposta também retorna config.point.print_on_terminal com a configuração de impressão e config.point.screen_time com o tempo de tela configurado.

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 Payment Intent API mas não têm equivalente na Orders API.

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

Erros renomeados

O seguinte erro foi renomeado na Orders API.

HTTP	Payment Intent API	Orders API	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 Orders API.

HTTP	Payment Intent API	Orders API	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 Payment Intent API e a Orders API é o campo state, que passa a se chamar status na nova API e recebe novos valores. Na Payment Intent API, o estado FINISHED exigia chamadas adicionais para determinar o resultado real do pagamento. Na Orders API, 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

Payment Intent API (`state`)	Orders API (`status`)	Observação
`OPEN`	`created`	Renomeado
`ON_TERMINAL`	`at_terminal`	Renomeado
`PROCESSING`	Absorvido	Não há estado intermediário na Orders API
`PROCESSED`	Absorvido	Não há estado intermediário na Orders API
`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. Este status está disponível somente em PDV; não se aplica a SELF_SERVICE. |

Na Payment Intent API, 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 Orders API, os status processed e failed são autocontidos: o resultado do pagamento está disponível diretamente na order, sem consultas adicionais.

Não utilize a API de Payments para consultar o resultado de pagamentos Point processados pela Orders API. Consulte a própria order, que contém todas as informações do resultado nos status processed e failed.

A Orders API também introduz o seguinte status sem equivalente na Payment Intent API.

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

Atualizar o tópico de notificações de webhook

Na Payment Intent API, as notificações de Point eram enviadas pelo tópico point_integration_wh. Na Orders API, elas passam para o tópico Order (Mercado Pago) (orders). Antes de subir em produção, atualize a configuração da sua aplicação em Suas integrações: inscreva-se em Order (Mercado Pago) e desative point_integration_wh.

Para mais informações, consulte a documentação Configurar notificações.

Atualizar o cancelamento de orders

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

Na Payment Intent API, só era possível cancelar intenções de pagamento que ainda não tinham chegado ao terminal. Na Orders API, é 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 Payment Intent API mas não têm equivalente na Orders API.

HTTP	Payment Intent API	Observação
`400`	`bad_request` (deviceID format)	`deviceid` foi removido do path na Orders API.
`403`	`forbidden`	Esse erro deixa de existir no cancelamento porque a validação do terminal não se aplica a este recurso.
`429`	`too_many_requests`	Presente na Payment Intent API. Não documentado na Orders API.

Erros renomeados

O seguinte erro foi renomeado na Orders API.

HTTP	Payment Intent API	Orders API	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 Orders API.

HTTP	Payment Intent API	Orders API	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 Payment Intent API, o campo `error` usa o código numérico `"101"`.
`409`	`101`	`order_already_canceled`	Na Payment Intent API, order inexistente e order já cancelada retornavam o mesmo erro `"101"`. Na Orders API 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.
`500`	Genérico	Erro interno. Verifique o retorno e repita a requisição.

Erros introduzidos pela Orders API

Os seguintes erros não têm equivalente na Payment Intent API.

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 Orders API introduz o endpoint dedicado POST /v1/orders/{orderid}/refund para reembolsos, que não existia na Payment Intent API. 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 Payment Intent API

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}/refundPOST 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/listGET e configurados por meio de PATCH /terminals/v1/setupPATCH no modo PDV ou SELF_SERVICE, de acordo com o fluxo da integração.

Criação de orders validada

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

Consulta de orders validada

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

Tópico de webhook atualizado

Tópico "Order (Mercado Pago)" (orders) configurado em Suas integrações substituindo point_integration_wh, e status de orders monitorados 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}/cancelPOST.

Reembolsos validados

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

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

AnteriorStatus de uma order e de uma transaçãoConheça quais são os status que uma order e uma transação podem assumir.

PróximoCredenciaisCredenciais são senhas únicas com as quais identificamos uma integração na sua conta. Saiba como obtê-las.