Guia de Assinaturas

Confira o guia de assinaturas para mais informações.

Endpoint responsável por atualizar o cartão de crédito utilizado por uma assinatura existente sem realizar uma cobrança imediata.

Além de atualizar o cartão associado à assinatura, o Asaas também atualiza automaticamente todas as cobranças pendentes vinculadas à recorrência, que passarão a utilizar o novo cartão nas próximas tentativas de cobrança.

Esse recurso é indicado para situações em que o cartão anterior expirou, foi cancelado, foi substituído pelo cliente ou precisa ser alterado sem recriar a assinatura.

Quando utilizar

Utilize este endpoint quando sua integração precisar:

• atualizar o cartão de crédito utilizado em uma assinatura recorrente;
• substituir um cartão expirado, cancelado ou bloqueado;
• corrigir dados do cartão antes do próximo vencimento;
• alterar o cartão mantendo a mesma assinatura ativa;
• atualizar também as cobranças pendentes para que utilizem o novo cartão.

Caso seja necessário alterar informações como valor, vencimento, periodicidade ou forma de pagamento da assinatura, utilize o endpoint Atualizar assinatura existente.

Parâmetros importantes

Além do identificador da assinatura, alguns parâmetros possuem impacto direto no comportamento da atualização:

• creditCard — dados completos do novo cartão.
• creditCardHolderInfo — informações do titular do cartão.
• creditCardToken — token previamente gerado. Quando informado, substitui o envio dos dados completos do cartão.
• remoteIp — endereço IP real do dispositivo do pagador. Não utilize o IP do seu servidor.

Como funciona

Após receber uma requisição válida, o Asaas valida o novo cartão informado e o associa à assinatura.

Fluxo simplificado:

Assinatura existente
        ↓
Atualizar cartão
        ↓
Novo cartão validado
        ↓
Assinatura atualizada
        ↓
Cobranças pendentes passam a utilizar o novo cartão

Nenhuma cobrança é realizada durante essa atualização.

Comportamentos importantes

Ao atualizar o cartão da assinatura:

• nenhuma cobrança é executada no momento da atualização;
• o novo cartão passa a ser utilizado nas próximas cobranças da recorrência;
• todas as cobranças pendentes vinculadas à assinatura também passam a utilizar o novo cartão;
• cobranças já liquidadas permanecem inalteradas;
• a atualização não modifica valor, periodicidade ou vencimento da assinatura.

A validação do cartão durante essa operação não garante que cobranças futuras serão aprovadas, pois o cartão poderá sofrer alterações posteriormente, como expiração, cancelamento ou indisponibilidade de limite.

Boas práticas

Erros comuns

400 Bad Request

Pode ocorrer quando os dados do cartão são inválidos ou inconsistentes.

401 Unauthorized

Ocorre quando a API Key é inválida ou pertence ao ambiente incorreto.

404 Not Found

Ocorre quando a assinatura informada não existe ou não pertence à conta autenticada.

Impactos operacionais

A atualização do cartão afeta tanto a assinatura quanto todas as cobranças pendentes vinculadas a ela.

Isso evita que cobranças futuras continuem tentando utilizar um cartão expirado ou inválido, reduzindo recusas e aumentando a continuidade da recorrência.

A operação não gera uma nova cobrança nem altera o histórico financeiro da assinatura.

Conteúdos relacionados

• Criar assinatura
• Criar assinatura com cartão de crédito
• Atualizar assinatura
• Recuperar uma única assinatura
• Webhooks de cobrança