Guardar tarjetas
Guarda los datos del comprador en tu tienda para agilizar las próximas compras. Esta configuración permite reutilizar datos de pago previamente tokenizados por la API de Mercado Pago, evitando el reenvío de información sensible en cada transacción. Reduce errores de entrada, simplifica el flujo de autorización y permite reutilizar tarjetas ya validadas en transacciones anteriores, lo que tiende a evitar rechazos por inconsistencia de datos y aumentar la tasa de aprobación de los pagos.
A continuación encontrarás las documentaciones para implementar y gestionar tarjetas guardadas en tu integración.
Crea el cliente y la tarjeta a través de las APIs de Crear clienteAPI y Guardar tarjetaAPI. Para eso, deberás utilizar tu Access Token de producciónClave privada de la aplicación creada en Mercado Pago, utilizada en el backend para operaciones de producción. Puedes acceder a ella en Tus integraciones > Detalles de la aplicación > Credenciales de producción..
Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
Primero, envía una solicitud POST al endpoint /v1/customersAPI para crear el cliente.
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" }'
| Campo | Descripción | Obligatoriedad |
email | Dirección de correo electrónico del cliente. Si utilizas usuarios de prueba, el e-mail debe seguir el formato test_payer_[0-9]{1,10}@testuser.com. | Obligatorio |
first_name | Nombre del cliente. | Opcional |
last_name | Apellido del cliente. | Opcional |
phone | Objeto que contiene la información del teléfono del cliente. | Opcional |
phone.area_code | Código de área del teléfono. | Opcional |
phone.number | Número de teléfono sin código de área. | Opcional |
identification | Objeto que contiene la información de identificación del cliente. | Opcional |
identification.type | Tipo de documento de identidad (por ejemplo: CPF, DNI, CNPJ). | Opcional |
identification.number | Número del documento de identidad. | Opcional |
default_address | Nombre de la dirección predeterminada del cliente. | Opcional |
address | Objeto que contiene la información de la dirección del cliente. | Opcional |
address.id | Identificador de la dirección. | Opcional |
address.zip_code | Código postal de la dirección. | Opcional |
address.street_name | Nombre de la calle. | Opcional |
address.street_number | Número de la dirección. | Opcional |
address.city | Objeto que contiene la información de la ciudad. | Opcional |
date_registered | Fecha de registro del cliente en formato ISO 8601. | Opcional |
description | Descripción adicional del cliente. | Opcional |
default_card | Identificador de la tarjeta predeterminada. Puede ser "None" si no hay tarjeta predeterminada. | Opcional |
Luego, envía una solicitud POST al endpoint /v1/customers/{id}/cardsAPI con el ID del Cliente (customer_id) para realizar la asociación en el path, y el token de tarjeta en el body de la requisición.
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"}'
| Campo | Descripción | Obligatoriedad |
token | Token generado (generalmente vía SDKs) que representa los datos sensibles de la tarjeta de forma segura. | Obligatorio |
Después de la creación exitosa, los objetos se identifican con estos prefijos:
| Prefijo | Descripción | Ejemplo |
customer | Prefijo del cliente. | custID+xyz123 |
card | Prefijo de la tarjeta. | card_abc456 |
La respuesta traerá el siguiente resultado:
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 con código HTTP 400, revisa el parámetro payment_method_id y asegúrate de que el valor haya sido insertado de manera correcta. Además, al utilizar usuarios de prueba, el e-mail del cliente debe seguir obligatoriamente el formato test_payer_[0-9]{1,10}@testuser.com.Actualiza cualquier información de un cliente, como dirección, tarjeta o e-mail. Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
Envía una solicitud PUT al endpoint /v1/customers/{id}API con el ID del Cliente (customer_id) en el path y los atributos a modificar en el body de la requisición.
customer_id, envía una solicitud GET al endpoint /v1/customers/searchAPI para obtener la información. Además, el campo email solo puede actualizarse si el cliente aún no tiene un email asociado.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": "Información del cliente" }'
El endpoint acepta la modificación de todos los atributos descritos en la tabla a continuación.
| Atributo | Descripción |
address | Dirección del cliente. |
default_address | ID de la dirección predeterminada del cliente para envíos. |
default_card | ID de la tarjeta predeterminada del cliente para realizar pagos. |
description | Información adicional o notas sobre el cliente. |
email | Dirección de correo electrónico del cliente. Solo puede actualizarse si el cliente aún no tiene una dirección de e-mail asociada en su cuenta. |
first_name | Nombre del cliente. |
last_name | Apellido del cliente. |
phone | Número de teléfono del cliente. |
identification | Tipo y número de documento de identificación del cliente. |
La respuesta traerá el siguiente resultado:
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": "Información del cliente", "date_created": "2021-05-25T15:36:23.541Z", "metadata": {}, "cards": [ {} ], "addresses": [ {} ] }
customer_id no se envía, la respuesta retornará el error "message": "missing customer id".Obtén datos específicos de un cliente, como ID, dirección o fecha de registro, a través de la API de Clientes. Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
Envía una solicitud GET al endpoint /v1/customers/searchAPI especificando el e-mail del cliente como parámetro de consulta.
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'
La respuesta mostrará este resultado:
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 } } ] }
Asocia tarjetas adicionales a un cliente registrado. Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
Envía una solicitud POST al endpoint /v1/customers/{customer_id}/cardsAPI con el ID del Cliente (customer_id) en el path y los datos de la tarjeta en el body de la solicitud.
customer_id) y el ID de la Tarjeta (id). La última tarjeta guardada se convierte automáticamente en el 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"}'
La respuesta traerá el siguiente resultado:
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 }
Consulta todas las tarjetas asociadas a un cliente. Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
Envía una solicitud GET al endpoint /v1/customers/{customer_id}/cardsAPI con el ID del Cliente (customer_id) en el path.
curl
curl -X GET \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
La respuesta será un array con todos los objetos de tarjeta guardados para el cliente.
json
[{ "id": "1490022319978", "expiration_month": 12, "expiration_year": 2020, "first_six_digits": "415231", "last_four_digits": "0001", ... }]
Para que un cliente efectúe un pago con tarjetas guardadas, debes capturar nuevamente el código de seguridad (CVV) de la tarjeta, ya que Mercado Pago no almacena este dato por razones de seguridad. Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
1. Mostrar lista de tarjetas guardadas
Muestra al comprador la lista de tarjetas guardadas para que elija la opción deseada.
Para hacerlo, envía una solicitud GET al endpoint /v1/customers/{customer_id}/cardsAPI con el ID del Cliente (customer_id) en el path.
curl
curl -X GET \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ 'https://api.mercadopago.com/v1/customers/CUSTOMER_ID/cards' \
2. Crear el formulario de pago
Después de mostrar las tarjetas guardadas al comprador, procede con la creación del formulario de pago.
Esta etapa permite al comprador ver dónde debe incluir el código de seguridad (CVV) de la tarjeta seleccionada. Para realizarla, implementa el código a continuación directamente en tu proyecto.
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>Enviar</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. Capturar el código de seguridad y crear el token
Después de mostrar las tarjetas guardadas y crear el formulario de pago, el próximo paso es capturar el código de verificación (CVV) de la tarjeta y generar el token de seguridad.
Para ello, debes crear un token enviando el formulario con el ID de la tarjeta seleccionado por el cliente y el código de seguridad (CVV) utilizando el código Javascript a continuación.
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. Crear el pago
Una vez que hayas obtenido el token de seguridad de la tarjeta en la etapa anterior, el paso final es crear el pago con el valor correspondiente.
Envía una solicitud POST al endpoint /v1/paymentsAPI incluyendo el payer.id y el token en el cuerpo de la solicitud, enviando los siguientes datos.
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" } }'
| Campo | Descripción |
payer.id | ID del cliente al cual pertenece la tarjeta. |
token | Token recién obtenido que sustituye los datos sensibles de la tarjeta y el CVV. |
transaction_amount | Valor de la transacción. |
Elimina una tarjeta específica de un cliente guardado para mantener actualizada su información. Puedes realizar esta operación mediante la API de Mercado Pago o utilizando nuestros SDKs.
Envía una solicitud DELETE al endpoint /v1/customers/{customer_id}/cards/{id}API con el ID del Cliente (customer_id) y el ID de la Tarjeta (id) como parámetros de path.
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*********' \
La respuesta traerá este resultado:
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": "19119119100", "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 }
Crea una nueva dirección para un cliente guardado mediante la API de Mercado Pago. Esto te permite asociar múltiples direcciones a un mismo cliente, facilitando la gestión de envíos y la experiencia de compra.
Para hacerlo, envía una solicitud POST al endpoint /v1/customers/{id}/addressesAPI y incluye el ID del Cliente (customer_id) en el path, junto con los atributos de la dirección detallados en la tabla a continuación.
curl
curl -X POST \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ -d '{ "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabajo", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" } }'
| Campo | Descripción | Obligatoriedad |
zip_code | Código postal de la dirección. | Obligatorio |
street_name | Nombre de la calle. | Obligatorio |
street_number | Número de la calle. | Opcional |
name | Nombre o etiqueta de la dirección (por ejemplo: "Casa", "Trabajo"). | Opcional |
phone | Número de teléfono asociado a la dirección. | Opcional |
floor | Número de piso. | Opcional |
apartment | Identificador del departamento. | Opcional |
comments | Comentarios adicionales sobre la dirección. | Opcional |
city | Objeto con el nombre de la ciudad. | Opcional |
state | Objeto con el ID y nombre del estado o provincia. | Opcional |
neighborhood | Objeto con el nombre del barrio. | Opcional |
La respuesta traerá el siguiente resultado:
json
{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabajo", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }
Obtén los datos de las direcciones de un cliente guardado mediante la API de Mercado Pago. Puedes consultar todas las direcciones asociadas al cliente o recuperar una dirección específica por su ID, lo que te permite gestionar y mostrar las opciones de envío disponibles. Para eso, utiliza los endpoints a continuación.
Listar direcciones
Consulta todas las direcciones asociadas a un cliente. Envía una solicitud GET al endpoint /v1/customers/{id}/addressesAPI con el ID del Cliente (customer_id) como parámetro de path.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN'
La respuesta será un array con todos los objetos de dirección guardados para el cliente.
json
[{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabajo", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }]
Obtener dirección
Obtén los datos de una dirección específica de un cliente. Envía una solicitud GET al endpoint /v1/customers/{id}/addresses/{address_id}API con el ID del Cliente (customer_id) y el ID de la Dirección (address_id) como parámetros de path.
curl
curl -X GET \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses/{address_id}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN'
La respuesta traerá el siguiente resultado:
json
{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabajo", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }
Actualiza los datos de una dirección existente de un cliente guardado mediante la API de Mercado Pago. Esta operación te permite modificar cualquier atributo de la dirección, como código postal, calle, número, o información adicional, y mantener los datos del cliente siempre actualizados.
Envía una solicitud PUT al endpoint /v1/customers/{id}/addresses/{address_id}API con el ID del Cliente (customer_id) y el ID de la Dirección (address_id) como parámetros de path, y los atributos a modificar en el cuerpo de la solicitud.
curl
curl -X PUT \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses/{address_id}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN' \ -d '{ "zip_code": "04543907", "street_name": "Rua Funchal", "street_number": 418, "name": "Escritório Novo", "phone": "11912345678", "floor": "12", "apartment": "1201", "comments": "Edifício E-Tower, entrada pela recepção principal", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Vila Olímpia" } }'
| Atributo | Descripción |
zip_code | Código postal de la dirección. |
street_name | Nombre de la calle. |
street_number | Número de la calle. |
name | Nombre o etiqueta de la dirección. |
phone | Número de teléfono asociado a la dirección. |
floor | Número de piso. |
apartment | Identificador del departamento. |
comments | Comentarios adicionales sobre la dirección. |
city | Objeto con el nombre de la ciudad. |
state | Objeto con el ID y nombre del estado o provincia. |
neighborhood | Objeto con el nombre del barrio. |
La respuesta traerá el siguiente resultado:
json
{ "id": "1162600213", "zip_code": "04543907", "street_name": "Rua Funchal", "street_number": 418, "name": "Escritório Novo", "phone": "11912345678", "floor": "12", "apartment": "1201", "comments": "Edifício E-Tower, entrada pela recepção principal", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Vila Olímpia" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T16:00:00.000Z" }
Si no envías el parámetro customer_id o address_id, recibirás el siguiente error:
json
{ "message": "missing customer id or address id" }
Elimina una dirección específica de un cliente guardado mediante la API de Mercado Pago. Esta operación te permite mantener actualizada la información de direcciones del cliente, eliminando aquellas que ya no son necesarias.
Envía una solicitud DELETE al endpoint /v1/customers/{id}/addresses/{address_id}API con el ID del Cliente (customer_id) y el ID de la Dirección (address_id) como parámetros de path.
curl
curl -X DELETE \ 'https://api.mercadopago.com/v1/customers/{customer_id}/addresses/{address_id}' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ENV_ACCESS_TOKEN'
La respuesta traerá este resultado:
json
{ "id": "1162600213", "zip_code": "01310100", "street_name": "Avenida Paulista", "street_number": 1000, "name": "Trabajo", "phone": "11987654321", "floor": "10", "apartment": "101A", "comments": "Próximo ao metrô Trianon-MASP", "city": { "name": "São Paulo" }, "state": { "id": "BR-SP", "name": "São Paulo" }, "neighborhood": { "name": "Bela Vista" }, "date_created": "2021-05-25T15:36:23.541Z", "date_last_updated": "2021-05-25T15:36:23.541Z" }