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 token de la tarjeta. Al procesar la order, la tarjeta será asociada al cliente y el perfil de pago será creado automáticamente.
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 una solicitud al endpoint /v1/customersPOST, asegurándote de incluir en la solicitud los datos recopilados en tu frontend, especialmente su e-mail, que es obligatorio para crear el registro.
curlcurl -X POST \ 'https://api.mercadopago.com/v1/customers' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{YOUR_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 }
Al crear el primer pago mediante la API de Orders, puedes almacenar la tarjeta y generar automáticamente el perfil de pago del cliente en la misma solicitud. Para activar este comportamiento, envía stored_credential.store_payment_method con el valor true. De esta manera, no es necesario asociar la tarjeta ni crear el perfil mediante solicitudes adicionales.
Para eso, envía una solicitud al endpoint /v1/ordersPOST utilizando tu Access TokenClave privada utilizada en el backend para autenticar las solicitudes a las APIs de Mercado Pago. Nunca debe compartirse ni exponerse en el frontend. y siguiendo las indicaciones para los parámetros obligatorios detallados en la tabla a continuación.
curlcurl -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 }, "stored_credential": { "store_payment_method": true, "payment_initiator": "customer", "reason": "recurring", "first_payment": true } } ] } }'
| 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 |
type | Body. String | Tipo de order. Para pagos online, el valor debe ser online. | 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, y automatic_async, para crear la order 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 |
transactions.payments.amount | Body. String | Monto del pago. | Requerido |
transactions.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 |
transactions.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, debit_card; y para pagos con tarjetas prepagas, prepaid_card. | Requerido |
transactions.payments.payment_method.token | Body. String | Token de la tarjeta, obtenido en la etapa de tokenización del medio de pago. | Requerido |
transactions.payments.payment_method.installments | Body. Integer | Cantidad de cuotas seleccionada para el pago. | Requerido |
transactions.payments.stored_credential.store_payment_method | Body. Boolean | Indica si el medio de pago debe almacenarse para utilizarlo en cobros futuros. Para crear el perfil automáticamente, envía true. | Requerido |
transactions.payments.stored_credential.payment_initiator | Body. String | Indica quién inició el pago. Para el primer cobro con CVV, envía customer. | Requerido |
transactions.payments.stored_credential.reason | Body. String | Indica el motivo por el que se almacena el medio de pago. Para pagos recurrentes, envía recurring. | Requerido |
transactions.payments.stored_credential.first_payment | Body. Boolean | Indica si este es el primer pago de la recurrencia. Para este flujo, envía true. | Requerido |
En caso de éxito, la respuesta se verá como el ejemplo a continuación, el primer pago habrá sido procesado, y el perfil de pago del cliente habrá sido creado.
json{ "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "200.00", "total_paid_amount": "200.00", "country_code": "COL", "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": "visa", "type": "credit_card", "token": "1223123", "installments": 1 }, "automatic_payments": { "payment_profile_id": "035979dc46c645c4ae12554835b07943" }, "stored_credential": { "store_payment_method": true, "payment_initiator": "customer", "reason": "recurring", "first_payment": true } } ] } }
La respuesta devolverá de forma síncrona el identificador del perfil de pago en el campo transactions.payments.automatic_payments.payment_profile_id.
payment_profile.updated indique que el perfil se encuentra en el status READY. Para recibir este evento, consulta Configurar notificaciones de Perfiles de Pago.Para consultar los principales status que puede tener un perfil de pago, así como los status de sus medios de pago asociados, accede a Estados del perfil y del medio de pago. Si es necesario, podrás actualizar el perfil, agregar nuevos medios de pago o eliminarlo. Consulta Gestión de perfiles para obtener más información.