Recursos para IA

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.

Obter as informações de Clientes e Cartões

Comece obtendo o customer_id de um cliente enviando um GET com seu e-mail registrado ao endpoint /v1/customers/searchAPI.

curl
curl -X GET \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
    'https://api.mercadopago.com/v1/customers/search' \
    -d '{
    "email": "test_user_19653727@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_12345@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.

curl
curl -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"
  }
]

Se a resposta a esta consulta não retornar nenhum meio de pagamento, é porque nunca foi adicionado um cartão a esse cliente.

Você deverá armazenar ambas as identificações, a do cliente e a do cartão, para poder incorporá-las à API de Perfis.

Criar o Perfil de Pagamento

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.

curl
curl -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

Consulte o detalhe de todos os parâmetros a serem enviados nesta solicitação na Referência de API

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.

Se você excluir um 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.

Medios de pago disponibles

Conoce los medios de pago disponibles para procesar Pagos Automáticos

Credenciales

Credenciales son contraseñas únicas con las que identificamos una integración en tu cuenta. Descubre cómo conseguirlas.

Documentação

Começando agora?

Recursos

Suporte

Parcerias

Comunidade

Como migrar da API de Pagamentos para a API de Orders

Criar perfis para clientes já armazenados

Navegação

Recursos e Comunidade

Mercado Pago

País e idioma