O Card Updater é uma funcionalidade do Mercado Pago que recupera e atualiza automaticamente os dados de cartões salvos, garantindo a continuidade das cobranças recorrentes sem CVV quando um cartão vence, é substituído ou sofre qualquer alteração no seu ciclo de vida.

Sempre que ocorre uma alteração no ciclo de vida de um cartão — vencimento, perda, roubo, atualização de categoria ou retificação de dados — o Mercado Pago realiza a sincronização direta com as bandeiras e emissores. Uma vez atualizada a base, dispara uma notificação Webhook para sua aplicação para que você possa atualizar seus registros de forma assíncrona e automática.

    sequenceDiagram
        participant E as Emissor / Bandeira
        participant MP as Mercado Pago
        participant App as Sua aplicação
        E->>MP: Alteração no ciclo de vida do cartão
        MP->>MP: Sincroniza credenciais na base de dados
        MP->>App: Webhook: card.updated
        App-->>MP: HTTP 200 / 201
        App->>MP: GET /v1/customers/{id}/cards (opcional)
        MP-->>App: Dados do novo cartão
        App->>App: Atualiza card_id para próximas cobranças
    

A implementação do tópico de notificação Card Updater mitiga pagamentos rejeitados por dados obsoletos, corrigindo erros como:

• Erros de entrada de dados: Bad_Filled_Card_Number, Bad_Filled_Card_Date, Bad_Filled_Security_Code.
• Restrições de status do cartão: Card_Disabled, Blacklist, Call_For_Authorized, Other_Reason.
• Substituição de credenciais: transições de cartões vencidos ou migração de categoria (por exemplo, de Gold para Black).

Ao processar o evento card.updated, sua aplicação garante a continuidade da cobrança sem intervenção manual do cliente final.

Dependendo da alteração realizada pela bandeira ou pelo emissor, o identificador do cartão (card_id) pode sofrer dois tipos de modificações:

• Mudança de card_id: ocorre quando um novo número de cartão (PAN) é gerado. A notificação Webhook disparada pelo Mercado Pago enviará o campo new_card_id, que substitui o identificador anterior.
• Atualização silenciosa: para correções menores, o card_id permanece igual e a atualização ocorre de forma transparente na base do Mercado Pago.

Além disso, todos os cartões gerados pelo Card Updater são adicionados automaticamente ao respectivo Cliente salvo no Mercado Pago, com um limite de até 20 cartões. Para validar os detalhes do novo cartão ou listar todos os cartões ativos de um cliente, utilize o endpoint /v1/customers/{id}/cardsGET.

Mantenha sempre atualizada a referência do card_id na sua base de dados após receber cada notificação do tipo card.updated. Nos casos de mudança de ID, garanta que todas as próximas cobranças utilizem o new_card_id. O uso de um card_id antigo após a atualização resultará em alta probabilidade de rejeição nos pagamentos.

Siga os passos abaixo para configurar seus endpoints e começar a receber os eventos card.updated.

1. Acesse o Painel do Desenvolvedor e selecione a aplicação que receberá as atualizações do Card Updater.

2. No menu da esquerda, selecione Notificações > Webhooks.

3. Configure as URLs que receberão as notificações. Recomendamos usar URLs separadas para os modos de teste e produção:

   • URL modo teste: use durante o desenvolvimento, exclusivamente com as credenciais de testeCredenciais únicas com as quais você identifica sua integração em ambientes de teste..
   • URL modo produção: use com sua integração já em produção, configurada com credenciais produtivasCredenciais únicas com as quais você identifica sua integração em ambientes de produção..

4. Em Eventos recomendados para integrações com Checkout API, selecione a opção Card Updater.

5. Por fim, clique em Salvar configuração. Isso gerará uma chave secretaChave gerada no Painel do Desenvolvedor para validar a autenticidade das notificações webhook. para sua aplicação. Esta chave não tem prazo de validade e a renovação periódica não é obrigatória, embora seja recomendada. Para fazê-lo, basta clicar no botão Redefinir.

Para garantir que as notificações estejam configuradas corretamente, simule o recebimento seguindo o passo a passo abaixo.

1. Após configurar a URL e o evento, clique em Salvar configuração.
2. Em seguida, clique em Simular notificação para verificar se a URL indicada está recebendo as notificações corretamente.
3. Na tela de simulação, selecione a URL a ser testada.
4. Escolha o tipo de evento Card Updater e insira o ID da notificação que será enviado no corpo da notificação (Data ID).
5. Por fim, clique em Enviar teste para verificar a solicitação, a resposta do servidor e a descrição do evento.

A validação da origem de cada solicitação é fundamental para garantir a autenticidade das notificações recebidas e prevenir fraudes.

O Mercado Pago enviará ao seu servidor uma notificação similar ao exemplo abaixo para um alerta do 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
  }
}

A chave secreta gerada ao salvar a configuração é enviada no header x-signature de cada solicitação, com o seguinte formato:

plain
Copiar
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar a validação, é necessário extrair a chave contida no header e compará-la com a chave fornecida para a sua aplicação em Suas integrações. Siga uma das abordagens abaixo para validar a autenticidade da notificação.

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

Quando você recebe uma notificação na sua plataforma, o Mercado Pago aguarda uma resposta para validar que o recebimento foi correto. Para isso, retorne um HTTP STATUS 200 ou 201 dentro de 22 segundos após o recebimento.

Recomendamos que você primeiro responda com um 200 ou 201, e depois processe a notificação no servidor, para evitar notificações duplicadas.

Se essa resposta não for enviada, o sistema realizará novas tentativas de envio a cada 15 minutos. Após as primeiras falhas, o intervalo é progressivamente ampliado, mas as entregas continuam até que a notificação seja confirmada.

Após confirmar o recebimento, processe o evento de forma assíncrona:

• Se data.new_card_id estiver presente na notificação, atualize a referência na sua base de dados e use esse identificador para todas as cobranças futuras desse cliente. O uso de um card_id antigo após a atualização resultará em alta probabilidade de rejeição.
• Se precisar dos dados completos do novo cartão, consulte a API enviando uma solicitação para /v1/customers/{id}/cardsGET.