Como migrar da API de Pagamentos para a API de Orders
A migração de integrações de Pagamentos automáticos da API de Pagamentos para a API de Orders envolve uma transferência da gestão de Clientes e Cartões para a estrutura de Perfis, inicialmente, e depois na utilização da API de Orders para o processamento de pagamentos.
Veja a seguir como realizar esta migração corretamente.
Criar perfis para clientes já armazenados
Anteriormente, no fluxo via Pagamentos, os dados de clientes e seus cartões tokenizados eram armazenados e gerenciados apenas através das APIs de ClientesAPI e CartõesAPI.
A nova API de Orders para Pagamentos automáticos, por outro lado, requer a criação de um profile (ou perfil) de pagamento para cada cliente no momento de enviar pagamentos recorrentes, recuperando as informações armazenadas por Clientes e Cartões. Esses perfis simplificam o reaproveitamento de dados de pagamento: contêm os meios de pagamento associados a um cliente e funcionam como um modelo para futuras cobranças automáticas.
Além disso, a estrutura de Perfis realiza uma validação automática dos meios de pagamento de um cliente, evitando a necessidade de processar pagamentos de validação e, diante de pagamentos recusados, realiza novas tentativas de processamento com os demais meios de pagamento que o compõem, melhorando a taxa de aprovação.
É possível criar perfis dos clientes previamente armazenados utilizando o customer_id e o card_id de seus cartões salvos seguindo os passos abaixo.
Comece obtendo o customer_id de um cliente enviando um GET com seu e-mail registrado ao endpoint /v1/customers/searchAPI.
curlcurl -X GET \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ 'https://api.mercadopago.com/v1/customers/search' \ -d '{ "email": "test@testuser.com" }'
Se a solicitação for bem-sucedida, na resposta você encontrará o customer_id identificado como id, conforme mostrado no exemplo abaixo.
json{ "paging": { "limit": 10, "offset": 0, "total": 1 }, "results": [ { "address": { "id": null, "street_name": null, "street_number": null, "zip_code": null }, "addresses": [], "cards": [ { ... } ], "date_created": "2017-05-05T00:00:00.000-04:00", "date_last_updated": "2017-05-05T09:23:25.021-04:00", "date_registered": null, "default_address": null, "default_card": "1493990563105", "description": null, "email": "test_payer@testuser.com", "first_name": null, "id": "123456789-jxOV430go9fx2e", "identification": { "number": null, "type": null }, "last_name": null, "live_mode": false, "metadata": {}, "phone": { "area_code": null, "number": null } } ] }
Em seguida, consulte a lista de cartões armazenados para este cliente enviando um GET com o customer_id obtido na solicitação anterior ao endpoint /v1/customers/{customer_id}/cardsAPI.
curlcurl -X GET \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ 'https://api.mercadopago.com/v1/customers/{{CUSTOMER_ID}}/cards'
Se a solicitação for bem-sucedida, a resposta retornará todos os cartões armazenados para esse cliente. Cada um terá seu card_id identificado como id, conforme mostrado no exemplo abaixo.
json[ { "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001" } ]
Você deverá armazenar ambas as identificações, a do cliente e a do cartão, para poder incorporá-las à API de Perfis.
Para criar um perfil de pagamento de um cliente migrando os dados de Clientes e Cartões, envie um POST ao endpoint /v1/customers/{customer_id}/payment-profiles incluindo o customer_id no path da requisição, o card_id no body, e seguindo as especificações da tabela abaixo.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/123456789-jxOV430go9fx2e/payment-profiles'\ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN \ -d '{ "description": "Test payment profile", "max_day_overdue": 5, "statement_descriptor": "Test Descriptor", "sequence_control": "MANUAL", "payment_methods": [ { "id": "visa", "type": "credit_card", "token": "12345", "default_method": false } ] }'
| Campo | Tipo e descrição | Obrigatoriedade |
customer_id | Path. Identificador do cliente que está sendo migrado, obtido na consulta à API de Clientes na etapa anterior. | Obrigatório |
description | Body, string. Descrição do perfil de pagamento. Recomendamos usar este campo para categorizar tipos de serviços contratados, planos ou a frequência do modelo de negócio. | Opcional |
max_day_overdue | Body, integer. Define a quantidade de dias para realizar novas tentativas de processamento do pagamento em caso de falha ou rejeição inicial. Por exemplo, se você enviar "5" como valor, novas tentativas de processamento serão feitas para os próximos 5 dias após a primeira falha. Caso o pagamento seja processado antes dos dias definidos, a lógica de tentativas será interrompida. Valor entre 1 e 10. | Opcional |
statement_descriptor | Body, string. Descrição que aparecerá no extrato do meio de pagamento do cliente. Útil para identificar a transação. Exemplo: MERCADOPAGO. | Opcional |
sequence_control | Body, string. Modo de controle de sequência de pagamentos. Os valores podem ser: AUTO (automático, tenta novamente o pagamento com outros meios) ou MANUAL (requer intervenção manual). | Opcional |
payment_methods | Body, object. Contém as informações do meio de pagamento a migrar. Não permite mais de dois meios de pagamento. Se houver mais de um meio, aceita no máximo dois cartões (crédito ou débito). | Obrigatório |
payment_methods.id | Body, string. Identificador do meio de pagamento ou bandeira do cartão. Exemplo: visa, master. | Obrigatório |
payment_methods.type | Body, string. Tipo de meio de pagamento. Os valores podem ser credit_card (cartão de crédito), debit_card (cartão de débito) ou prepaid_card (cartão pré-pago). | Obrigatório |
payment_methods.card_id | Body, string. Identificador do cartão do cliente que está sendo migrado, obtido na consulta à API de Cartões na etapa anterior. | Obrigatório |
Se a solicitação for bem-sucedida, a resposta será semelhante ao exemplo abaixo.
json{ "id": "PROFILE_ID", "created_date": "2025-09-05T18:35:39.000Z", "last_updated_date": "2025-09-05T18:35:39.000Z", "description": "Test", "status": "READY", "sequence_control": "AUTO", "payment_methods": [ { "payment_method_id": "a6e5fe16-3ed9-4826-b5a1-875e7b9973af", "id": "master", "type": "credit_card", "status": "READY", "card_id": 9264694962, "default_method": false } ] }
O campo status indicará o estado em que se encontra a criação do perfil:
| Status | Descrição |
PENDING | É o status inicial ao criar o perfil com cartões como meio de pagamento, ou se ele for criado sem nenhum meio de pagamento. Permanecerá neste status até que o pagamento de teste seja efetuado, quando passará para os status READY ou CANCELLED. |
READY | Este status indica que o perfil tem uma identificação de cartão válida e foi criado com sucesso. Este status pode mudar no futuro: pode passar para CANCELLED ou voltar ao status PENDING se todos os meios de pagamento forem modificados ou removidos. |
CANCELLED | Status que indica que o perfil foi cancelado por não ter um meio de pagamento aprovado, por não conseguir consultar o meio de pagamento associado, ou, no caso do Fintoc, porque o cancelamento foi solicitado pelo cliente. Este status não pode ser modificado. |
Se desejar, após esta criação, você poderá adicionar mais meios de pagamento a um perfil, ou criar diversos perfis para um mesmo usuário, identificado com o mesmo e-mail. Consulte todas as operações possíveis acessando Gestão de perfis.
card_id ou um customer_id da API de Clientes e Cartões após tê-lo associado a um perfil, as operações com esse perfil podem falhar. É importante manter a integridade dos dados entre ambas as APIs durante o período de transição.Ao concluir estes passos para todos os seus clientes pré-existentes, eles estarão devidamente configurados na API de Perfis e você poderá começar a realizar cobranças automáticas de forma eficiente através da API de Orders. Acesse a documentação para saber como processar pagamentos.