Registro para pagos posteriores
Si tu integración no requiere una compra inicial y solo necesitas dar de alta a los usuarios, será necesario almacenar las tarjetas para pagos posteriores, sean recurrentes, one-click o débitos automáticos. Por eso, luego de la tokenización del medio de pago, deberás crear un perfil de pago para el cliente.
Este perfil centraliza los medios de pago asociados y permite reutilizarlos en cobros futuros. La API de Perfiles valida automáticamente cada medio, evitando la realización de pagos de validación manuales. En caso de rechazo, reintenta con otros medios para mejorar la tasa de aprobación.
Para registrar el medio de pago en la API de Perfiles y utilizarlo en pagos posteriores, sigue el paso a paso a continuación.
Comienza por crear el cliente en tu sistema enviando un POST al endpoint /v1/customersAPI, asegurándote de incluir en la solicitud los datos recopilados en tu frontend, especialmente su e-mail, que es obligatorio para crear el registro.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d '{ "email": "jhon@doe.com", "first_name": "Jhon", "last_name": "Doe", "phone": { "area_code": "55", "number": "991234567" }, "identification": { "type": "CPF", "number": "12345678900" }, "default_address": "Home", "address": { "id": "123123", "zip_code": "01234567", "street_name": "Rua Exemplo", "street_number": 123, "city": {} }, "date_registered": "2021-10-20T11:37:30.000-04:00", "description": "Description del user", "default_card": "None" }'
La respuesta a esta solicitud te devolverá el identificador único de este cliente bajo el parámetro id, que deberás utilizar en las siguientes etapas cuando el customer_id te sea requerido.
json
{ "id": "000000001-sT93QZFAsfxU9P5", "email": "jhon@doe.com", "first_name": "Bruce", "last_name": "Wayne", "phone": { "area_code": 23, "number": 12345678 }, "identification": { "type": "DNI", "number": 12345678 }, "address": { "id": "1162600094", "zip_code": "SG1 2AX", "street_name": "Old Knebworth Ln" }, "description": "This is my description", "date_created": "2018-02-20T15:36:23.541Z", "metadata": { "source_sync": "source_ws" }, "default_address": "1162600094", "cards": [ {} ], "addresses": [ {} ], "live_mode": true }
Para almacenar los datos del cliente y su tarjeta para pagos futuros, es necesario crear un perfil de pago. Este perfil permitirá validar si el medio de pago es útil para realizar cargos de manera automática y será la estructura que contendrá los datos de pago que serán utilizados en tu sistema. Deberás contar con el customer_id generado en la etapa anterior y el card_token de la tarjeta, generado durante la tokenización del medio de pago.
Para crear el perfil de pago del cliente previamente registrado, envía un POST al endpoint /v1/customers/{customer_id}/payment-profiles. En el path de la requisición, incluye el customer_id obtenido al crear el cliente. En el body, informa el token de la tarjeta, generado al tokenizar el medio de pago. A continuación, puedes ver en la tabla cómo enviar cada uno de los parámetros requeridos.
curl
curl --location --globoff 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles' \ --header 'X-Idempotency-Key: {{x_idempotency_key}}' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "description": "description", "max_day_overdue": 5, "statement_descriptor": "statement_descriptor", "payment_methods": [ { "id": "{{bandera_de_la_tarjeta}}", "type": "credit_card", "token": "{{card_token}}", "default_method": true } ] }'
| Campo | Tipo y descripción | Obligatoriedad |
customer_id | Path. Identificador del cliente, obtenido al crear el cliente en 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 |
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. 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.token | Body, string. Token que identifica la tarjeta del cliente, generado durante la tokenización del medio de pago. Tiene una longitud mínima de 32 caracteres, y una longitud máxima de 33. | 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 |
Si la solicitud es exitosa, la API de Perfiles realizará una validación automática del medio de pago, y devolverá el status = READY junto con el identificador del perfil de pago para ese cliente, bajo el parámetro id. Este profile_id deberá ser utilizado 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": "Test payment profile", "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, "first_six_digits": 123456, "last_four_digits": 4321, "status": "READY", "default_method": true } ] }
La respuesta también contendrá la información relativa al medio de pago, incluyendo el campo payment_method_id, que será utilizado por la misma API para actualizar automáticamente el registro de la tarjeta para el cliente.
En caso de necesitarlo, posteriormente será posible actualizar el perfil de pago del cliente, incluir nuevos medios de pago, o incluso eliminarlo. Consulta Gestión de perfiles para más información.