# Add payment method to a profile

This endpoint allows to add a payment method to a payment profile associated with a customer. A payment profile can contain a maximum of two payment methods, and a new one cannot be added if its status is "CANCELLED". In case of success, the request will return a response with status 201.

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

## 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 to which the payment profile that is being modified belongs. It can be obtained by sending a request to the "Search clients" endpoint.

- `payment_profile_id` (string, required)
  Unique payment profile identifier to modify, associated with the customer. It can be obtained by sending a request to the "Query a client's payment profi||le" endpoint.

- `id` (string, optional)
  Identifier of the payment method selected to add to the profile. If it's a card payment, it will be 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.

- `type` (string, optional)
  Type of payment method selected to add to the profile.
Possible enum values:

  - `credit_card`
  Credit card.

  - `debit_card`
  Debit card.

  - `prepaid_card`
  Prepaid card.

- `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.

- `card_id` (long, optional)
  Unique identifier of the card declared as payment method, associated with the customer. Its value can be obtained in the query to the "Search cards of a client" endpoint.

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

- `payment_method_id` (string, optional)
  Unique identifier for the payment method, automatically generated. It helps to identify and differentiate each payment method.

- `id` (string, optional)
  Identifier of the payment method added to the profile. If it's a card payment, it will show the brand.

- `type` (string, optional)
  Type of payment method added to the profile.

- `card_id` (integer, optional)
  Unique identifier of the card added to the profile, associated with the customer.

- `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.

- `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_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 | 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 | 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 | 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 | 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 | 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/{payment_profile_id}/payment-methods' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "id": "visa",
  "type": "credit_card",
  "token": "12345",
  "card_id": null,
  "default_method": true
  }'
```

## Response example

```json
{
  "payment_method_id": "64abf0f5-3e15-48a5-9be0-a8ac56bbd87a",
  "id": "visa",
  "type": "credit_card",
  "card_id": 1234567890,
  "status": "READY",
  "default_method": true
}
```