El Card Updater es una funcionalidad de Mercado Pago que recupera y actualiza automáticamente los datos de tarjetas guardadas, garantizando la continuidad de los pagos recurrentes sin CVV cuando una tarjeta vence, se reemplaza o sufre cualquier alteración en su ciclo de vida.

Siempre que ocurre una alteración en el ciclo de vida de una tarjeta, ya sea vencimiento, pérdida, robo, actualización de categoría o rectificación de datos, Mercado Pago realiza la sincronización directa con las banderas y emisores. Una vez actualizada la base, dispara una notificación Webhook a tu aplicación para que puedas actualizar tus registros de forma asíncrona y automática.

    sequenceDiagram
        participant E as Emisor / Bandera
        participant MP as Mercado Pago
        participant App as Tu aplicación
        E->>MP: Cambio en el ciclo de vida de la tarjeta
        MP->>MP: Sincroniza credenciales en la base de datos
        MP->>App: Webhook: card.updated
        App-->>MP: HTTP 200 / 201
        App->>MP: GET /v1/customers/{id}/cards (opcional)
        MP-->>App: Datos de la nueva tarjeta
        App->>App: Actualiza card_id para próximos cobros
    

La implementación del tópico de notificación Card Updater mitiga pagos rechazados por datos obsoletos, subsanando errores como:

• Errores de entrada de datos: Bad_Filled_Card_Number, Bad_Filled_Card_Date, Bad_Filled_Security_Code.
• Restricciones de estado de la tarjeta: Card_Disabled, Blacklist, Call_For_Authorized, Other_Reason.
• Sustitución de credenciales: transiciones de tarjetas vencidas o migración de categoría (por ejemplo, de Gold a Black).

Al procesar el evento card.updated, tu aplicación garantiza la continuidad de la facturación sin intervención manual del cliente final.

Dependiendo de la alteración realizada por la bandera o el emisor, el identificador de la tarjeta (card_id) puede sufrir dos tipos de modificaciones:

• Cambio de card_id: ocurre cuando se genera un nuevo número de tarjeta (PAN). La notificación Webhook disparada por Mercado Pago enviará el campo new_card_id, que reemplaza el identificador anterior.
• Actualización silenciosa: para correcciones menores, el card_id permanece igual y la actualización ocurre de forma transparente en la base de Mercado Pago.

Asimismo, todas las tarjetas generadas por el Card Updater se añaden automáticamente al respectivo Cliente guardado en Mercado Pago, con un límite de hasta 20 tarjetas. Para validar los detalles de la nueva tarjeta o listar todas las tarjetas activas de un cliente, utiliza el endpoint /v1/customers/{id}/cardsGET.

Mantén siempre actualizada la referencia del card_id en tu base de datos después de recibir cada notificación de tipo card.updated. En los casos de cambio de ID, debes garantizar que todos los próximos pagos se ejecuten utilizando el new_card_id. El uso de un card_id antiguo después de la actualización resultará en una alta probabilidad de rechazo en los pagos.

Sigue los pasos a continuación para configurar tus endpoints y comenzar a recibir los eventos card.updated.

1. Accede al Panel del Desarrollador y selecciona la aplicación que recibirá las actualizaciones del Card Updater.

2. En el menú de la izquierda, selecciona Notificaciones > Webhooks.

3. Configura las URLs que recibirán las notificaciones. Recomendamos usar URLs separadas para los modos de prueba y producción:

   • URL modo test: úsala durante el desarrollo, exclusivamente con las credenciales de pruebaCredenciales únicas con las que identificas tu integración en entornos de prueba..
   • URL modo producción: úsala con tu integración ya en producción, configurada con credenciales productivasCredenciales únicas con las que identificas tu integración en entornos de producción..

4. En Eventos recomendados para integraciones con Checkout API, selecciona la opción Card Updater.

5. Por último, haz clic en Guardar configuración. Esto generará una clave secretaClave generada en el Panel del Desarrollador para validar la autenticidad de las notificaciones webhook. para tu aplicación. Ten en cuenta que esta clave no tiene plazo de caducidad y su renovación periódica no es obligatoria, aunque sí recomendada. Para hacerlo, basta con cliquear en el botón Restablecer.

Para garantizar que las notificaciones estén configuradas correctamente, simula su recepción siguiendo el paso a paso a continuación.

1. Después de configurar la URL y el evento, haz clic en Guardar configuración.
2. Luego, haz clic en Simular notificación para verificar que la URL indicada está recibiendo las notificaciones correctamente.
3. En la pantalla de simulación, selecciona la URL que se va a probar.
4. Elige el tipo de evento Card Updater e ingresa el ID de la notificación que se enviará en el cuerpo de la notificación (Data ID).
5. Por último, haz clic en Enviar prueba para verificar la solicitud, la respuesta del servidor y la descripción del evento.

La validación del origen de cada solicitud es fundamental para garantizar la autenticidad de las notificaciones recibidas y prevenir fraudes.

Mercado Pago enviará a tu servidor una notificación similar al ejemplo a continuación para una alerta del tópico Card Updater.

json
Copiar
{
  "id": "evt_123456789",
  "action": "card.updated",
  "type": "automatic-payments",
  "api_version": "v1",
  "application_id": 8339021212080291,
  "user_id": 1197520450,
  "date_created": "2024-01-28T15:00:00-03:00",
  "data": {
    "customer_id": "cust_987654321",
    "new_card_id": 50000102202,
    "old_card_id": 50000006036
  }
}

La clave secreta generada al guardar la configuración es enviada en el header x-signature de cada solicitud, con el siguiente formato:

plain
Copiar
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar la validación, es necesario extraer la clave contenida en el header y compararla con la clave otorgada para tu aplicación en Tus integraciones.

Sigue uno de los enfoques a continuación para validar la autenticidad de la notificación.

<?php
use MercadoPago\Webhook\WebhookSignatureValidator;
use MercadoPago\Exceptions\InvalidWebhookSignatureException;

try {
    WebhookSignatureValidator::validate(
        $_SERVER['HTTP_X_SIGNATURE'],
        $_SERVER['HTTP_X_REQUEST_ID'],
        $_GET['data_id'],
        $secret
    );
    http_response_code(200);
} catch (InvalidWebhookSignatureException $e) {
    http_response_code(401);
}

import { WebhookSignatureValidator, InvalidWebhookSignatureError } from 'mercadopago';

try {
    WebhookSignatureValidator.validate({
        xSignature: req.headers['x-signature'],
        xRequestId: req.headers['x-request-id'],
        dataId:     req.query['data.id'],
        secret,
    });
    res.sendStatus(200);
} catch (err) {
    if (err instanceof InvalidWebhookSignatureError) res.status(401).end();
    else throw err;
}

from mercadopago.webhook import WebhookSignatureValidator, InvalidWebhookSignatureError

try:
    WebhookSignatureValidator.validate(
        request.headers.get("x-signature"),
        request.headers.get("x-request-id"),
        request.args.get("data.id"),
        secret,
    )
    return "", 200
except InvalidWebhookSignatureError:
    return "", 401

import "github.com/mercadopago/sdk-go/pkg/webhook"

err := webhook.ValidateSignature(
    r.Header.Get("x-signature"),
    r.Header.Get("x-request-id"),
    r.URL.Query().Get("data.id"),
    secret,
)
if err != nil {
    w.WriteHeader(http.StatusUnauthorized)
    return
}
w.WriteHeader(http.StatusOK)

using MercadoPago.Error;
using MercadoPago.Webhook;

try {
    WebhookSignatureValidator.Validate(
        xSignature: Request.Headers["x-signature"],
        xRequestId: Request.Headers["x-request-id"],
        dataId:     Request.Query["data.id"],
        secret:     secret);
    return Ok();
} catch (InvalidWebhookSignatureException) {
    return Unauthorized();
}

import com.mercadopago.webhook.WebhookSignatureValidator;
import com.mercadopago.exceptions.MPInvalidWebhookSignatureException;

try {
    WebhookSignatureValidator.validate(
        request.getHeader("x-signature"),
        request.getHeader("x-request-id"),
        request.getParameter("data.id"),
        secret);
    response.setStatus(200);
} catch (MPInvalidWebhookSignatureException e) {
    response.setStatus(401);
}

require 'mercadopago/webhook/validator'

begin
    Mercadopago::Webhook::Validator.validate(
        request.headers['x-signature'],
        request.headers['x-request-id'],
        request.params['data.id'],
        secret
    )
    head :ok
rescue Mercadopago::Webhook::InvalidWebhookSignatureError
    head :unauthorized
end

Cuando recibes una notificación en tu plataforma, Mercado Pago espera una respuesta para validar que la recepción fue correcta. Para eso, devuelve un HTTP STATUS 200 o 201 dentro de los 22 segundos siguientes a la recepción.

Recomendamos que primero respondas con un 200 o 201, y que luego proceses la notificación en el servidor, para evitar notificaciones duplicadas.

Si no se envía esta respuesta, el sistema realizará nuevos intentos de envío cada 15 minutos. Después de los primeros fallos, el intervalo se amplía progresivamente, pero las entregas continúan hasta que la notificación sea confirmada.

Luego de confirmar la recepción, procesa el evento de forma asíncrona:

• Si data.new_card_id está presente en la notificación, actualiza la referencia en tu base de datos y usa ese identificador para todos los cobros futuros de ese cliente. El uso de un card_id antiguo después de la actualización resultará en una alta probabilidad de rechazo.
• Si necesitas los datos completos de la nueva tarjeta, consulta la API enviando una solicitud a /v1/customers/{id}/cardsGET.