# Create payment profile

This endpoint allows to create a payment profile for a customer to reuse that information for automatic or recurring payments. In case of success, the request will return a response with status 201.

**POST** `/v1/customers/{customer_id}/payment-profiles`

## Request parameters

### Header

- `X-Idempotency-Key` (string, required)
  This feature allows you to safely retry requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical payments. To ensure that each request is unique, it's important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. The header accepts values between 1 and 64 characters.

### Path

- `customer_id` (string, required)
  Unique customer identifier for which the payment profile is being created. Can be obtained by sending a request to the "Search clients" endpoint.

- `description` (string, optional)
  Description of the customer's payment profile, that will be used to facilitate the identification of the nature of the charges linked to this profile within the integrator or seller's management ecosystem. Text field used to categorize the type of service, contracted plan, or frequency of the business model.

- `max_day_overdue` (integer, optional)
  It 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 setted days, the retry logic will be stopped. It must be a value between 1 and 10.

- `statement_descriptor` (string, optional)
  Description for the payment to be shown on the client's card statement. (e.g. MERCADOPAGO)

- `sequence_control` (string, optional)
  It defines whether the subscription data, such as the information that determines the payment sequence, should be sent manually or automatically. The possible values are:
Possible enum values:

  - `AUTO`
  The subscription data is sent automatically. It is the default value if the field is not sent.

  - `MANUAL`
  The subscription data must be sent manually.

- `payment_methods` (array, optional)
  It contains information about the payment method. There must be at least one payment method present in the list to ensure that the payment profile is functional, and can contain a maximum of two payment methods. In case of creating a profile with two cards as payment methods, only one of them can contain the "token"; that is, the other one must be registered with the "card_id".

  - `payment_methods[].id` (string, optional)
  Identifier of the payment method selected to make the payment. If it's a card payment, it will show the brand.
Possible enum values:

  - `visa`
  Visa credit card.

  - `master`
  Master credit card.

  - `amex`
  American Express credit card.

  - `diners`
  Diners Club credit card.

  - `naranja`
  Naranja credit card.

  - `cabal`
  Cabal credit card.

  - `cencosud`
  Cencosud credit card.

  - `argencard`
  Argencard credit card.

  - `hipercard`
  Hipercard credit card.

  - `elo`
  Elo credit card.

  - `debelo`
  Elo debit card.

  - `debmaster`
  Master debit card.

  - `debvisa`
  Visa debit card.

  - `debcabal`
  Cabal debit card.

  - `maestro`
  Maestro debit card.

  - `payment_methods[].type` (string, optional)
  Type of payment method selected to make the payment.
Possible enum values:

  - `credit_card`
  Credit card.

  - `debit_card`
  Debit card.

  - `prepaid_card`
  Prepaid card.

  - `payment_methods[].token` (string, optional)
  It is a mandatory field for card payments, as it is the token that identifies the card and contains its data securely. It has a minimum length of 32 characters, and a maximum length of 33. If you don't know how to generate it, go to the Automatic Payments documentation.

  - `payment_methods[].card_id` (long, optional)
  Unique identifier of the card declared as payment method, associated with the customer for which the payment profile is being created. Its value can be obtained in the query to the "Search cards of a client" endpoint.

  - `payment_methods[].default_method` (boolean, optional)
  It identifies if the payment method is the default for making payment attempts for that client. In case of creating a payment profile with the two allowed payment methods, it should be indicated which of the two is the default.

## Response parameters

- `id` (string, optional)
  Unique identifier of the payment profile, automatically generated by Mercado Pago.

- `created_date` (string, optional)
  Creation date of the payment profile, in "yyyy-MM-ddTHH:mm:ss.sssZ" format.

- `last_updated_date` (string, optional)
  Last update date of the payment profile, in "yyyy-MM-ddTHH:mm:ss.sssZ" format.

- `description` (string, optional)
  Description of the customer's payment profile, that will be used to facilitate the identification of the nature of the charges linked to this profile within the integrator or seller's management ecosystem.

- `max_day_overdue` (integer, optional)
  It 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 setted days, the retry logic will be stopped. Value between 1 and 10.

- `statement_descriptor` (string, optional)
  Description for the payment to be shown on the client'scard statement.

- `status` (string, optional)
  Current status of the payment profile in the system. The possible values are:
Possible enum values:

  - `PENDING`
  Initial status when creating the profile with cards as payment method or if the profile is created without any payment method. It will remain in this status until the test payment is made, when it will pass to the status "READY" or "CANCELLED".

  - `READY`
  Status that indicates that the profile has a valid card identification and was created successfully.

  - `CANCELLED`
  Status that indicates that the profile was canceled because it does not have an approved payment method or because it cannot query the associated payment method.

- `sequence_control` (string, optional)
  It defines whether the subscription data, such as the information that determines the payment sequence, should be sent manually ("MANUAL") or automatically ("AUTO").

- `payment_methods` (array, optional)
  It contains information about the payment methods associated with the profile. When there are two cards, one can contain the "token" and the other the "card_id".

  - `payment_methods[].payment_method_id` (string, optional)
  Unique identifier for the payment method, automatically generated. It helps to identify and differentiate each payment method, in case there are more than one registered.

  - `payment_methods[].id` (string, optional)
  Identifier of the payment method selected to make the payment. If it's a card payment, it will show the brand.

  - `payment_methods[].type` (string, optional)
  Type of payment method selected to make the payment.

  - `payment_methods[].card_id` (integer, optional)
  Unique identifier of the card declared as payment method, associated with the customer for which the payment profile is being created.

  - `payment_methods[].status` (string, optional)
  Status of the payment method. It indicates if the payment method was tested and is ready for payment processing. The possible values are:
Possible enum values:

  - `PENDING`
  Status assigned to approved card payments, whose response does not include their ID. The payment method remains pending due to an asynchronous card registration.

  - `READY`
  The payment method was tested and is ready for payment processing.

  - `REJECTED`
  The payment method was rejected in the test payment.

  - `DISABLED`
  The payment method was disabled.

  - `payment_methods[].default_method` (boolean, optional)
  It identifies if the payment method is the default for making payment attempts for that client.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | payment_method_id_cannot_be_blank | The request failed because no "payment_method_id" was sent. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | payment_methods_cannot_be_null | The request failed because no payment method information was sent. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | payment_methods_required | The request failed because no object with payment method information was sent. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | payment_method_token_or_card_id_required | The request failed because no "card_token" or "card_id" was sent when at least one of them is required for the payment profile creation. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | html_insertion_not_allowed | Request failed because HTML tags were inserted in fields that do not allow them. More information can be found in "details". Verify that the data sent is correct and try again. |
| 400 | max_day_overdue_out_of_range | The request failed because the value sent for the "max_day_overdue" field is not within the allowed range. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | validation_error | The request failed due to a validation error for the senti fields. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | payload_failed | The request failed, possibly due to formatting or invalid data errors. More details can be found in "details". Verify that the data sent is correct and try again. |
| 400 | multiple_default_payment_methods_not_allowed | The request failed because the maximum number of default payment methods was exceeded. Remember that you can only define one payment method with the "default_method" = true. |
| 400 | more_than_two_payment_methods_not_allowed | The request failed because more than two objects containing payment method information were sent, which is the maximum allowed for the profile creation. Review the request and verify that you have sent that node correctly. |
| 400 | two_cards_with_token_not_allowed | Request failed because it is not allowed to create a payment profile with two cards containing "card_token" as payment methods. Review the request to send both objects correctly. |
| 400 | duplicate_payment_method_not_allowed | Request failed due to a duplicated payment method. It is not allowed to add a payment method that already exists in the payment profile. |
| 400 | invalid_site_id_for_fintoc | Request failed because the site_id associated with the user who is creating the payment profile is not valid for fintoc, a payment method that is only available for Chile. Verify that you are sending the correct credentials or create a profile using a valid payment method for your country. |
| 400 | profile_modification_not_allowed | Request failed because it's not allowed to change profile with canceled status. Verify that the payment profile status is correct before attempting changes. |
| 400 | payment_method_validation_failed | Request failed because the payment method validation could not be done. Try again later and, if the problem persists, contact Support with error details. |
| 400 | customer_id_mismatch | Request failed because the "customer_id" sent does not match the payment profile. Verify if the correct value was sent and try again. |
| 400 | caller_id_mismatch | Request failed because the "caller_id" sent does not match the payment profile. Verify if the correct value was sent and try again. |
| 400 | site_id_mismatch | Request failed because the "site_id" does not match the payment profile. Verify if the correct value was sent and try again. |
| 400 | unknown_error_occurred | Unknown error. Contact Support for more information. |
| 401 | header_missing | Request failed because a required header is missing. Make sure that all necessary authentication headers are being sent. |
| 401 | Unauthorized Access Token | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 402 | payment_method_not_approved | Request failed because the payment for the payment method verification was not approved. Verify that the payment information is valid and sufficient to complete the transaction or use a different payment method. |
| 404 | resource_not_found | Request failed because the payment profile was not found. Verify that the payment profile ID, customer ID and caller ID are correct. |
| 429 | Too Many Requests | Request failed because the request rate has been exceeded. Reduce the frequency or implement a retry system with exponential backoff. |
| 500 | internal_server_error | Request failed due to an internal server error. Please try again later and, if the problem persists, contact Support with error details. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/customers/{customer_id}/payment-profiles' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "description": "Test payment profile",
  "max_day_overdue": 5,
  "statement_descriptor": "Test Descriptor",
  "sequence_control": "MANUAL",
  "payment_methods": [
  {
  "id": "visa",
  "type": "credit_card",
  "token": "12345",
  "card_id": null,
  "default_method": true
  }
  ]
  }'
```

## Response example

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