Cómo migrar de la API de Pagos a la API de Orders
La migración de integraciones de Pagos automáticos con la API de Pagos a la API de Orders involucra un traslado de la gestión de Clientes y Tarjetas a la estructura de Perfiles, inicialmente, y luego en la utilización de la API de Orders para el procesamiento de pagos.
Ve a continuación cómo realizar esta migración de manera correcta.
Crear perfiles para clientes ya almacenados
Anteriormente, en el flujo vía Pagos, los datos de clientes y sus tarjetas tokenizadas eran almacenados y gestionados únicamente a través de las APIs de ClientesAPI y TarjetasAPI.
La nueva API de Orders para Pagos automáticos, en cambio, requiere la creación de un profile (o perfil) de pago para cada cliente a la hora de enviar pagos recurrentes, recuperando la información almacenada por Clientes y Tarjetas. Estos perfiles simplifican el reaprovechamiento de datos de pago: contienen los medios asociados a un cliente y funcionan como un modelo para futuros cobros automáticos.
Además, la estructura de Perfiles realiza una validación automática de los medios de pago de un cliente, evitando la necesidad de procesar pagos de validación y, ante pagos rechazados, realiza nuevas tentativas de procesamiento con el resto de los medios de pago que lo componen, mejorando la tasa de aprobación.
Es posible crear perfiles de los clientes previamente almacenados utilizando el customer_id y el card_id de sus tarjetas guardadas siguiendo los pasos a continuación.
Comienza por obtener el customer_id de un cliente enviando un GET y su e-mail registrado al endpoint /v1/customers/searchAPI.
curlcurl -X GET \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ 'https://api.mercadopago.com/v1/customers/search' \ -d '{ "email": "test@testuser.com" }'
Si la solicitud es exitosa, en la respuesta encontrarás el customer_id identificado como id, tal como se muestra en el ejemplo a continuación.
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 } } ] }
Luego, consulta la lista de las tarjetas almacenadas para este cliente enviando un GET con el customer_id del cliente obtenido en la solicitud anterior al endpoint /v1/customers/{customer_id}/cardsAPI.
curlcurl -X GET \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ 'https://api.mercadopago.com/v1/customers/{{CUSTOMER_ID}}/cards'
Si la solicitud es exitosa, la respuesta devolverá todas las tarjetas almacenadas para ese cliente. Cada una tendrá su card_id identificado como id, tal como se muestra en el ejemplo a continuación.
json[ { "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001" } ]
Deberás almacenar ambas identificaciones, la del cliente y la de la tarjeta, para poder incorporarlas a la API de Perfiles.
Para crear un perfil de pago de un cliente migrando los datos de Clientes y Tarjetas, envía un POST al endpoint /v1/customers/{customer_id}/payment-profiles incluyendo el customer_id en el path de la requisición, el card_id en el body, y siguiendo las especificaciones de la tabla debajo.
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 y descripción | Obligatoriedad |
customer_id | Path. Identificador del cliente que se está queriendo migrar, obtenido en la consulta a la API de Clientes de la etapa anterior. | Obligatorio |
description | Body, string. Descripción del perfil de pago. Recomendamos usar este campo para categorizar tipos de servicio contratados, planes o la frecuencia del modelo de negocio. | Opcional |
max_day_overdue | Body, integer. Define la cantidad de días para realizar nuevas tentativas de procesamiento del pago en caso de falla o rechazo inicial. Por ejemplo, si envías "5" como valor, se realizarán nuevas tentativas de procesamiento durante los 5 días posteriores al primer fallo. Si el pago se procesa antes de los días establecidos, la lógica de reintentos se interrumpirá. Valor entre 1 y 10. | Opcional |
statement_descriptor | Body, string. Descripción que aparecerá en el estado de cuenta del medio de pago del cliente. Útil para identificar la transacción. Ejemplo: MERCADOPAGO. | Opcional |
sequence_control | Body, string. Modo de control de secuencia de pagos. Los valores pueden ser: AUTO (automático, reintenta el pago con otros medios) o MANUAL (requiere intervención manual). | Opcional |
payment_methods | Body, object. Contiene la información del medio de pago a migrar. No permite más de dos medios de pago. Si hay más de un medio, acepta como máximo dos tarjetas (crédito o débito). | Obligatorio |
payment_methods.id | Body, string. Identificador del medio de pago o bandera de la tarjeta. Ejemplo: visa, master. | Obligatorio |
payment_methods.type | Body, string. Tipo de medio de pago. Los valores pueden ser credit_card (tarjeta de crédito), debit_card (tarjeta de débito) o prepaid_card (tarjeta prepago). | Obligatorio |
payment_methods.card_id | Body, string. Identificador de la tarjeta del cliente que se está queriendo migrar, obtenido en la consulta a la API de Tarjetas de la etapa anterior. | Obligatorio |
Si la solicitud es exitosa, la respuesta se verá como el ejemplo a continuación.
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 } ] }
El campo status indicará el estado en el que se encuentra la creación del perfil:
| Status | Descripción |
PENDING | Es el estado inicial al crear el perfil con tarjetas como medio de pago, o bien si este es creado sin ningún medio de pago. Permanecerá en este estado hasta que se efectúe el pago de prueba, cuando pasará a los estados READY o CANCELLED. |
READY | Este estado indica que el perfil tiene una identificación de tarjeta válida y fue creado exitosamente. Este estado puede variar en un futuro: puede pasar a CANCELLED o puede volver al estado de PENDING si todos los medios de pago son modificados o eliminados. |
CANCELLED | Estado que indica que el perfil fue cancelado por no tener un medio de pago aprobado, por no poder consultar el medio de pago asociado, o, en el caso de Fintoc, porque la cancelación fue solicitada por el cliente. Este estado no puede ser modificado. |
Si lo deseas, luego de esta creación, podrás agregar más medios de pago a un perfil, o bien crear diversos perfiles para un mismo usuario, identificado con el mismo e-mail. Consulta todas las operaciones posibles accediendo a Gestión de perfiles.
card_id o un customer_id de la API de Clientes y Tarjetas después de haberlo asociado a un perfil, las operaciones con ese perfil pueden fallar. Es importante mantener la integridad de los datos entre ambas APIs durante el período de transición.Al concluir estos pasos para todos tus clientes preexistentes, estarán debidamente configurados en la API de Perfiles y podrás comenzar a realizar cobros automáticos de forma eficiente a través de la API de Orders. Dirígete a la documentación para saber cómo procesar pagos.