Registro con un primer cobro con CVV
Si tu integración requiere que el cliente haga una primera compra, deberás:
- Crear el cliente para registrarlo en tu sistema.
- Crear el pago utilizando el identificador del cliente y el el token de la tarjeta, creado en la etapa de tokenización del medio de pago.
- Asociar esa tarjeta al cliente.
- Crear un perfil de pago a partir de la información del cliente, lo que centralizará los medios de pago asociados y permitirá reutilizarlos en cobros futuros.
Para registrar un medio de pago con un primer cobro con CVV, sigue los pasos 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 }
Utiliza la identificación del cliente y el token de la tarjeta, obtenido en la etapa de tokenización del medio de pago, para crear el pago utilizando la API de Orders.
Para eso, envía un POST al endpoint /v1/ordersAPI utilizando tu Access TokenClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación. y siguiendo las indicaciones para los parámetros obligatorios detallados en la tabla a continuación.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/orders' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \ -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \ -d '{ "type": "online", "processing_mode": "automatic", "total_amount": "200.00", "external_reference": "ext_ref_1234", "payer": { "customer_id": "1234567890" }, "transactions": { "payments": [ { "amount": "200.00", "payment_method": { "id": "master", "type": "credit_card", "token": "1223123", "installments": 1 } } ] } }'
| Atributo | Tipo | Descripción | Obligatoriedad |
Authorization | Header | Hace referencia a tu clave privada, el Access Token de prueba. | Requerido |
X-Idempotency-Key | Header | Llave de idempotencia. Esta llave garantiza que cada solicitud sea procesada una única vez, evitando duplicidades. Utiliza un valor exclusivo en el encabezado de tu solicitud, como un UUID V4 o strings aleatorias. | Requerido |
processing_mode | Body. String | Modo de procesamiento de la order. Los valores posibles son: automatic, para crear y procesar la order en modo automático. automatic_assync, para crear la order y con lógica de reintentos. Para más información, accede a Modo de procesamiento de Orders. | Requerido |
total_amount | Body. String | Monto total de la transacción. | Requerido |
payer.customer_id | Body. String | Identificador del cliente creado en la etapa anterior. | Requerido |
transaction.payments.payment_method.id | Body. String | Identificador del medio de pago. En este caso, es la bandera de cada tarjeta. Para más información, consulta la lista de Medios de pago disponibles. | Requerido |
transaction.payments.payment_method.type | Body. String | Tipo de medio de pago. Para pagos con tarjetas de crédito, debe ser credit_card, para pagos con tarjeta de débito, debe ser debit_card, y para pagos con tarjetas prepagas, prepaid_card. | Requerido |
payment_method.token | Body. String | Token de la tarjeta, obtenido en la etapa de tokenización de medio de pago. | Requerido |
En caso de éxito, la respuesta se verá como el ejemplo a continuación, y el primer pago habrá sido procesado.
json
{ "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "200.00", "total_paid_amount": "200.00", "country_code": "BRA", "user_id": "2021490138", "status": "processed", "status_detail": "accredited", "capture_mode": "automatic_async", "created_date": "2025-04-17T21:41:33.96Z", "last_updated_date": "2025-04-17T21:41:35.144Z", "integration_data": { "application_id": "874202490252970" }, "transactions": { "payments": [ { "id": "PAY01JS2V6CM8KJ0EC4H504R7YE34", "amount": "200.00", "paid_amount": "200.00", "reference_id": "0002yjis6j", "status": "processed", "status_detail": "accredited", "payment_method": { "id": "elo", "type": "credit_card", "token": "1223123", "installments": 1 } } ] } }
Una vez que el primer pago haya sido procesado, y el medio de pago validado, deberás utilizar el mismo token de la tarjeta enviado en el pago para asociarla al cliente previamente creado, y así poder almacenar la información para utilizarla en pagos posteriores.
Para eso, envía un POST al endpoint /v1/customers/{customer_id}/cardsAPI, incluyendo el customer_id en el path de la requisición y el token de la tarjeta en el body, como se indica a continuación. Asegúrate de enviar también tu Access TokenClave privada de la aplicación creada en Mercado Pago, que es utilizada en el backend. Puedes acceder a ella a través de Tus integraciones > Detalles de aplicación..
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers/{{CUSTOMER_ID}}/cards' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -d '{ "token": "1223123" }'
Si la solicitud fue correcta, la respuesta devolverá un id, que es el identificador de la tarjeta. Deberás utilizarlo para terminar con la etapa del registro del medio de pago a partir de un primer cobro.
json
{ "id": 1562188766852, "expiration_month": 6, "expiration_year": 2023, "first_six_digits": 423564, "last_four_digits": 5682, "payment_method": { "id": "visa", "name": "visa", "payment_type_id": "credit_card", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/visa.gif", "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/visa.gif" }, "date_created": "2019-07-03T21:15:35.000Z", "date_last_updated": "2019-07-03T21:19:18.000Z", "customer_id": "448870796-7ZjwhKGxILixxN", "user_id": 448870796, "live_mode": true }
Para almacenar los datos del cliente y su tarjeta para pagos posteriores, es necesario crear un perfil de pago. Este perfil será la estructura que contendrá los datos de pago para ser utilizados en tu sistema y facilitará su reaprovechamiento para próximos cobros.
Para crear el perfil de pago del cliente, 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 id de la tarjeta generado al asociar la tarjeta al cliente. A continuación, puedes ver en la tabla cómo enviar cada uno de los parámetros requeridos.
curl
curl --location '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": "Test", "payment_methods": [ { "id": "master", "type": "credit_card", "card_id": {{CARD_ID}}, "default_method": false } ] }'
| 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 |
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, una sola será identificada con el token, y la otra con el card_id. 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, obtenido en la etapa 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 |
Si la solicitud es exitosa, la respuesta devolverá el status = READY y 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, "status": "READY", "default_method": true } ] }
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.