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, created during the payment method tokenization stage.
- Associate that card with the customer.
- Create a payment profile based on the customer's information, which will centralize the associated payment methods and allow them to be reused in future charges.
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 POST to the endpoint /v1/customersAPI, making sure to include the data collected in your frontend in the request, especially their email, which is required to create the registration.
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" }'
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 }
Use the customer identification and the card token, obtained during the payment method tokenization stage, to create the payment using the Orders API.
To do this, send a POST to the endpoint /v1/ordersAPI 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.
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 } } ] } }'
| 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 |
processing_mode | Body. String | Order processing mode. Possible values are: automatic, to create and process the order in automatic mode. automatic_assync, 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 |
transaction.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 |
transaction.payments.payment_method.type | Body. String | Payment method type. For credit card payments, it must be credit_card, for debit card payments, it must be debit_card, and for prepaid cards, prepaid_card. | Required |
payment_method.token | Body. String | Card token, obtained during the payment method tokenization stage. | Required |
In case of success, the response will look like the example below, and the first payment will have been processed.
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 } } ] } }
Once the first payment has been processed and the payment method validated, you must use the same card token sent in the payment to associate it with the previously created customer, in order to store the information for use in future payments.
To do this, send a POST to the endpoint /v1/customers/{customer_id}/cardsAPI, including the customer_id in the request path and the card token in the body, as indicated below. Make sure to also send your Access TokenPrivate key of the application created in Mercado Pago, used in the backend. You can access it through Your integrations > Application details..
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" }'
If the request was successful, the response will return an id, which is the card identifier. You must use it to complete the payment method registration stage from a first charge.
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 }
To store the customer's data and their card for future payments, you need to create a payment profile. This profile will be the structure that contains the payment data to be used in your system and will facilitate its reuse for future charges.
To create the customer's payment profile, send a POST to the endpoint /v1/customers/{customer_id}/payment-profiles. In the request path, include the customer_id obtained when creating the customer. In the body, provide the card id generated when associating the card to the customer. Below, you can see in the table how to send each of the required parameters.
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 } ] }'
| Field | Type and description | Required |
customer_id | Path. Customer identifier, obtained when creating the customer in the previous stage. | Required |
description | Body, string. Description of the payment profile. We recommend using this field to categorize contracted service types, plans, or business model frequency. | Optional |
payment_methods | Body, object. Contains the payment method information. During profile creation, it does not allow more than two payment methods. When there are two cards, only one will be identified with the token, and the other must be identified with the card_id. It accepts a maximum of two cards (credit or debit). | Required |
payment_methods.id | Body, string. Payment method identifier or card brand. Example: visa, master. | Required |
payment_methods.type | Body, string. Payment method type. Values can be credit_card, debit_card, or prepaid_card. | Required |
payment_methods.card_id | Body, string. Customer's card identifier, obtained in the previous stage. | Required |
payment_methods.default_method | Body, boolean. Identifies whether the payment method is the default for payment attempts for that customer. | Optional |
If the request is successful, the response will return status = READY and the payment profile identifier for that customer, under the id parameter. This profile_id must be used to process payments with the Orders API.
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 } ] }
If needed, you can later update the customer's payment profile, add new payment methods, or even delete it. Check Profile management for more information.