Gestión de perfiles
Luego de concluir las configuraciones iniciales, podrás acceder a un conjunto de llamadas destinadas a la gestión de los perfiles.
En esta sección, presentamos las principales operaciones disponibles para administrar un perfil y cómo ejecutarlas.
Para almacenar los datos del cliente y de su tarjeta para pagos futuros, es necesario crear un perfil de pago. Este perfil funciona como la estructura que almacena los datos de pago utilizados por tu sistema y facilita su reutilización en cobros futuros.
Para crear el perfil de pago del cliente, envía una solicitud al endpoint Crear perfil de pago para el clientePOST considerando los parámetros listados en la tabla debajo del código. En el path de la solicitud, incluye el customer_id obtenido al crear el cliente. En el body, proporciona el id de la tarjeta generado al asociar la tarjeta al cliente.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "description": "Payment description", "payment_methods": [ { "id": "master", "type": "credit_card", "card_id": 1234567890, "default_method": false } ] }'
| Atributo | Tipo | Descripción | Obligatoriedad |
customer_id | Path. String | Identificador del cliente, obtenido al crear el cliente en el paso anterior. | Obligatorio |
description | Body. String | Descripción del perfil de pago. Recomendamos usar este campo para categorizar tipos de servicios contratados, planes o la frecuencia del modelo de negocio. | Opcional |
payment_methods | Body. Object | Contiene la información del medio de pago. Durante la creación del perfil, no permite más de dos medios de pago. Cuando hay dos tarjetas, solo una se identificará con el token, y la otra deberá identificarse con el card_id. Es posible combinar tarjetas de crédito y débito. | Obligatorio |
payment_methods.id | Body. String | Identificador del medio de pago o marca 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 prepaga). | Obligatorio |
payment_methods.card_id | Body. Long | Identificador de la tarjeta del cliente, obtenido en el paso anterior. | Obligatorio |
payment_methods.default_method | Body. Boolean | Identifica si el medio de pago es el predeterminado para realizar los intentos de pago para ese cliente. | Opcional |
AUTO para el campo sequence_control. Los perfiles creados con el valor MANUAL generan conflictos con el campo stored_credential.previous_transaction_reference, lo que puede impedir la ejecución de los cobros.Si la solicitud es exitosa, la respuesta devolverá status = READY y el identificador del perfil de pago para ese cliente, en el parámetro id. Este profile_id deberá usarse para procesar los pagos con la API de Orders.
json{ "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T14:03:28.653Z", "description": "Payment description", "max_day_overdue": 5, "statement_descriptor": "Test Descriptor", "status": "READY", "sequence_control": "AUTO", "payment_methods": [ { "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true } ] }
Esta operación permite consultar, a partir de un ID, el perfil de pago asociado a un cliente específico y acceder a toda la información registrada. Es útil, por ejemplo, para confirmar los datos del perfil antes de realizar un nuevo pago o mostrar al usuario la información del medio de pago almacenado.
Para eso, envía una solicitud al endpoint Consultar un perfil de pago específicoGET considerando los parámetros listados en la tabla debajo del código.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descripción | Obligatoriedad |
customer_id | Path. String | Identificador único del cliente cuyo perfil de pago está siendo consultado. | Obligatorio |
payment_profile_id | Path.String | Identificador único del perfil de pago, asociado al cliente. | Obligatorio |
En caso de éxito, la respuesta retornada seguirá el formato del ejemplo a continuación.
json{ "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T14:03:28.653Z", "description": "Payment description", "max_day_overdue": 5, "statement_descriptor": "Test Descriptor", "status": "READY", "sequence_control": "AUTO", "payment_methods": [ { "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true } ] }
Esta operación permite consultar la lista de perfiles de pago asociados a un cliente a través de su ID, siendo útil cuando es preciso identificar qué perfiles el cliente posee para elegir cuál de ellos será utilizado en pagos posteriores.
Para eso, envía una solicitud al endpoint Consultar lista de perfiles de pagoGET considerando los parámetros listados en la tabla debajo del código.
curlcurl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles?limit=50&status=READY' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descripción | Obligatoriedad |
customer_id | Path. String | Identificador único del cliente para el cual se están consultando los perfiles de pago. | Obligatorio |
limit | Query. Integer | Límite de paginación. Especifica el número máximo de registros que deseas obtener en la respuesta. Debe ser un valor numérico entre 1 y 100, siendo 50 el valor aplicado por defecto. | Opcional |
offset | Query. Integer | Offset de paginación. Determina el punto inicial a partir del cual los registros deben ser obtenidos. Debe ser un valor numérico mayor o igual a cero (0). | Opcional |
status | Query. String | Estado actual del perfil de pago. Debe enviarlo en caso de que desee filtrar los perfiles por estado. | Opcional |
En caso de éxito, la respuesta retornada seguirá el formato del ejemplo a continuación.
json{ "paging": { "total": 10, "total_pages": 100, "offset": 1, "limit": 10 }, "data": [ { "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T15:03:28.653Z", "description": "Simple description", "max_day_overdue": 5, "statement_descriptor": "Statement description", "status": "READY", "sequence_control": "AUTO", "payment_methods": [ { "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true } ] } ] }
Esta operación permite agregar un nuevo medio de pago al perfil del cliente o actualizar uno existente, incluyendo la posibilidad de ajustar el campo default_method a true o false, definiendo así si será o no el medio de pago predeterminado.
Para agregar un medio de pago, envía una solicitud al endpoint Agregar medio de pago a un perfilPOST considerando los parámetros listados en la tabla debajo del código.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/payment-methods' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "id": "{{bandera_tarjeta}}", "type": "credit_card", "token": "{{card_token}}", "default_method": true }'
| Atributo | Tipo | Descripción | Obligatoriedad |
X-Idempotency-Key | Header. String | Clave de idempotencia. Permite repetir solicitudes con seguridad, evitando que la misma acción sea procesada más de una vez. Recomendamos usar un UUID V4 o strings aleatorias. | Obligatorio |
Authorization | Header. String | Clave privada utilizada para autenticar las requisiciones. Utiliza tu Access Token de prueba en el ambiente de desarrollo y tu Access Token productivo en el ambiente de producción. | Obligatorio |
customer_id | Path. String | Identificador único del cliente al cual pertenece el perfil de pago que está siendo modificado. | Obligatorio |
payment_profile_id | Path. String | Identificador único del perfil de pago a modificar, asociado al cliente. | Obligatorio |
id | Body. String | Identificador del medio de pago seleccionado. Para pagos con tarjeta, indica la bandera (visa, master, debmaster, debvisa). | Obligatorio |
type | Body. String | Tipo del medio de pago seleccionado: credit_card, debit_card, prepaid_card. | Obligatorio |
token | Body. String | Token seguro que identifica el medio de pago. Es obligatorio en transacciones con tarjeta y debe tener entre 32 y 33 caracteres. | Obligatorio para tarjeta |
card_id | Body. Long | ID de la tarjeta asociada al medio de pago. | Obligatorio |
default_method | Body. Boolean | Define si este medio será utilizado como predeterminado en futuras tentativas de pago. | Opcional |
En caso de éxito, la respuesta retornada seguirá el formato del ejemplo a continuación.
json{ "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true }
Al agregar un medio de pago a un perfil, la API realiza automáticamente su validación para verificar si podrá ser utilizado en cobros futuros. El resultado de esa validación es indicado por el campo status, que muestra la situación actual del medio de pago. Conoce más sobre los estados del medio de pago consultando nuestra documentación.
Esta operación permite eliminar un medio de pago de un perfil, lo que puede ser necesario cuando el usuario opta por remover una tarjeta que no desea más utilizar o cuando el medio deja de ser válido para cobros futuros.
Para eso, envía una solicitud al endpoint Eliminar medio de pago de un perfilDELETE considerando los parámetros listados en la tabla debajo del código.
curlcurl -X DELETE \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/payment-methods/{{payment_method_id}}' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descripción | Obligatoriedad |
X-Idempotency-Key | Header. String | Permite repetir solicitudes de forma segura sin riesgo de ejecutar la misma acción dos veces por error. Usa un valor exclusivo (por ejemplo, UUID v4 o string aleatoria) para garantizar la unicidad de la requisición. | Obligatorio |
Authorization | Header. String | Clave privada utilizada para autenticar las requisiciones. Utiliza tu Access Token de prueba en el ambiente de desarrollo y tu Access Token productivo en el ambiente de producción. | Obligatorio |
customer_id | Path. String | Identificador único del cliente al cual pertenece el perfil de pago que está siendo modificado. | Obligatorio |
payment_profile_id | Path. String | Identificador único del perfil de pago del cual se eliminará el medio de pago. | Obligatorio |
payment_method_id | Path. String | Identificador único del medio de pago a eliminar del perfil, obtenido en la respuesta a la creación del perfil. | Obligatorio |
En caso de éxito, la respuesta retornará un status 202, lo que confirma su correcto procesamiento.
Esta operación posibilita cancelar un perfil de pago vinculado a un cliente a través de los respectivos IDs, siendo utilizada cuando el perfil no será más utilizado para cobros futuros o cuando es preciso registrar un nuevo perfil desde el inicio.
Para eso, envía una solicitud al endpoint Cancelar perfil de pagoPOST considerando los parámetros listados en la tabla debajo del código.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/cancel' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}'
| Atributo | Tipo | Descripción | Obligatoriedad |
X-Idempotency-Key | Header. String | Permite repetir solicitudes de forma segura sin riesgo de ejecutar la misma acción dos veces por error. Usa un valor exclusivo (por ejemplo, UUID v4 o string aleatoria) para garantizar la unicidad de la requisición. | Obligatorio |
Authorization | Header. String | Clave privada utilizada para autenticar las requisiciones. Utiliza tu Access Token de prueba en el ambiente de desarrollo y tu Access Token productivo en el ambiente de producción. | Obligatorio |
customer_id | Path. String | Identificador único del cliente cuyo perfil de pago está siendo cancelado. | Obligatorio |
payment_profile_id | Path. String | Identificador único del perfil de pago a cancelar, asociado al cliente. | Obligatorio |
En caso de éxito, la respuesta retornará un status 202, lo que confirma su correcto procesamiento.
Si quieres consultar los principales status que puede tomar un perfil de pago, así como los status de sus medios de pago asociados, accede a la documentación.