Recursos para IA

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.

Crear cliente y tarjeta

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.. Para hacerlo, sigue estos pasos.

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

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

Para detalles completos sobre los campos y métodos, consulta las referencias de API: Crear cliente y Guardar tarjeta.

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
}

Si la respuesta de la solicitud retorna un error 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.

Actualizar cliente

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.

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.

Si no tienes el 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": [
    {}
  ]
}

Si el parámetro customer_id no se envía, la respuesta retornará el error "message": "missing customer id".

Buscar cliente

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.

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

Agregar nuevas tarjetas a un cliente

Asocia tarjetas adicionales a un cliente registrado. Puedes realizar esta operación mediante la API de Mercado Pago.

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.

Si necesitas eliminar una tarjeta antes de agregar una nueva, 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). 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
}

Listar tarjetas

Consulta todas las tarjetas asociadas a un cliente. Puedes realizar esta operación mediante la API de Mercado Pago.

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",
    ...
}]

Recibir pagos con tarjetas guardadas

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.

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/ordersAPI incluyendo el payer.customer_id y el payment_method.token en el cuerpo de la solicitud, enviando los siguientes datos.

curl
curl --request POST \
  --url https://api.mercadopago.com/v1/orders \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "online",
  "external_reference": "ext_ref_1234",
  "total_amount": "200.00",
  "payer": {
    "customer_id": "{{CUSTOMER_ID}}"
  },
  "transactions": {
    "payments": [
      {
        "amount": "200.00",
        "payment_method": {
          "id": "{{PAYMENT_METHOD_ID}}",
          "type": "{{PAYMENT_METHOD_TYPE}}",
          "token": "{{CARD_TOKEN}}",
          "installments": 1
        }
      }
    ]
  }
}'

Campo	Descripción
`type`	Tipo de order.
`external_reference`	Referencia externa para identificar la order.
`total_amount`	Monto total de la order.
`payer.customer_id`	ID del cliente al que pertenece la tarjeta guardada.
`transactions.payments.amount`	Monto del pago asociado a la order.
`transactions.payments.payment_method.id`	ID del medio de pago.
`transactions.payments.payment_method.type`	Tipo de medio de pago.
`transactions.payments.payment_method.token`	Token de la tarjeta que reemplaza los datos sensibles y el CVV.
`transactions.payments.payment_method.installments`	Cantidad de cuotas del pago.

Eliminar tarjeta

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
}

Recomendações para melhorar a aprovação

Veja os principais cenários que podem ajudar a melhorar a aprovação dos pagamentos.

Dados de indústria

Saiba mais sobre os dados adicionais de indústria que você pode enviar ao criar um pagamento.