Mercado Pago
DEVELOPERS
Entrar
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. A nova API incorpora status autocontidos, validade configurável da order (expiration_time) e 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çãoAPI de Intenção de PagamentoAPI de Orders
Listar terminaisGET /point/integration-api/devicesAPIGET /terminals/v1/listAPI
Atualizar modo de operação do terminalPATCH /point/integration-api/devices/{device_id}APIPATCH /terminals/v1/setupAPI
Criar intenção de pagamento vs. Criar orderPOST /point/integration-api/devices/{deviceid}/payment-intentsAPIPOST /v1/ordersAPI
Obter intenção de pagamento vs. Obter orderGET /point/integration-api/payment-intents/{paymentintentid}APIGET /v1/orders/{orderid}API
Cancelar intenção de pagamento vs. Cancelar orderDELETE /point/integration-api/devices/{deviceid}/payment-intents/{paymentintentid}APIPOST /v1/orders/{orderid}/cancelAPI
Reembolsar orderNão existia endpoint dedicadoPOST /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.

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 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"
  }'

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}}'

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.

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

Na API de Intenção de Pagamento, as notificações eram enviadas pelo tópico point_integration_wh. Já na API de Orders, elas passam a ser enviadas pelo tópico Order (Mercado Pago) (orders).

Antes de subir em produção, atualize a configuração da sua aplicação em Suas integrações. Para isso, selecione o tópico "Order (Mercado Pago)" e desative o tópico 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 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}}'

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.

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.

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

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

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

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

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

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.

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

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

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.