Save cards
Save buyer data in your store to speed up future purchases. This configuration allows you to reuse payment data previously tokenized by the Mercado Pago API, avoiding the resending of sensitive information in each transaction. It reduces input errors, simplifies the authorization flow and allows the reuse of cards already validated in previous transactions, which tends to avoid rejections due to data inconsistency and increase payment approval rates.
Below you'll find the documentation to implement and manage saved cards in your integration.
Create the customer and card through the Create customerAPI and Save cardAPI APIs. To do this, you must use your Production Access TokenPrivate key of the application created in Mercado Pago, used in the backend for production operations. You can access it in Your integrations > Application details > Production credentials..
You can perform this operation using the Mercado Pago API or our SDKs.
First, send a POST request to the endpoint /v1/customersAPI to create the customer.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer APP_USR-1*********685765-12*********1b4332e5c*********e077d7679*********664' \ -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" }'
| Field | Description | Required |
email | Email address of the customer. If you use test users, the email must follow the format test_payer_[0-9]{1,10}@testuser.com. | Required |
first_name | Customer's first name. | Optional |
last_name | Customer's last name. | Optional |
phone | Object containing the customer's phone information. | Optional |
phone.area_code | Phone area code. | Optional |
phone.number | Phone number without area code. | Optional |
identification | Object containing the customer's identification information. | Optional |
identification.type | Type of identification document (e.g., CPF, DNI, CNPJ). | Optional |
identification.number | Identification document number. | Optional |
default_address | Name of the customer's default address. | Optional |
address | Object containing the customer's address information. | Optional |
address.id | Address identifier. | Optional |
address.zip_code | Address postal code. | Optional |
address.street_name | Street name. | Optional |
address.street_number | Address number. | Optional |
address.city | Object containing the city information. | Optional |
date_registered | Customer registration date in ISO 8601 format. | Optional |
description | Additional customer description. | Optional |
default_card | Default card identifier. Can be "None" if there is no default card. | Optional |
Then, send a POST request to the endpoint /v1/customers/{id}/cardsAPI with the Customer ID (customer_id) in the path to perform the association, and the card token in the body of the request.
curl
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \ -d '{"token": "9b2d63e00d66a8c721607214cedaecda"}'
| Field | Description | Required |
token | Token generated (usually via SDKs) that securely represents the card's sensitive data. | Required |
After successful creation, objects are identified with these prefixes:
| Prefix | Description | Example |
customer | Customer prefix. | custID+xyz123 |
card | Card prefix. | card_abc456 |
The response will return the following result:
json
{ "id": "123456789-jxOV430go9fx2e", "email": "test_payer_12345@testuser.com", ... "default_card": "1490022319978", "default_address": null, "cards": [{ "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001", ... }], "addresses": [], "live_mode": false }
invalid parameter error with HTTP code 400, check the payment_method_id parameter and make sure the value has been inserted correctly. In addition, when using test users, the customer email must follow the format test_payer_[0-9]{1,10}@testuser.com.Update any customer information, such as address, card, or email. You can perform this operation using the Mercado Pago API or our SDKs.
Send a PUT request to the endpoint /v1/customers/{id}API with the Customer ID (customer_id) in the path and the attributes to modify in the body of the request.
customer_id, send a GET request to the endpoint /v1/customers/searchAPI to get the information. Also, the email field can only be updated if the customer does not yet have an email address associated with their account.curl
curl -X PUT \ 'https://api.mercadopago.com/v1/customers/{id}' \ -H 'Authorization: Bearer ACCESS_TOKEN_ENV' \ -d '{ "email": "user@user.com", "first_name": "john", "last_name": "wagner", "address": { "zip_code": "52", "street_name": "Av. das Nações Unidas", "street_number": "2" }, "phone": { "area_code": "11", "number": "001234567" }, "identification": { "type": "CPF", "number": "12341234" }, "description": "Customer information" }'
The endpoint accepts modification of all attributes described in the table below.
| Attribute | Description |
address | Customer address. |
default_address | ID of the customer's default address for shipping. |
default_card | ID of the customer's default card for making payments. |
description | Additional information or notes about the customer. |
email | Customer email address. Can only be updated if the customer does not yet have an email address associated with their account. |
first_name | Customer first name. |
last_name | Customer last name. |
phone | Customer phone number. |
identification | Customer identification document type and number. |
The response will return the following result:
json
{ "id": "xxxxxxxxxxxxxxxxxxxxx", "email": "user@user.com", "first_name": "john", "last_name": "wagner", "phone": { "area_code": "11", "number": "001234567" }, "identification": { "type": "CPF", "number": "12341234" }, "address": { "zip_code": "52", "street_name": "Av. das Nações Unidas", "street_number": 2 }, "description": "Customer information", "date_created": "2021-05-25T15:36:23.541Z", "metadata": {}, "cards": [ {} ], "addresses": [ {} ] }
customer_id parameter is not sent, the response will return the error "message": "missing customer id".Get specific customer data, such as ID, address, or registration date, through the Customer API. You can perform this operation using the Mercado Pago API or our SDKs.
Send a GET request to the endpoint /v1/customers/searchAPI specifying the customer email as a query parameter.
curl
curl -X GET \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/search?email=test_user_19653727@testuser.com'
The response will show this result:
json
{ "paging": { "limit": 10, "offset": 0, "total": 1 }, "results": [ { "address": { "id": null, "street_name": null, "street_number": null, "zip_code": null }, "addresses": [], "cards": [ { ... } ], "date_created": "2017-05-05T00:00:00.000-04:00", "date_last_updated": "2017-05-05T09:23:25.021-04:00", "date_registered": null, "default_address": null, "default_card": "1493990563105", "description": null, "email": "test_payer_12345@testuser.com", "first_name": null, "id": "123456789-jxOV430go9fx2e", "identification": { "number": null, "type": null }, "last_name": null, "live_mode": false, "metadata": {}, "phone": { "area_code": null, "number": null } } ] }
Associate additional cards with a registered customer. You can perform this operation using the Mercado Pago API or our SDKs.
Send a POST request to the endpoint /v1/customers/{customer_id}/cardsAPI with the Customer ID (customer_id) in the path and card data in the request body.
customer_id) and Card ID (id). The last card saved automatically becomes the DefaultCard.curl
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \ -d '{"token": "9b2d63e00d66a8c721607214cedaecda"}'
The response will return the following result:
json
{ "id": "1493990563105", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "503175", "last_four_digits": "0604", "payment_method": { "id": "master", "name": "master", "payment_type_id": "credit_card", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/master.gif", "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/master.gif" }, "security_code": { "length": 3, "card_location": "back" }, "issuer": { "id": 3, "name": "Mastercard" }, "cardholder": { "name": "Card holdername", "identification": { "number": "12345678", "type": "DNI" } }, "date_created": "2017-05-05T09:22:30.893-04:00", "date_last_updated": "2017-05-05T09:22:30.893-04:00", "customer_id": "255276729-yLOTNHQjpDWw1X", "user_id": "255276729", "live_mode": false }
Query all cards associated with a customer. You can perform this operation using the Mercado Pago API or our SDKs.
Send a GET request to the endpoint /v1/customers/{customer_id}/cardsAPI with the Customer ID (customer_id).
curl
curl -X GET \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
The response will be an array with all saved card objects for the customer.
json
[{ "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001", ... }]
For a customer to make a payment with saved cards, you must capture the security code (CVV) of the card again, since Mercado Pago does not store this data for security reasons. You can perform this operation using the Mercado Pago API or our SDKs.
1. Show list of saved cards
Show the buyer the list of saved cards so they can choose the desired option.
To do so, send a GET request to the endpoint /v1/customers/{customer_id}/cardsAPI with the Customer ID (customer_id) in its path.
curl
curl -X GET \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
2. Create payment form
After showing the saved cards to the buyer, proceed with creating the payment form.
This stage allows the buyer to see where they must include the security code (CVV) of the selected card. To perform it, implement the code below directly in your project.
html
<style> #form-checkout { display: flex; flex-direction: column; max-width: 600px; } .container { height: 18px; display: inline-block; border: 1px solid rgb(118, 118, 118); border-radius: 2px; padding: 1px 2px; } </style> <form id="form-checkout" method="POST" action="/process_payment"> <select type="text" id="form-checkout__cardId"></select> <div id="form-checkout__securityCode-container" class="container"></div> <input name="token" id="token" hidden> <button>Send</button> </form> <script> const mp = new MercadoPago('TEST-2bf9f710-6a6e-47c8-a207-79f5e73b464c'); const securityCodeElement = mp.fields.create('securityCode', { placeholder: "CVV" }).mount('form-checkout__securityCode-container'); const customerCards = [{ "id": "3502275482333", "last_four_digits": "9999", "payment_method": { "name": "amex", }, "security_code": { "length": 4, } }]; function appendCardToSelect() { const selectElement = document.getElementById('form-checkout__cardId'); const tmpFragment = document.createDocumentFragment(); customerCards.forEach(({ id, last_four_digits, payment_method }) => { const optionElement = document.createElement('option'); optionElement.setAttribute('value', id) optionElement.textContent = `${payment_method.name} ended in ${last_four_digits}` tmpFragment.appendChild(optionElement); }) selectElement.appendChild(tmpFragment) } appendCardToSelect(); </script>
3. Capture security code and create token
After showing the saved cards and creating the payment form, the next step is to capture the verification code (CVV) of the card and generate the security token.
To do this, you must create a token by submitting the form with the card ID selected by the customer and the security code (CVV) using the Javascript code below.
javascript
const formElement = document.getElementById('form-checkout'); formElement.addEventListener('submit', e => createCardToken(e)); const createCardToken = async (event) => { try { const tokenElement = document.getElementById('token'); if (!tokenElement.value) { event.preventDefault(); const token = await mp.fields.createCardToken({ cardId: document.getElementById('form-checkout__cardId').value }); tokenElement.value = token.id; console.log(tokenElement); } } catch (e) { console.error('error creating card token: ', e) } }
4. Create the payment
Once you have obtained the card security token in the previous stage, the final step is to create the payment with the corresponding value.
Send a POST request to the endpoint /v1/paymentsAPI including the payer.id and token in the request body, sending the following data.
curl
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/payments' \ -d '{ "transaction_amount": 100, "token": "ff8080814c11e237014c1ff593b57b4d", "installments": 1, "payer": { "type": "customer", "id": "123456789-jxOV430go9fx2e" } }'
| Field | Description |
payer.id | ID of the customer to which the card belongs. |
token | Recently obtained token that replaces the card's sensitive data and CVV. |
transaction_amount | Transaction amount. |
Perform the deletion of a specific card associated with a saved customer, ensuring data is updated. The operation is available via the Mercado Pago API or through the available SDKs.
Send a DELETE request to the endpoint /v1/customers/{customer_id}/cards/{id}API with the Customer ID (customer_id) and Card ID (id) as path parameters.
curl
curl -X DELETE \ 'https://api.mercadopago.com/v1/customers/12123adfasdf123u4u/cards/12123adfasdf123u4u'\ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer TEST-7434*********159-03141*********cee51edf8*********f94f589-1*********' \
The response will return this result:
json
{ "id": "8987269652", "expiration_month": 7, "expiration_year": 2023, "first_six_digits": "503143", "last_four_digits": "6351", "payment_method": { "id": "master", "name": "Mastercard", "payment_type_id": "credit_card", "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/master.gif", "secure_thumbnail": "https://www.mercadopago.com/org-img/MP3/API/logos/master.gif" }, "security_code": { "length": 3, "card_location": "back" }, "issuer": { "id": 24, "name": "Mastercard" }, "cardholder": { "name": "APRO", "identification": { "number": "01234567890", "type": "CPF" } }, "date_created": "2021-03-16T16:08:21.000-04:00", "date_last_updated": "2021-03-16T16:14:40.962-04:00", "customer_id": "470183340-cpunOI7UsIHlHr", "user_id": "470183340", "live_mode": true }