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 creados.
En esta sección, presentamos las principales operaciones disponibles para administrar un perfil y cómo ejecutarlas.
Esta operación permite consultar un perfil de pago asociado a un cliente específico utilizando un ID, lo que permite acceder a todas la información registrada, por ejemplo, cuando es necesario 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 un GET al endpoint Consultar un perfil de pago específicoAPI considerando los parámetros listados en la tabla debajo del código.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{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 un GET al endpoint Consultar lista de perfiles de pagoAPI considerando los parámetros listados en la tabla debajo del código.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles?limit=50&status=READY' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{access_token}}'
| Atributo | Tipo | Descripción | Obligatoriedad |
customer_id | Header. 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 un POST al endpoint Agregar medio de pago a un perfilAPI considerando los parámetros listados en la tabla debajo del código.
curl
curl -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: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{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 un DELETE al endpoint Eliminar medio de pago de un perfilAPI considerando los parámetros listados en la tabla debajo del código.
curl
curl -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: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{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 |
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 un POST al endpoint Cancelar perfil de pagoAPI considerando los parámetros listados en la tabla debajo del código.
curl
curl -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: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{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.