Criando assinatura com cartão de crédito

Ao criar uma assinatura com cartão de crédito, os dados do cartão podem ser enviados juntamente com a requisição para que o Asaas valide o meio de pagamento antes do início da recorrência.

Diferentemente de uma cobrança avulsa, o cartão não é cobrado no momento da criação da assinatura (exceto quando o primeiro vencimento é definido para a data atual). Nesse momento, o Asaas apenas realiza a validação necessária para verificar se o cartão pode ser utilizado na recorrência.

Após a criação da assinatura, as cobranças serão realizadas automaticamente nas datas de vencimento definidas.

POST /v3/subscriptions
Confira a referência completa deste endpoint

Quando utilizar

Este fluxo é recomendado quando sua aplicação deseja:

criar assinaturas recorrentes com cartão de crédito;
automatizar cobranças periódicas sem solicitar novamente os dados do cartão ao cliente;
realizar cobranças mensais, trimestrais, semestrais ou anuais;
oferecer renovação automática de serviços ou assinaturas.

Como funciona

Durante a criação da assinatura:

os dados do cartão são enviados à API;
o cartão é validado;
caso a validação seja aprovada, a assinatura é criada;
as cobranças ocorrerão automaticamente nas datas previstas.

Fluxo simplificado:

Criar assinatura
        ↓
Validar cartão
        ↓
Assinatura criada
        ↓
Gerar cobranças
automaticamente
        ↓
Cobrar cartão
em cada vencimento

📘
Importante
A validação realizada na criação não garante que todas as cobranças futuras serão aprovadas.
Entre a criação da assinatura e os próximos vencimentos, o cartão poderá ser cancelado, expirar, perder limite ou sofrer outras restrições impostas pela operadora.

Exemplo de requisição

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "CREDIT_CARD",
  "nextDueDate": "2026-12-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "description": "Plano Pró",
  "creditCard": {
    "holderName": "Marcelo Henrique Almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2030",
    "ccv": "318"
  },
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  }
}

Primeira cobrança imediata

Caso deseje que a primeira cobrança seja realizada imediatamente, informe o campo nextDueDate com a data atual.

📘
Dica
Quando nextDueDate corresponde ao dia da criação da assinatura, a primeira cobrança será processada imediatamente após a criação.

Possíveis erros na criação

Caso a assinatura não seja criada, a API poderá retornar HTTP 400.

As causas mais comuns são:

cartão recusado pela operadora;
dados do cartão inválidos;
dados do portador inconsistentes;
cliente inexistente;
parâmetros obrigatórios ausentes;
forma de pagamento incompatível com a operação.

Antes de repetir a requisição, recomenda-se identificar o motivo retornado pela API para evitar tentativas duplicadas.

Segurança

🚧
Atenção

Caso sua aplicação capture os dados do cartão, é obrigatório utilizar HTTPS.

Contas que processam cartões sem SSL podem ser bloqueadas para transações de cartão de crédito.

Recomendamos configurar timeout mínimo de 60 segundos para evitar duplicidade causada por novas tentativas da aplicação.

Alterando valor ou vencimento da assinatura

Para alterar o valor ou a data de vencimento de uma assinatura de cartão é necessário possuir a funcionalidade de tokenização habilitada.

A tokenização permite armazenar um identificador seguro do cartão para utilização nas cobranças recorrentes, sem necessidade de solicitar novamente todos os dados ao cliente.

POST /v3/subscriptions/{id}
Veja a referência completa deste endpoint

🚧
Importante

A tokenização já está habilitada no Sandbox.

Em Produção, é necessário solicitar sua habilitação ao gerente de contas.

A aprovação depende da análise de risco da operação.

O token pertence ao cliente que o originou e não pode ser reutilizado em outro cliente.

📘
Saiba mais
Consulte também a documentação sobre Tokenização de Cartões para entender como funciona o armazenamento seguro e o gerenciamento dos tokens utilizados nas cobranças recorrentes.

Ao alterar:

valor;
forma de pagamento;
vencimento;

apenas as cobranças futuras serão afetadas.

Caso também deseje atualizar as cobranças pendentes já criadas, envie:

updatePendingPayments: true

Alterando o cartão da assinatura

Também é possível atualizar apenas o cartão utilizado pela assinatura, sem gerar uma cobrança imediata.

PUT /v3/subscriptions/{id}/creditCard
Veja a referência completa deste endpoint

{
  "creditCard": {
    "holderName": "John Doe",
    "number": "4111111111111111",
    "expiryMonth": "04",
    "expiryYear": "2030",
    "ccv": "123"
  },
  "creditCardHolderInfo": {
    "name": "John Doe",
    "email": "[email protected]",
    "cpfCnpj": "12345678901",
    "postalCode": "12345678",
    "addressNumber": "123",
    "addressComplement": null,
    "phone": null,
    "mobilePhone": null
  },
  "creditCardToken": "a75a1d98-c52d-4a6b-a413-71e00b193c99",
  "remoteIp": "116.213.42.53"
}

Esse procedimento substitui o cartão utilizado nas próximas cobranças da assinatura, sem gerar cobrança imediata.

Upgrade de planos

Caso seja necessário alterar o plano contratado durante a vigência da assinatura:

com tokenização habilitada, basta atualizar a assinatura;
sem tokenização, recomenda-se cancelar a assinatura atual e criar uma nova.

Se houver necessidade de cobrança proporcional pela mudança de plano, recomenda-se:

calcular o valor proporcional;
emitir uma cobrança avulsa;
atualizar ou recriar a assinatura com os novos valores.

Boas práticas

📘
Recomendado

Utilize HTTPS em toda captura de dados do cartão.

Utilize Webhooks para acompanhar os pagamentos das cobranças geradas pela assinatura.

Não considere a validação inicial do cartão como garantia de aprovação das cobranças futuras.

Armazene o identificador da assinatura para futuras alterações.

Utilize tokenização sempre que houver possibilidade de atualização da assinatura.

Impactos operacionais

Assinaturas com cartão de crédito geram novas transações automaticamente ao longo do tempo.

Por esse motivo, integrações que realizam:

conciliação financeira;
emissão de notas fiscais;
envio de notificações;
processamento de Webhooks;

devem considerar que novas cobranças poderão ser criadas e processadas automaticamente sem novas chamadas para criação da assinatura.

Próximos passos

Após implementar assinaturas com cartão de crédito, recomendamos consultar:

Atualizar assinatura existente.
Atualizar cartão de crédito da assinatura.
Listar cobranças de uma assinatura.
Webhook para cobranças.
Tokenização de cartões.
FAQ de Assinaturas.