Guia de Assinaturas

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

Endpoint responsável por criar uma nova assinatura recorrente no Asaas.

Uma assinatura funciona como um agendador de cobranças, criando automaticamente novas cobranças conforme a periodicidade configurada. Esse recurso é indicado para mensalidades, planos, assinaturas SaaS, contratos de prestação de serviços e qualquer outro cenário em que exista recorrência de pagamentos.

Após a criação da assinatura, as cobranças serão geradas automaticamente até que a assinatura seja removida ou atinja o limite definido.

Quando utilizar

Utilize este endpoint quando sua aplicação precisar:

• criar cobranças recorrentes automaticamente;
• cobrar clientes em intervalos periódicos;
• gerenciar assinaturas de produtos ou serviços;
• automatizar o faturamento recorrente;
• utilizar boleto, Pix ou cartão de crédito como forma de pagamento.

Principais parâmetros da requisição

Alguns campos possuem papel fundamental no comportamento da assinatura:

• customer — identificador do cliente que será cobrado.
• billingType — define a forma de pagamento utilizada nas cobranças recorrentes.
• value — valor de cada cobrança da assinatura.
• nextDueDate — define a data de vencimento da primeira cobrança.
• cycle — determina a periodicidade das cobranças.
• endDate — data limite para geração de novas cobranças.
• maxPayments — quantidade máxima de cobranças que poderão ser criadas.
• externalReference — identificador da assinatura no sistema de origem.
• split — configura a divisão automática dos valores, quando aplicável.
• callback — configura o redirecionamento após o pagamento, quando suportado pelo fluxo.

Regras de negócio importantes

Ao criar uma assinatura:

• a primeira cobrança será criada utilizando a data informada em nextDueDate;
• as próximas cobranças serão geradas automaticamente conforme a periodicidade informada em cycle;
• o valor de cada cobrança será definido pelo parâmetro value;
• a assinatura permanece ativa até ser removida ou atingir endDate ou maxPayments, quando informados;
• cada cobrança criada possui ciclo de vida próprio e poderá ser acompanhada individualmente.

Caso utilize cartão de crédito, a validação do cartão ocorre durante a criação da assinatura, porém a cobrança será realizada apenas na data de vencimento de cada cobrança recorrente.

Período de gratuidade (Trial)

Caso sua aplicação trabalhe com um período de trial (por exemplo, 7 dias gratuitos), basta informar em nextDueDate a data em que a primeira cobrança deverá ocorrer.

Exemplo:

• criação da assinatura hoje;
• nextDueDate configurado para daqui a 7 dias;
• primeira cobrança será gerada com vencimento nessa data.

Se o cartão de crédito for informado durante a criação da assinatura, ele será validado e armazenado para utilização automática no primeiro vencimento.

Comportamento ao informar o cartão posteriormente

Caso a assinatura seja criada sem os dados do cartão de crédito e o pagador informe posteriormente um cartão válido, o comportamento será diferente.

Nesse cenário, o valor da cobrança pendente será processado imediatamente após o cadastro do cartão, independentemente da data originalmente informada em nextDueDate.

Esse comportamento existe para permitir a regularização imediata da cobrança que aguardava uma forma de pagamento válida.

Como funciona o fluxo

Em uma integração típica, a criação da assinatura segue a seguinte jornada:

Criar assinatura
        ↓
Assinatura criada
        ↓
Gerar cobranças automaticamente
        ↓
Cliente realiza o pagamento
        ↓
Webhook informa o resultado
        ↓
Aplicação atualiza o status

As cobranças são geradas automaticamente pela assinatura e cada uma possui seu próprio ciclo de vida financeiro.

Boas práticas

Impactos operacionais

A criação da assinatura não representa o recebimento do pagamento.

Cada cobrança será criada automaticamente conforme a periodicidade configurada em cycle e deverá ser acompanhada individualmente através da API ou dos Webhooks.

Alterações posteriores na assinatura poderão afetar apenas cobranças futuras ou, quando suportado pela operação, também cobranças pendentes.

Próximos passos

Após criar uma assinatura, normalmente a integração segue para:

• Recuperar uma assinatura.
• Atualizar uma assinatura.
• Listar cobranças de uma assinatura.
• Configurar Webhooks.
• Gerenciar cobranças recorrentes.