> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Como ativar assinaturas incompletas > Entenda como funcionam e como são ativadas as assinaturas incompletas. Criou uma assinatura pela API e ela voltou com `status: "incomplete"`? **Está tudo certo.** Isso acontece quando a primeira cobrança ainda precisa ser resolvida: faltou um payment method, a tentativa foi recusada com `allow_incomplete`, ou você escolheu `default_incomplete`. Este guia mostra como levar essa primeira invoice até o pagamento e o que acontece se a janela de recuperação terminar. **`incomplete` é transitório, não um erro.** Ele significa "assinatura registrada, aguardando o primeiro pagamento". Não libere produto nem acesso enquanto ela estiver assim. Quando a invoice for paga, a assinatura muda para `active` e o `subscription.updated` traz a transição. Este guia é para quando **você** cria a assinatura, via `POST /v1/subscriptions` — venda assistida, backoffice, fluxo custom. Se o cliente assina pelo **checkout hospedado**, a session cuida da primeira cobrança por você: comece por [Crie assinaturas para seu SaaS](/payments/create-subscriptions). Como nos outros guias, tudo aqui roda em test mode (`ch_test_...`). ## 1. O resultado do create depende da primeira cobrança Sem trial e com cobrança automática, o create monta a primeira invoice e o payment intent. O `payment_behavior` decide o que a API faz quando essa cobrança não pode ser concluída: | `payment_behavior` | Primeira cobrança | Resposta do create | Depois | | --------------------- | ---------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- | | `allow_incomplete` | Tenta pagar imediatamente e aprova | `200`, subscription `active` | O fluxo segue ativo. | | `allow_incomplete` | Tenta pagar e falha | `200`, subscription `incomplete` | Invoice paga ativa a subscription; após 23h sem pagar, vira `incomplete_expired`. | | `error_if_incomplete` | Tenta pagar imediatamente e aprova | `200`, subscription `active` | O fluxo segue ativo. | | `error_if_incomplete` | Tenta pagar e falha | `402 card_error`, sem subscription pública | Corrija o pagamento e faça uma nova criação. | | `default_incomplete` | Não depende de pagamento imediato | `200`, subscription `incomplete` | Invoice paga ativa a subscription; após 23h sem pagar, vira `incomplete_expired`. | | `payment_behavior` | Resultado quando a primeira cobrança não fecha | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `allow_incomplete` *(padrão)* | Retorna `200` com subscription `incomplete`, invoice `open` e a janela de 23 horas para recuperar. | | `default_incomplete` | Não tenta cobrar no create. Retorna `200` com a mesma estrutura pendente para confirmação posterior. | | `error_if_incomplete` | Retorna `402` com `type: "card_error"`. A subscription, a invoice e o payment intent provisórios não ficam disponíveis na API. | `pending_if_incomplete` é exclusivo de updates e retorna `400` no create. Em trial, `send_invoice` ou invoice de valor zero, não existe pagamento inicial para esse campo bloquear. ## 2. Caminho feliz: cartão salvo e resposta active Passe `default_payment_method` no create. Com o comportamento padrão, a primeira cobrança é tentada **dentro do mesmo request**: ```json POST /v1/subscriptions theme={"theme":"css-variables"} { "customer": "cus_o2CXNCMoZhnvSCez", "default_payment_method": "pm_NSMt9jV45GZUBj2i", "items": [ { "price": "price_FnYoKAJLEPwZ2jTo" } ], "payment_behavior": "allow_incomplete" } ``` Se o pagamento passar, a resposta `200` já traz `status: "active"`. Se for recusado, o mesmo `allow_incomplete` retorna `200` com `status: "incomplete"` para você recuperar a invoice. Troque o campo para `payment_behavior: "error_if_incomplete"`. Pagamento aprovado continua retornando `200` com a subscription `active`; pagamento recusado ou ausência de método retorna `402`, sem deixar uma subscription pública para abandonar depois. Na criação paga imediatamente, `subscription.created` já carrega `status: "active"`. Quando uma subscription que estava `incomplete` é paga depois, `subscription.updated` traz o diff `incomplete → active`: ```javascript theme={"theme":"css-variables"} case 'subscription.updated': { const sub = evt.data.object; const cameFromIncomplete = evt.data.previous_attributes?.status === 'incomplete'; if (cameFromIncomplete && sub.status === 'active') { // Primeira cobrança paga: agora sim, libere o acesso. await activateAccount(sub.id); } break; } ``` ## 3. Sem cartão salvo? Mande a fatura hospedada Criou sem `default_payment_method`? Nada é cobrado sozinho — mas a primeira fatura já existe e tem uma **página de pagamento pronta**. São duas consultas: busque a assinatura (`GET /v1/subscriptions/sub_iQbv6AKoRVPNH8QE`) e pegue no campo `latest_invoice` o ID da primeira fatura; depois busque a fatura (`GET /v1/invoices/inv_gAMqMQJABoeG7jPk`) — a resposta traz **`hosted_invoice_url`**, uma página de pagamento hospedada, pronta para WhatsApp ou e-mail. Quando o cliente pagar por ela, o fluxo é o mesmo da seção anterior: `invoice.paid`, `subscription.updated` e a assinatura `active`. O importante é o prazo: a primeira cobrança tem **23 horas** para fechar. A página hospedada continua funcionando durante essa janela. ## 4. Cartão recusado? Tente pagar a invoice de novo Enquanto a subscription estiver `incomplete`, não é necessário criar outra. Troque ou salve o payment method, pegue a invoice em `latest_invoice` e faça uma nova tentativa explícita: ```bash POST /v1/invoices/inv_gAMqMQJABoeG7jPk/pay theme={"theme":"css-variables"} curl -X POST "https://api.chargefy.io/v1/invoices/inv_gAMqMQJABoeG7jPk/pay" \ -H "Authorization: Bearer {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "pm_mgoYChXGHeKoYD3b" }' ``` Esse endpoint cria uma nova tentativa para a invoice aberta. Quando ela passa, chegam `payment.intent.succeeded`, `invoice.paid` e `subscription.updated`; a subscription vira `active`. O contrato completo está em [`POST /v1/invoices/{id}/pay`](/api-reference/invoices/pay). ## 5. Reaja ao estado atual de cada evento A criação e a ativação disparam uma sequência previsível de webhooks: | Momento | Evento | O que carrega | | ---------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Create pago imediatamente | `subscription.created` | A assinatura completa já com `status: "active"`. | | Create mantido para recuperação | `subscription.created` | A assinatura completa com `status: "incomplete"`. | | Primeira fatura criada | `invoice.created` | A invoice `subscription_create`, aberta ou já paga conforme o resultado. | | Tentativa criada | `payment.intent.created` | O payment intent da primeira cobrança. | | Cobrança recusada com `allow_incomplete` | `invoice.payment.failed` (e `payment.intent.updated` com `requires_payment_method`) | A subscription continua `incomplete`; a fatura aceita nova tentativa no mesmo intent. | | Invoice recuperada e paga | `payment.intent.succeeded`, `invoice.paid` e `subscription.updated` | A subscription muda de `incomplete` para `active`. | Com `error_if_incomplete`, uma falha retorna `402` e não emite eventos dos recursos provisórios, porque eles não passaram a existir publicamente. Se o seu receiver ainda não existe, o [guia de primeiro pagamento](/accept-your-first-payment) monta um em dez linhas. ## Quando a primeira cobrança não fecha Se a primeira cobrança **não for paga em até 23 horas**, a Chargefy expira a assinatura — em cadeia: `incomplete → incomplete_expired`, com `subscription.updated` trazendo o diff. Esse estado é **terminal**. A fatura `subscription_create` que estava `open` passa para `void` e dispara `invoice.voided`. O `payment_intent` em aberto vira `canceled` e dispara `payment.intent.canceled`. Duas pegadinhas aqui: * **Falha não é atraso.** Com `allow_incomplete`, cartão recusado na primeira cobrança **não** leva a assinatura para `past_due`: a fatura continua `open` e a assinatura continua `incomplete` até ser paga ou a janela vencer. Com `error_if_incomplete`, a mesma recusa encerra o create com `402` e não cria a assinatura pública. * **`incomplete_expired` não volta.** Para o cliente assinar de novo, crie uma assinatura nova. ## incomplete, past\_due e unpaid não são a mesma coisa É comum confundir o estado da **primeira** cobrança com o das **renovações**. A régua é direta: | Cenário | Status resultante | | -------------------------------------- | -------------------- | | Primeira cobrança ainda não fechou | `incomplete` | | Primeira cobrança não fechou em 23h | `incomplete_expired` | | Cobrança de **renovação** falhou | `past_due` | | Retry/política de recuperação esgotada | `unpaid` | `past_due` e `unpaid` pertencem ao mundo das renovações — com retentativas e régua de cobrança automáticas por conta da Chargefy. Esse lado da história está em [Crie assinaturas para seu SaaS](/payments/create-subscriptions#5-cartão-falhou-a-régua-de-cobrança-já-vem-pronta). O mapa completo de estados: | Acontecimento | Transição | | -------------------------------------------------- | ---------------------------------------- | | Criação sem trial, com pagamento imediato aprovado | Início
→ `active` | | Criação sem trial, com pagamento pendente | Início
→ `incomplete` | | Criação com trial | Início
→ `trialing` | | Primeira cobrança paga | `incomplete`
→ `active` | | 23 horas sem pagamento | `incomplete`
→ `incomplete_expired` | | Trial termina e a cobrança é aprovada | `trialing`
→ `active` | | Renovação falha | `active`
→ `past_due` | | Cobrança recuperada | `past_due`
→ `active` | | Retentativas esgotadas | `past_due`
→ `unpaid` | | Fatura aberta paga | `unpaid`
→ `active` | ## E o trial? Assinatura criada com `trial_period_days` ou `trial_end` **não passa por `incomplete`**: ela nasce `trialing` e a primeira cobrança só acontece no fim do trial. Sem cartão salvo, a resposta do create traz `pending_setup_intent` para você coletar o cartão durante o período gratuito, e `trial_settings.end_behavior` decide o que acontece se ele terminar sem método de pagamento. Detalhes em [Trial](/payments/subscription-trial). ## Próximos passos O guia completo da recorrência: trial, renovações, régua de cobrança, pró-rata e portal do cliente. O contrato do POST /v1/subscriptions, incluindo trial e importação. A cobrança que confirma a primeira fatura e leva a assinatura a active. Schema público completo, todos os status e os campos retornados.