Registration for future payments
If your integration does not require an initial purchase and you only need to register users, it will be necessary to store the cards for future payments, whether recurring, one-click, or automatic debits. Therefore, after tokenizing the payment method, you must create a payment profile for the customer.
This profile centralizes the associated payment methods and allows them to be reused in future charges. The Profiles API automatically validates each method, avoiding the need for manual validation payments. In case of rejection, it retries with other methods to improve the approval rate.
To register the payment method in the Profiles API and use it for future payments, 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 }
To store the customer's data and their card for future payments, you need to create a payment profile. This profile will validate whether the payment method is useful for making automatic charges and will be the structure that contains the payment data to be used in your system. You will need the customer_id generated in the previous stage and the card card_token, generated during the payment method tokenization.
To create the payment profile for the previously registered customer, 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 token, generated when tokenizing the payment method. Below, you can see in the table how to send each of the required parameters.
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 } ] }'
| 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 |
max_day_overdue | Body, integer. Sets the number of days to retry the payment processing in case of failure or initial rejection. For example, if you send "5" as value, new processing attempts will be made for the next 5 days after the first failure. In case the payment is processed before the set days, the retry logic will be stopped. Value between 1 and 10. | Optional |
statement_descriptor | Body, string. Description that will appear on the customer's payment method statement. Useful for identifying the transaction. Example: MERCADOPAGO. | Optional |
payment_methods | Body, object. Contains the payment method information. During profile creation, it does not allow more than two payment methods. If there is more than one method, 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.token | Body, string. Token that identifies the customer's card, generated during the payment method tokenization. It has a minimum length of 32 characters and a maximum length of 33. | 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 Profiles API will perform an automatic validation of the payment method and return status = READY along with 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, "first_six_digits": 123456, "last_four_digits": 4321, "status": "READY", "default_method": true } ] }
The response will also contain information related to the payment method, including the payment_method_id field, which will be used by the same API to automatically update the card registration for the customer.
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.