Profile management
After completing the initial configurations, you will be able to access a set of calls for managing the created profiles.
In this section, we present the main available operations to manage a profile and how to execute them.
This operation allows you to query a payment profile associated with a specific customer using an ID, which provides access to all registered information, for example, when you need to confirm profile data before making a new payment or show the user the stored payment method information.
To do so, send a GET to the endpoint Query a specific payment profileAPI considering the parameters listed in the table below the code.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{access_token}}'
| Attribute | Type | Description | Required |
customer_id | Path.String | Unique identifier of the customer whose payment profile is being queried. | Required |
payment_profile_id | Path.String | Unique identifier of the payment profile, associated with the customer. | Required |
In case of success, the returned response will follow the format shown in the example below.
json
{ "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T14:03:28.653Z", "description": "Payment description", "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 } ] }
This operation allows you to query the list of payment profiles associated with a customer through their ID, being useful when you need to identify which profiles the customer has to choose which one will be used in subsequent payments.
To do so, send a GET to the endpoint Query payment profile listAPI considering the parameters listed in the table below the code.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles?limit=50&status=READY' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {{access_token}}'
| Attribute | Type | Description | Required |
customer_id | Header.String | Unique identifier of the customer for whom payment profiles are being queried. | Required |
limit | Query.Integer | Pagination limit. Specifies the maximum number of records you want to get in the response. Must be a numeric value between 1 and 100, with 50 being the default value. | Optional |
offset | Query.Integer | Pagination offset. Determines the starting point from which records should be retrieved. Must be a numeric value greater than or equal to zero (0). | Optional |
status | Query.String | Current status of the payment profile. Send it if you want to filter profiles by status. | Optional |
In case of success, the returned response will follow the format shown in the example below.
json
{ "paging": { "total": 10, "total_pages": 100, "offset": 1, "limit": 10 }, "data": [ { "id": "7036b192b541454fa9b9990660dfa1b5", "created_date": "2024-05-22T14:03:28.653Z", "last_updated_date": "2024-05-22T15:03:28.653Z", "description": "Simple description", "max_day_overdue": 5, "statement_descriptor": "Statement description", "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 } ] } ] }
This operation allows you to add a new payment method to the customer's profile or update an existing one, including the possibility of adjusting the default_method field to true or false, thus defining whether it will be the default payment method or not.
To add a payment method, send a POST to the endpoint Add payment method to a profileAPI considering the parameters listed in the table below the code.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/payment-methods' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{access_token}}' \ -d '{ "id": "{{card_brand}}", "type": "credit_card", "token": "{{card_token}}", "default_method": true }'
| Attribute | Type | Description | Required |
X-Idempotency-Key | Header.String | Idempotency key. Allows you to safely repeat requests, preventing the same action from being processed more than once. We recommend using a UUID V4 or random strings. | Required |
Authorization | Header.String | Private key used to authenticate requests. Use your test Access Token in the development environment and your production Access Token in the production environment. | Required |
customer_id | Path.String | Unique identifier of the customer to whom the payment profile being modified belongs. | Required |
payment_profile_id | Path.String | Unique identifier of the payment profile to modify, associated with the customer. | Required |
id | Body.String | Identifier of the selected payment method. For card payments, indicate the brand (visa, master, debmaster, debvisa). | Required |
type | Body.String | Type of the selected payment method: credit_card, debit_card, prepaid_card. | Required |
token | Body.String | Secure token that identifies the payment method. It is required for card transactions and must be between 32 and 33 characters. | Required for card |
card_id | Body.Long | ID of the card associated with the payment method. | Required |
default_method | Body.Boolean | Defines whether this method will be used as the default in future payment attempts. | Optional |
In case of success, the returned response will follow the format shown in the example below.
json
{ "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a", "id": "visa", "type": "credit_card", "card_id": 1234567890, "status": "READY", "default_method": true }
When adding a payment method to a profile, the API automatically performs its validation to verify if it can be used in future charges. The result of this validation is indicated by the status field, which shows the current status of the payment method. Learn more about the payment method status checking our documentation.
This operation allows you to delete a payment method from a profile, which may be necessary when the user chooses to remove a card they no longer want to use or when the method is no longer valid for future charges.
To do so, send a DELETE to the endpoint Delete payment method from a profileAPI considering the parameters listed in the table below the code.
curl
curl -X DELETE \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/payment-methods/{{payment_method_id}}' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{access_token}}'
| Attribute | Type | Description | Required |
X-Idempotency-Key | Header.String | Allows you to safely repeat requests without the risk of executing the same action twice by mistake. Use a unique value (for example, UUID v4 or random string) to ensure request uniqueness. | Required |
Authorization | Header.String | Private key used to authenticate requests. Use your test Access Token in the development environment and your production Access Token in the production environment. | Required |
customer_id | Path.String | Unique identifier of the customer whose payment profile is being canceled. | Required |
payment_profile_id | Path.String | Unique identifier of the payment profile to cancel, associated with the customer. | Required |
payment_method_id | Path.String | Unique identifier of the payment method to delete from the profile, obtained in the response to profile creation. | Required |
In case of success, the response will return a status 202, which confirms its correct processing.
This operation allows you to cancel a payment profile linked to a customer through their respective IDs, being used when the profile will no longer be used for future charges or when it is necessary to register a new profile from the beginning.
To do so, send a POST to the endpoint Cancel payment profileAPI considering the parameters listed in the table below the code.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles/{{payment_profile_id}}/cancel' \ -H 'Content-Type: application/json' \ -H 'X-Idempotency-Key: {{x_idempotency_key}}' \ -H 'Authorization: Bearer {{access_token}}'
| Attribute | Type | Description | Required |
X-Idempotency-Key | Header.String | Allows you to safely repeat requests without the risk of executing the same action twice by mistake. Use a unique value (for example, UUID v4 or random string) to ensure request uniqueness. | Required |
Authorization | Header.String | Private key used to authenticate requests. Use your test Access Token in the development environment and your production Access Token in the production environment. | Required |
customer_id | Path.String | Unique identifier of the customer whose payment profile is being canceled. | Required |
payment_profile_id | Path.String | Unique identifier of the payment profile to cancel, associated with the customer. | Required |
In case of success, the response will return a status 202, which confirms its correct processing.
If you want to check the main statuses that a payment profile can have, as well as the statuses of its associated payment methods, access the documentation.