Checkout com Assinatura (recorrente)

Crie um Checkout com assinatura recorrente

Crie um Checkout com cartão de crédito para que, após a conclusão da jornada de pagamento, o Asaas crie uma assinatura recorrente.

Utilize chargeTypes = RECURRENT e informe as regras da recorrência em subscription.

Antes de começar

Antes de criar o Checkout:

defina os itens e valores da assinatura;
escolha a periodicidade da recorrência;
defina a data da primeira cobrança;
prepare as URLs de sucesso, cancelamento e expiração;
configure os Webhooks de Checkout, assinaturas e cobranças.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Definir a recorrência"] --> B["Criar o Checkout"]
    B --> C["Armazenar o ID"]
    C --> D["Disponibilizar o link"]
    D --> E["Pagador conclui o Checkout"]
    E --> F["Criar a assinatura"]
    F --> G["Gerar cobranças recorrentes"]
    G --> H["Receber os Webhooks"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F,G validacao
    class H sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Configure a recorrência

Para criar uma assinatura, utilize:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["RECURRENT"]
}

O objeto subscription é obrigatório quando chargeTypes inclui RECURRENT.

Nele, defina as regras da recorrência:

{
  "subscription": {
    "cycle": "MONTHLY",
    "nextDueDate": "2027-01-31 15:02:38",
    "endDate": "2027-12-31 15:02:38"
  }
}

Nesse exemplo:

cycle = MONTHLY define a recorrência mensal;
nextDueDate define a data da primeira cobrança;
endDate delimita o período da assinatura.

2. Crie o Checkout

Envie uma requisição para:

POST /v3/checkouts

Exemplo:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["RECURRENT"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://meusite.com/cancelado",
    "expiredUrl": "https://meusite.com/expirado",
    "successUrl": "https://meusite.com/sucesso"
  },
  "items": [
    {
      "name": "Plano mensal",
      "description": "Assinatura mensal",
      "quantity": 1,
      "value": 100.00
    }
  ],
  "subscription": {
    "cycle": "MONTHLY",
    "nextDueDate": "2027-01-31 15:02:38",
    "endDate": "2027-12-31 15:02:38"
  }
}

Consulte o endpoint Criar novo checkout.

Se sua aplicação já possui os dados do pagador, consulte Como informar os dados do cliente.

3. Disponibilize o Checkout

A criação retorna o ID do Checkout.

Armazene esse identificador e utilize-o para montar a URL que será disponibilizada ao pagador.

Consulte Link do checkout e redirecionamento do cliente.

Resultado esperado

Após o pagador concluir o Checkout, o Asaas cria a assinatura com a recorrência definida em subscription.

As próximas cobranças são geradas de acordo com cycle e possuem ciclo de vida próprio.

4. Acompanhe o Checkout e a assinatura por Webhook

Utilize os Webhooks de acordo com o recurso que deseja acompanhar:

Recurso	O que acompanhar
Checkout	Conclusão, cancelamento ou expiração da jornada
Assinatura	Criação e alterações da recorrência
Cobranças	Geração e processamento de cada cobrança da assinatura

Para confirmar a conclusão do Checkout, acompanhe CHECKOUT_PAID.

Para registrar a assinatura criada, acompanhe SUBSCRIPTION_CREATED.

Depois disso, acompanhe as cobranças recorrentes pelos eventos de cobrança. O objeto da cobrança possui o campo subscription, que identifica a assinatura de origem.

👍
Recomendado
Utilize Webhooks como mecanismo principal de sincronização.
O successUrl controla apenas o redirecionamento do pagador. Não utilize o callback como confirmação de pagamento ou de criação da assinatura.

Erros comuns

Se o Checkout não for criado, verifique:

se RECURRENT foi informado em chargeTypes;
se o objeto subscription foi enviado;
se cycle, nextDueDate e as demais regras da recorrência estão válidas;
se callback e items foram preenchidos corretamente;
se minutesToExpire está entre 10 e 1440 minutos.

Para outros cenários, consulte Erros comuns e boas práticas.

Próximos passos

Updated 3 days ago

Did this page help you?