Card Updater is a Mercado Pago feature that automatically retrieves and updates stored card data, ensuring the continuity of recurring payments without CVV when a card expires, is replaced, or undergoes any change in its lifecycle.

Whenever a change occurs in a card's lifecycle — expiration, loss, theft, category upgrade, or data correction — Mercado Pago performs direct synchronization with card networks and issuers. Once the database is updated, it triggers a Webhook notification to your application so you can update your records asynchronously and automatically.

    sequenceDiagram
        participant E as Issuer / Card Network
        participant MP as Mercado Pago
        participant App as Your application
        E->>MP: Card lifecycle change
        MP->>MP: Syncs credentials in the database
        MP->>App: Webhook: card.updated
        App-->>MP: HTTP 200 / 201
        App->>MP: GET /v1/customers/{id}/cards (optional)
        MP-->>App: New card data
        App->>App: Updates card_id for upcoming charges
    

The Card Updater notification topic mitigates rejected payments caused by outdated data, resolving errors such as:

• Data entry errors: Bad_Filled_Card_Number, Bad_Filled_Card_Date, Bad_Filled_Security_Code.
• Card status restrictions: Card_Disabled, Blacklist, Call_For_Authorized, Other_Reason.
• Credential replacement: transitions from expired cards or category migration (for example, from Gold to Black).

By processing the card.updated event, your application ensures billing continuity without manual intervention from the end customer.

Depending on the change made by the card network or issuer, the card identifier (card_id) can undergo two types of modifications:

• card_id change: occurs when a new card number (PAN) is generated. The Webhook notification sent by Mercado Pago will include the new_card_id field, which replaces the previous identifier.
• Silent update: for minor corrections, the card_id remains the same and the update occurs transparently in Mercado Pago's database.

Additionally, all cards generated by Card Updater are automatically added to the respective Customer stored in Mercado Pago, with a limit of up to 20 cards. To validate the details of the new card or list all active cards for a customer, use the /v1/customers/{id}/cardsGET endpoint.

Always keep the card_id reference in your database updated after receiving each card.updated notification. When an ID change occurs, ensure that all upcoming charges use the new_card_id. Using an outdated card_id after the update will result in a high probability of payment rejection.

Follow the steps below to configure your endpoints and start receiving card.updated events.

1. Access the Developer Panel and select the application that will receive Card Updater updates.

2. In the left menu, select Notifications > Webhooks.

3. Configure the URLs that will receive notifications. We recommend using separate URLs for test and production environments:

   • Test URL: use during development, exclusively with test credentialsUnique credentials that identify your integration in test environments..
   • Production URL: use with your integration already in production, configured with production credentialsUnique credentials that identify your integration in production environments..

4. Under Recommended events for Checkout API integrations, select the Card Updater option.

5. Finally, click Save configuration. This will generate a secret keyKey generated in the Developer Panel to validate the authenticity of webhook notifications. for your application. Note that this key has no expiration date and periodic renewal is not mandatory, though recommended. To do so, click the Reset button.

To ensure notifications are configured correctly, simulate receiving them by following the steps below.

1. After configuring the URL and event, click Save configuration.
2. Then click Simulate notification to check if the indicated URL is receiving notifications correctly.
3. On the simulation screen, select the URL to test.
4. Choose the Card Updater event type and enter the notification ID to be sent in the notification body (Data ID).
5. Finally, click Send test to verify the request, the server response, and the event description.

Validating the origin of each request is essential to ensure the authenticity of received notifications and prevent fraud.

Mercado Pago will send your server a notification similar to the example below for a Card Updater topic alert.

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

The secret key generated when saving the configuration is sent in the x-signature header of each request, with the following format:

plain
Copiar
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

To confirm the validation, extract the key from the header and compare it with the key provided for your application in Your integrations. To confirm the validation, it is necessary to extract the key from the header and compare it with the key provided for your application in Your integrations.

Follow one of the approaches below to validate the authenticity of the notification.

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

When you receive a notification on your platform, Mercado Pago expects a response to validate that the receipt was correct. To do so, return an HTTP STATUS 200 or 201 within 22 seconds of receipt.

We recommend that you first respond with a 200 or 201, and then process the notification on the server, to avoid duplicate notifications.

If this response is not sent, the system will make new delivery attempts every 15 minutes. After the first failures, the interval progressively increases, but deliveries continue until the notification is confirmed.

After confirming receipt, process the event asynchronously:

• If data.new_card_id is present in the notification, update the reference in your database and use that identifier for all future charges for that customer. Using an outdated card_id after the update will result in a high probability of rejection.
• If you need the full details of the new card, query the API by sending a request to /v1/customers/{id}/cardsGET.