Como migrar da Payments API para a Orders API

A Payments API continua funcionando normalmente após o lançamento da Orders API. O Mercado Pago não desativou essa API, apenas deixou de adicionar novas funcionalidades a ela, mantendo correções de segurança e estabilidade. Tecnicamente, é possível manter as duas APIs ativas ao mesmo tempo, cada uma processando parte do seu volume.

Recomendamos a seguinte estratégia:

• Migre por meio de pagamento, não tudo de uma vez. Mova cartão para a Orders API primeiro e migre os demais meios de pagamento um a um, após validar a estabilidade.
• Faça a divisão de tráfego no seu próprio checkout. Como cada API usa endpoints, credenciais e chaves de idempotência independentes, é seguro rotear parte das novas transações para /v1/ordersPOST e o restante para /v1/paymentsPOST.
• Separe o tratamento de notificações. Configure o Webhook para escutar os tópicos orders e payment em paralelo durante a transição, direcionando cada payload ao tratamento correto. Só desative payment depois de migrar o tráfego novo e monitorar as transações e notificações pendentes da Payments API.
• Defina como interromper a migração. Se for necessário voltar a usar a Payments API, redirecione apenas as novas transações. As transações já criadas devem continuar sendo consultadas, capturadas, canceladas ou reembolsadas na API em que foram processadas, pois não podem nem precisam ser transferidas de uma API para a outra.
• Acompanhe a taxa de aprovação e a qualidade da integração separadamente para cada API durante a coexistência, como critério para decidir quando desligar o tráfego da Payments API.

Antes de iniciar a migração, confirme se todos os meios de pagamento da sua integração já têm equivalente na Orders API.

Além da disponibilidade por meio de pagamento, verifique se a sua integração utiliza recursos de Marketplace ou Split de Pagamentos 1:1. Na Payments API, essas integrações retêm comissões por meio de application_fee; a Orders API ainda não tem um campo equivalente documentado para essa mecânica. Trate esse ponto como bloqueio antes de migrar o fluxo.

Na Payments API, cada operação usava um recurso próprio sobre /v1/payments/{id}. A Orders API consolida a maior parte dessas operações em sub-recursos do mesmo /v1/orders/{order_id} e introduz endpoints dedicados que não existiam antes: captura explícita, adição, remoção e atualização de transações, e processamento em modo manual.

O header Authorization é obrigatório em ambas as APIs e não muda. A principal alteração está na obrigatoriedade do header de idempotência em praticamente todas as operações de escrita.

Na Payments API, o status e o status_detail existem em um único nível. Na Orders API, o mesmo conceito existe em dois níveis: o status da order, como visão consolidada, e o status de cada transação em transactions.payments[] — o que passa a ser essencial quando uma order tem mais de uma transação.

O endpoint de criação muda de /v1/paymentsPOST para /v1/ordersPOST. Além da URL, a estrutura da requisição foi reorganizada: o valor e o meio de pagamento migram para dentro do nó transactions.payments[], um array que permite múltiplas transações por order. Os campos type, com valor fixo online, e o nó config passam a existir sem equivalência direta no legado.

A tabela a seguir mapeia os principais campos da resposta de criação entre as duas APIs.

A Payments API retorna um erro por vez, o primeiro encontrado. A Orders API retorna uma lista com todos os erros de validação da requisição em uma única resposta, o que agiliza a correção.

O endpoint de consulta muda de /v1/payments/{id}GET para /v1/orders/{id}GET. A resposta traz o objeto completo da order, incluindo todas as transações associadas, seus reembolsos e eventuais contestações — informação que no legado exigia consultas separadas.

Erros de consulta

O endpoint de busca muda de /v1/payments/searchGET para /v1/orders/searchGET, com filtros e paginação reestruturados. Os intervalos de data passam a ser obrigatórios e a paginação usa page e page_size em vez de offset e limit.

A reserva de valor muda de um campo booleano (capture) para um modo de captura configurado na criação da order (capture_mode), combinado com um endpoint dedicado de captura.

Assim como na Payments API, é possível cancelar uma order antes da conclusão do pagamento ou reembolsá-la, total ou parcialmente, após a aprovação. Veja a seguir como cada fluxo muda na Orders API.

Os endpoints da API de Clientes são compartilhados entre as duas APIs e não sofrem alteração de estrutura na migração. Apenas a forma de usar o cartão salvo em uma nova cobrança muda, já que o pagamento passa a ser criado como order.

O que muda ao pagar com um cartão salvo:

Na Payments API, integrações de marketplace usam OAuth para obter o Access Token do vendedor conectado e enviam o campo application_fee, com o valor retido pelo integrador, no corpo da criação do pagamento.

A autenticação 3D Secure 2.0 passa de um campo simples para um nó de configuração dedicado em config.online.transaction_security, com controle explícito de responsabilidade por contestação.

Status possíveis após o fluxo de 3DS na Orders API:

O mecanismo de assinatura e validação HMAC-SHA256 é idêntico entre as duas APIs. O que muda é o tópico de notificação e a origem da configuração.

O endpoint de consulta de contestação /v1/chargebacks/{id}GET é idêntico entre as duas APIs. A diferença está no evento de notificação e nos novos campos expostos diretamente na order.

Os campos de resolução são idênticos nas duas APIs.

As boas práticas de prevenção à fraude permanecem conceitualmente iguais. O que muda é onde os dados adicionais são enviados no corpo da requisição.

O uso de credenciais, usuários e cartões de teste segue o mesmo conceito. A principal diferença está no e-mail exigido para o pagador e na tabela de nomes de titular usada para simular cada cenário.

A avaliação da Orders API considera os seguintes aspectos para medir a qualidade da integração migrada.

Antes de subir em produção, confirme os seguintes pontos:

• Ativar as credenciais de produção em Suas integrações.
• Substituir a Public Key e o Access Token de teste pelos de produção.
• Implementar certificado SSL/HTTPS, obrigatório em produção.
• Reconfigurar o Webhook para o tópico orders. Desative o tópico payment apenas depois de migrar o tráfego novo e concluir o monitoramento das transações e notificações pendentes da Payments API.
• Garantir o tratamento de todos os valores de status e status_detail nos dois níveis, order e transação.

Depois de aplicar as mudanças, verifique se a integração funciona corretamente em todos os fluxos antes de ir para produção. Use os checkboxes abaixo para confirmar cada ponto.

Validações obrigatórias

Validações conforme seu fluxo

Validações para fluxos ainda sem equivalência