Registration with a first payment with CVV
If your integration requires the customer to make a first purchase, you must:
- Create the customer to register them in your system.
- Create the payment using the customer identifier and the card token. When processing the order, the card will be associated with the customer and the payment profile will be created automatically.
To register a payment method with a first payment with CVV, follow the steps below.
Start by creating the customer in your system by sending a request to the endpoint /v1/customersPOST, making sure to include the data collected in your frontend in the request, especially their email, which is required to create the registration.
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" }'
The response to this request will return the unique identifier for this customer under the id parameter, which you must use in the following stages when the customer_id is required.
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 }
When creating the first payment through the Orders API, you can store the card and automatically generate the customer's payment profile in the same request. To enable this behavior, send stored_credential.store_payment_method with the value true. This way, you do not need to associate the card or create the profile through additional requests.
To do this, send a request to the endpoint /v1/ordersPOST using your Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Application details. and following the instructions for the required parameters detailed in the table below.
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 } } ] } }'
| Attribute | Type | Description | Required |
Authorization | Header | Refers to your private key, the test Access Token. | Required |
X-Idempotency-Key | Header | Idempotency key. This key ensures that each request is processed only once, avoiding duplicates. Use a unique value in your request header, such as a UUID V4 or random strings. | Required |
type | Body. String | Order type. For online payments, the value must be online. | Required |
processing_mode | Body. String | Order processing mode. Possible values are: automatic, to create and process the order in automatic mode, and automatic_async, to create the order with retry logic. For more information, access Order processing modes. | Required |
total_amount | Body. String | Total transaction amount. | Required |
payer.customer_id | Body. String | Customer identifier created in the previous stage. | Required |
transactions.payments.amount | Body. String | Payment amount. | Required |
transactions.payments.payment_method.id | Body. String | Payment method identifier. In this case, it is the card brand. For more information, check the list of Available payment methods. | Required |
transactions.payments.payment_method.type | Body. String | Payment method type. For credit card payments, it must be credit_card; for debit card payments, debit_card; and for prepaid cards, prepaid_card. | Required |
transactions.payments.payment_method.token | Body. String | Card token, obtained during the payment method tokenization stage. | Required |
transactions.payments.payment_method.installments | Body. Integer | Number of installments selected for the payment. | Required |
transactions.payments.stored_credential.store_payment_method | Body. Boolean | Indicates whether the payment method must be stored for use in future charges. To create the profile automatically, send true. | Required |
transactions.payments.stored_credential.payment_initiator | Body. String | Indicates who initiated the payment. For the first payment with CVV, send customer. | Required |
transactions.payments.stored_credential.reason | Body. String | Indicates why the payment method is being stored. For recurring payments, send recurring. | Required |
transactions.payments.stored_credential.first_payment | Body. Boolean | Indicates whether this is the first recurring payment. For this flow, send true. | Required |
In case of success, the response will look like the example below, the first payment will have been processed, and the customer's payment profile will have been created.
json{ "id": "ORD01JS2V6CM8KJ0EC4H502TGK1WP", "type": "online", "processing_mode": "automatic", "external_reference": "ext_ref_1234", "total_amount": "200.00", "total_paid_amount": "200.00", "country_code": "CHL", "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 } } ] } }
The response will synchronously return the payment profile identifier in the transactions.payments.automatic_payments.payment_profile_id field.
payment_profile.updated notification to indicate that the profile has reached the READY status. To receive this event, see Configure Payment Profile notifications.To check the main statuses a payment profile can have, as well as the statuses of its associated payment methods, see Profile and payment method statuses. If necessary, you can update the profile, add new payment methods, or delete it. See Profile management for more information.