Crie uma assinatura com cartão de crédito

Crie uma assinatura para que o Asaas gere cobranças recorrentes e processe o cartão nas datas de vencimento.

Na criação, o cartão é validado. A primeira cobrança ocorre em nextDueDate, salvo quando essa data corresponde ao dia atual.

Quando utilizar

Utilize este fluxo quando sua integração precisar:

• realizar cobranças recorrentes no cartão de crédito;
• reutilizar o mesmo cartão nos próximos ciclos;
• validar o cartão na contratação;
• automatizar a cobrança sem solicitar os dados do cartão a cada vencimento.

Antes de começar

Antes de criar a assinatura:

• cadastre o cliente e armazene seu ID;
• defina valor, periodicidade e primeiro vencimento;
• configure os Webhooks de assinaturas e cobranças;
• utilize HTTPS caso sua aplicação capture os dados do cartão.

Se já possuir um creditCardToken válido para o cliente, prefira utilizá-lo no lugar dos dados completos do cartão.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Cadastrar ou localizar o cliente"] --> B["Informar o cartão"]
    B --> C["Criar a assinatura"]
    C --> D["Validar o cartão"]
    D --> E["Gerar as cobranças"]
    E --> F["Processar cada vencimento"]
    F --> G["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 validacao
    class G sucesso

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

A validação realizada na criação não garante a aprovação das cobranças futuras. O cartão pode expirar, ser bloqueado, cancelado ou ficar sem limite antes de um próximo vencimento.

1. Crie a assinatura

Utilize:

POST /v3/subscriptions

Exemplo com os dados do cartão:

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "CREDIT_CARD",
  "nextDueDate": "2027-01-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"
  },
  "remoteIp": "203.0.113.10"
}

Informe em remoteIp o IP do dispositivo utilizado pelo pagador. Não envie o IP do seu servidor.

Consulte o endpoint Criar assinatura com cartão de crédito.

Utilizando um cartão tokenizado

Se já possuir um token válido para o cliente, utilize creditCardToken no lugar de creditCard e creditCardHolderInfo:

{
  "customer": "cus_0T1mdomVMi39",
  "billingType": "CREDIT_CARD",
  "nextDueDate": "2027-01-15",
  "value": 19.90,
  "cycle": "MONTHLY",
  "creditCardToken": "a75a1d98-c52d-4a6b-a413-71e00b193c99",
  "remoteIp": "203.0.113.10"
}

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

Consulte a Tokenização de cartão de crédito.

Resultado esperado

A API retorna a assinatura criada e seu id.

Armazene esse identificador para acompanhar, atualizar ou remover a assinatura.

Se nextDueDate corresponder à data atual, a primeira cobrança poderá ser processada imediatamente.

2. Acompanhe a assinatura e os pagamentos

Prefira Webhooks para manter sua aplicação sincronizada com o Asaas.

Utilize os Eventos para assinaturas para acompanhar alterações no ciclo de vida da assinatura.

Utilize os Eventos para cobranças para acompanhar cada cobrança gerada e seu processamento no cartão.

3. Atualize os dados da assinatura

Para alterar informações como valor, vencimento ou periodicidade, utilize:

PUT /v3/subscriptions/{id}

Por padrão, as alterações afetam as cobranças que ainda serão geradas.

Quando precisar aplicar as alterações suportadas também às cobranças pendentes já existentes, informe:

{
  "updatePendingPayments": true
}

Para alterações de valor ou vencimento em assinaturas com cartão de crédito, a funcionalidade de tokenização deve estar habilitada.

A tokenização está disponível no Sandbox. Em Produção, sua habilitação deve ser solicitada ao gerente de contas e está sujeita à análise da operação.

Consulte o endpoint Atualizar assinatura existente.

4. Atualize o cartão da assinatura

Para substituir apenas o cartão utilizado na recorrência, sem realizar uma cobrança imediata, utilize:

PUT /v3/subscriptions/{id}/creditCard

Se possuir um token do novo cartão:

{
  "creditCardToken": "a75a1d98-c52d-4a6b-a413-71e00b193c99",
  "remoteIp": "203.0.113.10"
}

Também é possível enviar creditCard e creditCardHolderInfo no lugar do token.

A atualização:

• não realiza cobrança imediata;
• altera o cartão da assinatura;
• atualiza também as cobranças pendentes vinculadas à assinatura para utilizar o novo cartão.

Consulte o endpoint Atualizar cartão de crédito da assinatura.

Erros comuns

Se a assinatura não for criada, verifique:

• se o cartão foi recusado;
• se os dados do cartão e do titular são válidos;
• se o cliente pertence à conta;
• se os campos obrigatórios foram enviados;
• se remoteIp corresponde ao dispositivo do pagador.

A criação pode retornar HTTP 400 quando os dados enviados ou o processamento do cartão impedirem a operação.

Não repita automaticamente uma requisição sem avaliar o retorno anterior, principalmente em cenários de timeout.

Teste no Sandbox

Utilize os cartões próprios de teste para validar aprovações, recusas, tokenização e Webhooks antes de utilizar o fluxo em Produção.

Consulte Testando pagamento com cartão de crédito.

Próximos passos

• Tokenize cartões para reutilização
• Atualize o cartão de crédito da assinatura
• Acompanhe os eventos de assinaturas
• Acompanhe os eventos de cobranças
• Teste pagamentos com cartão de crédito
• Consulte o FAQ de Assinaturas