AI resources

How to migrate from the Payments API to the Orders API

The migration of Automatic Payments integrations from the Payments API to the Orders API involves transferring the management of Customers and Cards to the Profiles structure, initially, and then using the Orders API for payment processing.

See below how to perform this migration correctly.

Create profiles for already stored customers

Previously, in the Payments flow, customer data and their tokenized cards were stored and managed only through the CustomersAPI and CardsAPI APIs.

The new Orders API for Automatic Payments, on the other hand, requires the creation of a payment profile for each customer when sending recurring payments, retrieving the information stored by Customers and Cards. These profiles simplify the reuse of payment data: they contain the payment methods associated with a customer and function as a template for future automatic charges.

Additionally, the Profiles structure performs automatic validation of a customer's payment methods, avoiding the need to process validation payments and, in case of rejected payments, makes new processing attempts with the remaining payment methods that compose it, improving the approval rate.

It is possible to create profiles for previously stored customers using the customer_id and the card_id of their saved cards by following the steps below.

Get Customer and Card information

Start by obtaining the customer_id of a customer by sending a GET with their registered email to the 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"
}'

If the request is successful, in the response you will find the customer_id identified as id, as shown in the example below.

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

Then, query the list of stored cards for this customer by sending a GET with the customer_id obtained in the previous request to the endpoint /v1/customers/{customer_id}/cardsAPI.

curl
curl -X GET \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
    'https://api.mercadopago.com/v1/customers/{{CUSTOMER_ID}}/cards'

If the request is successful, the response will return all stored cards for that customer. Each one will have its card_id identified as id, as shown in the example below.

json
[
  {
    "id": "1490022319978",
    "expiration_month": 12,
    "expiration_year": 2020,
    "first_six_digits": "415231",
    "last_four_digits": "0001"
  }
]

If the response to this query does not return any payment method, it is because a card was never added to that customer.

You must store both identifications, the customer's and the card's, to be able to incorporate them into the Profiles API.

Create the Payment Profile

To create a payment profile for a customer by migrating the Customers and Cards data, send a POST to the endpoint /v1/customers/{customer_id}/payment-profiles including the customer_id in the request path, the card_id in the body, and following the specifications in the table below.

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

Field	Type and description	Required
`customer_id`	Path. Identifier of the customer being migrated, obtained in the query to the Customers API in the previous step.	Required
`description`	Body, string. Description of the payment profile. We recommend using this field to categorize contracted service types, plans, or business model frequency.	Optional
`max_day_overdue`	Body, integer. Sets the number of days to retry the payment processing in case of failure or initial rejection. For example, if you send "5" as value, new processing attempts will be made for the next 5 days after the first failure. In case the payment is processed before the set days, the retry logic will be stopped. Value between 1 and 10.	Optional
`statement_descriptor`	Body, string. Description that will appear on the customer's payment method statement. Useful for identifying the transaction. Example: `MERCADOPAGO`.	Optional
`sequence_control`	Body, string. Payment sequence control mode. Values can be: `AUTO` (automatic, retries payment with other methods) or `MANUAL` (requires manual intervention).	Optional
`payment_methods`	Body, object. Contains the payment method information to migrate. Does not allow more than two payment methods. If there is more than one method, it accepts a maximum of two cards (credit or debit).	Required
`payment_methods.id`	Body, string. Payment method identifier or card brand. Example: `visa`, `master`.	Required
`payment_methods.type`	Body, string. Payment method type. Values can be `credit_card`, `debit_card`, or `prepaid_card`.	Required
`payment_methods.card_id`	Body, string. Card identifier of the customer being migrated, obtained in the query to the Cards API in the previous step.	Required

Check the detail of all parameters to be sent in this request in the API Reference

If the request is successful, the response will look like the example below.

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

The status field will indicate the state of the profile creation:

Status	Description
`PENDING`	This is the initial status when creating the profile with cards as payment method, or if it is created without any payment method. It will remain in this status until the test payment is made, when it will change to `READY` or `CANCELLED` status.
`READY`	This status indicates that the profile has a valid card identification and was created successfully. This status may change in the future: it can change to `CANCELLED` or return to `PENDING` status if all payment methods are modified or removed.
`CANCELLED`	Status indicating that the profile was canceled due to not having an approved payment method, being unable to query the associated payment method, or, in the case of Fintoc, because the cancellation was requested by the customer. This status cannot be modified.

If you wish, after this creation, you can add more payment methods to a profile, or create multiple profiles for the same user, identified with the same email. Check all possible operations by accessing Profile management.

If you delete a card_id or a customer_id from the Customers and Cards API after associating it with a profile, operations with that profile may fail. It is important to maintain data integrity between both APIs during the transition period.

Upon completing these steps for all your pre-existing customers, they will be properly configured in the Profiles API and you can start making automatic charges efficiently through the Orders API. Go to the documentation to learn how to process payments.

Adobe Commerce

Mercado Pago in your store

Documentation

Starting now?

Resources

Support

Partners

Community

How to migrate from the Payments API to the Orders API

Create profiles for already stored customers

Navigation

Resources and Community

Mercado Pago

Country and language