Assinaturas e cobrança recorrente

Uma assinatura cobra o cliente sozinha a cada ciclo: toda semana, todo mês, a cada trimestre, semestre ou ano. O cliente paga a primeira vez no checkout, e a AbacatePay cobra os ciclos seguintes no cartão de crédito ou no Pix Automático. O vídeo também está em Assinaturas.

​

Quando usar

Use assinatura para mensalidades e planos: cursos e mentorias, SaaS, comunidades, clubes de assinatura.

​

Como funciona uma assinatura

São dois recursos, com IDs e rotas próprias: As regras:

• O produto precisa ter ciclo. Só produto criado com cycle entra numa assinatura. O valor de cada cobrança é o preço do produto vezes a quantidade.
• Um produto por checkout. Mais de um produto no mesmo checkout de assinatura precisa ser liberado na sua conta pelo suporte, e todos os produtos têm que ter o mesmo ciclo.
• Um checkout, um cliente. Depois do pagamento, o checkout de assinatura fica PAID e o link não aceita outro pagamento. Para cada cliente, crie um checkout.
• A data se repete. A próxima cobrança cai na mesma data da contratação, a cada ciclo. Com teste grátis, a contagem começa no fim do teste. O campo nextChargeAt da assinatura traz a data da próxima cobrança.
• Sem parcelamento. A assinatura no cartão é sempre à vista, e não aceita repasse de taxa.
• Liberação. Em produção, a conta precisa ter assinaturas liberadas. No Modo Teste, elas funcionam sem liberação.

​

Formas de pagamento

O campo methods aceita: Com ["CARD", "PIX"], o cliente escolhe no checkout.

​

Ciclos de cobrança

O ciclo é definido no produto e não muda depois que a assinatura começa.

​

Status da assinatura

Enquanto a AbacatePay tenta cobrar um ciclo recusado, a assinatura continua ACTIVE. Quando as tentativas acabam, ela vira CANCELLED.

​

Pagamento recusado e retentativas

No cartão, uma cobrança recusada é tentada de novo conforme a retryPolicy do checkout de assinatura:

• Cada tentativa que falha dispara subscription.payment_failed.
• Com maxRetry: 3 e retryEvery: 2, a AbacatePay tenta no dia do ciclo, 2 dias depois e mais 2 dias depois.
• Quando a última tentativa falha, a assinatura é cancelada com cancelledDueTo: "max_payment_retries_exceeded", e sai o subscription.cancelled.
• Enquanto a assinatura está ativa, o cliente pode trocar o cartão pelo Portal do cliente. Se uma cobrança estiver em retentativa, ela é cobrada no cartão novo na hora.

A retryPolicy só pode ser definida pela API. Checkouts criados pelo dashboard usam o padrão. No Pix Automático, quem debita é o banco do cliente, e a retryPolicy não se aplica: veja cobrança recusada no Pix Automático.

​

Período de teste grátis

O teste grátis deixa o cliente usar antes de pagar. Ele é configurado no produto, com trialDays (de 1 a 90 dias), ao criar o produto pela API. O campo só tem efeito em produto com cycle: num produto avulso, ele é aceito e não faz nada.

• No checkout, o cliente digita o cartão, e o valor cobrado é R$ 0,00. O cartão fica salvo para as próximas cobranças.
• A assinatura nasce ACTIVE, com trialDays e trialEndsAt preenchidos.
• Na contratação sai subscription.trial_started, no lugar de subscription.completed. A primeira cobrança, no fim do teste, chega como subscription.renewed. Se você libera o acesso no completed, libere também no trial_started.
• Se a assinatura for cancelada durante o teste, nada é cobrado.
• O teste grátis é do cartão. Com teste, o checkout não aceita cupom.

​

Cupom em assinatura

O cupom vale só em assinatura cobrada só no cartão (methods: ["CARD"]) e com produto sem teste grátis.

• O desconto vale na primeira cobrança. As renovações cobram o preço cheio.
• Os cupons aceitos vão em coupons na criação do checkout. Depois, não há como aplicar ou trocar o cupom de uma assinatura.
• Com PIX em methods ou com trialDays no produto, o campo de cupom some do checkout e o cupom é recusado. A criação pela API aceita coupons mesmo assim; a regra vale na hora do pagamento.

Veja como criar cupons em Cupons.

​

Trocar o plano da assinatura

Para fazer upgrade ou downgrade, chame Alterar plano com os novos produtos em items.

• A troca fica pendente até a próxima cobrança do ciclo. O ciclo atual não muda, e não há cobrança proporcional.
• Uma troca pendente por vez. Uma chamada nova substitui a troca que ainda não foi aplicada.
• Mesmo ciclo. Os produtos novos precisam ter o mesmo ciclo da assinatura.
• Valor mínimo de R$ 1,00 para o novo plano.
• Só assinatura ativa. Mais de um produto no plano precisa de liberação, como na criação.
• Pix Automático: a troca só é aceita se o valor continuar o mesmo.

O subscription.plan_changed dispara duas vezes: no pedido, com pendingUpdateId, newAmount e status: "PENDING"; e quando a troca é aplicada, já com o novo amount na assinatura.

​

Cobrança por uso

Além do valor fixo do plano, a assinatura pode cobrar o que o cliente consumiu no ciclo, como chamadas de API, SMS ou créditos. É o modelo pay-as-you-go.

1. Crie um produto sem cycle para a unidade de uso, com o preço de cada unidade.
2. A cada consumo, chame Registrar uso com o produto, as unidades e action: "add". Para estornar unidades do mesmo ciclo, use action: "subtract".
3. Na próxima cobrança, a AbacatePay soma o uso ao valor do plano.

O valor da cobrança é o plano, mais as unidades adicionadas, menos as estornadas, cada uma pelo preço que o produto tinha no registro. A cobrança nunca fica abaixo de R$1,00. Por exemplo: plano de R$ 49,90 e 120 unidades de R$0,10 dão uma cobrança de R$ 61,90. O uso só pode ser registrado em assinatura ativa, e o Pix Automático não aceita cobrança por uso.

​

Cancelar uma assinatura

O momento em que o cancelamento vale depende de quem cancela: Nos dois casos, o status vira CANCELLED e o subscription.cancelled sai na hora. No cancelamento pelo portal, o cliente já pagou o ciclo em curso: corte o acesso só depois do fim dele (currentPeriodEnd em Buscar assinatura), e não no recebimento do evento. O subscription.cancelled dispara por estas causas, indicadas em cancelledDueTo: Excluir o checkout de assinatura não cancela a assinatura que ele gerou.

​

Pelo dashboard

1. Em Sua Loja → Produtos, crie o produto. Em Tipo de cobrança, escolha Assinatura e ative os ciclos com o preço de cada um (Mensal, Trimestral, Anual ou Semanal). Cada ciclo ativado vira um produto.
2. Em Sua Loja → Assinaturas, clique em Criar checkout.
3. Escolha o Produto de assinatura, o Cliente (opcional) e os Métodos de pagamento. Se quiser, preencha a URL de finalização e a URL de retorno. Clique em Cadastrar.
4. Na aba Checkouts, abra o checkout em Ver detalhes e copie a URL para mandar ao cliente.
5. Depois do pagamento, a assinatura aparece na aba Assinaturas. Para cancelar, abra a assinatura e clique em Cancelar assinatura no menu de ações.

Se o menu Assinaturas não aparece em produção, a sua conta ainda não tem assinaturas liberadas. Fale com o suporte em ajuda@abacatepay.com. Algumas opções existem só pela API:

​

Pela API

1. Crie o produto com ciclo em Criar produto, com cycle e, se quiser teste grátis, trialDays.
2. Crie o checkout de assinatura em Criar checkout de assinatura:
   POST /v2/subscriptions/create
   {
     "items": [{ "id": "prod_abc123xyz", "quantity": 1 }],
     "customerId": "cust_abc123xyz",
     "externalId": "assinatura-123",
     "completionUrl": "https://seusite.com/sucesso",
     "methods": ["CARD"],
     "retryPolicy": { "maxRetry": 3, "retryEvery": 2 }
   }
   
   Se já existir um checkout com o mesmo externalId, a API devolve esse checkout em vez de criar outro.
3. Mande o cliente para a url da resposta. É lá que ele paga a primeira vez.
4. Espere o webhook subscription.completed (ou subscription.trial_started, com teste grátis) para liberar o acesso. O data.subscription.id é o subs_... da assinatura.
5. Gerencie a assinatura com os endpoints abaixo.

A assinatura aponta o checkout que a originou em checkoutId. Para achar a assinatura de um checkout, use GET /v2/subscriptions/list?checkoutId=bill_....

​

Notificações

Os payloads estão em Eventos de assinatura. Para configurar o recebimento, veja Webhooks.

​

Testar no Modo Teste

• No Modo Teste, as assinaturas funcionam sem liberação. O Pix Automático precisa estar liberado também no Modo Teste.
• No checkout, use os cartões de teste para aprovar ou recusar o primeiro pagamento.
• As cobranças dos próximos ciclos acontecem na data do ciclo, também no Modo Teste. Não há como adiantar uma renovação.

​

Perguntas frequentes