Docs Pagar.me v5 (legado)

Card Updater

Atualização automática de cartões expirados na Pagar.me v5.

Documentação legada do Pagar.me v5

Esta página descreve um conceito da Pagar.me v5 (versão clássica). Para projetos novos, explore o API Catalog.

O Card Updater é uma funcionalidade que permite a atualização de cartões de crédito expirados que foram reemitidos — eliminando a necessidade de renovação do cartão por parte do consumidor final.

Essa funcionalidade é especialmente valiosa para clientes com assinatura, pois reduz significativamente a taxa de churn involuntário (quando o consumidor não deseja cancelar o serviço, mas o cartão expira).

Bandeiras suportadas

Apenas algumas bandeiras disponibilizam cartões para essa funcionalidade:

  • ✅ Mastercard
  • ✅ Visa
  • ✅ Hipercard

Modos de operação

Pensando na melhor experiência, a funcionalidade foi desenvolvida de duas formas distintas: manual ou automática.

Renovação Manual

Permite que o cliente, ao receber como resposta que o cartão está vencido ou inválido, envie uma requisição de renovação, chamando a API e verificando se esse cartão foi reemitido.

Caso o cartão tenha sido reemitido, a API cria um novo cartão (mantendo o antigo, para garantir rastreabilidade das transações realizadas com ele) na Wallet do lojista.

Essa solução é interessante para clientes que utilizam funcionalidades como "one click buy": a loja pode renovar manualmente um cartão prestes a vencer e avisar ao consumidor que o cartão foi atualizado.

Segurança

Por questões de segurança, só é possível utilizar essa funcionalidade caso o cartão já esteja gravado na wallet.

Renovação Automática

Pensada para clientes com modelo de negócios de recorrência. Se um cartão atrelado a assinaturas for identificado como expirado, a API envia automaticamente uma requisição de renovação. Em caso de renovação bem-sucedida:

  1. O cartão novo é gravado na wallet (mantendo o antigo para rastreabilidade)
  2. É atualizado na assinatura
  3. A cobrança referente à assinatura é retentada automaticamente com o novo cartão

Funciona para todos os tipos de assinatura — pré, pós-paga e "exact day".

Permite que o lojista não perca transações por churn involuntário e diminua a inadimplência.

Use os dois juntos

É possível utilizar as duas formas separadamente ou de forma simultânea — combine como se encaixar melhor no seu modelo de negócios.

Migração para a API Unificada

Na Stone, Card Updater funciona transparentemente quando você usa wallet_id em uma cobrança recorrente:

{
  "amount": 4990,
  "currency": "BRL",
  "payment_method": "credit_card",
  "card": { "wallet_id": "wlt_aN9k..." },
  "recurring": { "interval": "month", "frequency": 1 }
}

Não há chamada extra — se o cartão foi reemitido, a Stone usa a versão atualizada automaticamente. Veja Stone Online · Recorrência.

Jornada: Cobrar de forma recorrente
Etapa 7 de 7

Etapa anteriorRecorrência com Split