AI resources

Profile management

After completing the initial configurations, you will be able to access a set of calls for managing the profiles.

In this section, we present the main available operations to manage a profile and how to execute them.

Create payment profile for the customer

To store customer and card data for future payments, you need to create a payment profile. This profile stores the payment data used by your system, making it easier to reuse for future charges.

To create the customer's payment profile, send a request to the endpoint Create payment profile for the customerPOST considering the parameters listed in the table below the code. 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 with the customer.

curl
curl -X POST \
    'https://api.mercadopago.com/v1/customers/{{customer_id}}/payment-profiles' \
    -H 'Content-Type: application/json' \
    -H 'X-Idempotency-Key: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
    -d '{
  "description": "Payment description",
  "payment_methods": [
    {
      "id": "master",
      "type": "credit_card",
      "card_id": 1234567890,
      "default_method": false
    }
  ]
}'

Attribute	Type	Description	Required
`customer_id`	Path.String	Customer identifier, obtained when creating the customer in the previous step.	Required
`description`	Body.String	Payment profile description. We recommend using this field to categorize contracted service types, plans, or the frequency of the business model.	Optional
`payment_methods`	Body.Object	Contains the payment method information. During profile creation, no more than two payment methods are allowed. When there are two cards, only one will be identified with the `token`, and the other must be identified with the `card_id`. Credit and debit cards can be combined.	Required
`payment_methods.id`	Body.String	Payment method or card brand identifier. 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.Long	Customer's card identifier, obtained in the previous step.	Required
`payment_methods.default_method`	Body.Boolean	Identifies whether the payment method is the default for payment attempts for this customer.	Optional

When creating the payment profile, always use the value AUTO for the sequence_control field. Profiles created with the value MANUAL cause conflicts with the stored_credential.previous_transaction_reference field, which may prevent charges from being processed.

If the request is successful, the response will return status = READY and the payment profile identifier for that customer in the id parameter. This profile_id should 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": "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
    }
  ]
}

Query payment profile

This operation allows you to query the payment profile associated with a specific customer using an ID, returning all stored information. It is useful, for example, for confirming profile data before making a new payment or showing the user the stored payment method information.

To do so, send a request to the endpoint Query a specific payment profileGET 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 {{YOUR_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

For more details on the parameters to be sent in this request and possible processing errors, see our API Reference.

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
    }
  ]
}

Query payment profile list

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 request to the endpoint Query payment profile listGET 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 {{YOUR_ACCESS_TOKEN}}'

Attribute	Type	Description	Required
`customer_id`	Path.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

For more details on the parameters to be sent in this request and possible processing errors, see our API Reference.

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
        }
      ]
    }
  ]
}

Add payment method to a profile

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.

Updates can only be made for one payment method at a time. If you want to add more than one payment method to the same profile, you will need to send a request for each method you want to register.

To add a payment method, send a request to the endpoint Add payment method to a profilePOST 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: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_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

For more details on the parameters to be sent in this request and possible processing errors, see our API Reference.

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.

Delete payment method from profile

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 request to the endpoint Delete payment method from a profileDELETE 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: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_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 to whom the payment profile being modified belongs.	Required
`payment_profile_id`	Path.String	Unique identifier of the payment profile from which the payment method will be deleted.	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.

Cancel payment profile

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 request to the endpoint Cancel payment profilePOST 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: {{SOME_UNIQUE_VALUE}}' \
    -H 'Authorization: Bearer {{YOUR_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.

PreviousConfigure chargeback notificationsLearn how to configure chargeback notifications.

NextOrder statusesConsult the main status in which the creation of an order may result.