Como ativar 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. 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

Crie a assinatura com um método de pagamento padrão

Passe default_payment_method no create. Com o comportamento padrão, a primeira cobrança é tentada dentro do mesmo request:

POST /v1/subscriptions

{
"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.

Use error_if_incomplete quando o create precisar ser tudo ou nada

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.

Sincronize o acesso pelos webhooks

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:

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:

POST /v1/invoices/inv_gAMqMQJABoeG7jPk/pay

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.

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 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:

A assinatura vira incomplete_expired

incomplete → incomplete_expired, com subscription.updated trazendo o diff. Esse estado é terminal.

A primeira fatura é anulada

A fatura subscription_create que estava open passa para void e dispara invoice.voided.

A cobrança pendente é cancelada

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. 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.

Próximos passos

Crie assinaturas para seu SaaS

O guia completo da recorrência: trial, renovações, régua de cobrança, pró-rata e portal do cliente.

Criar assinatura (API)

O contrato do POST /v1/subscriptions, incluindo trial e importação.

Payment Intents

A cobrança que confirma a primeira fatura e leva a assinatura a active.

Objeto subscription

Schema público completo, todos os status e os campos retornados.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Como ativar assinaturas incompletas

1. O resultado do create depende da primeira cobrança

2. Caminho feliz: cartão salvo e resposta active

3. Sem cartão salvo? Mande a fatura hospedada

4. Cartão recusado? Tente pagar a invoice de novo

5. Reaja ao estado atual de cada evento

Quando a primeira cobrança não fecha

incomplete, past_due e unpaid não são a mesma coisa

E o trial?

Próximos passos

Crie assinaturas para seu SaaS

Criar assinatura (API)

Payment Intents

Objeto subscription

​1. O resultado do create depende da primeira cobrança

​2. Caminho feliz: cartão salvo e resposta active

​3. Sem cartão salvo? Mande a fatura hospedada

​4. Cartão recusado? Tente pagar a invoice de novo

​5. Reaja ao estado atual de cada evento

​Quando a primeira cobrança não fecha

​incomplete, past_due e unpaid não são a mesma coisa

​E o trial?

​Próximos passos

Crie assinaturas para seu SaaS

Criar assinatura (API)

Payment Intents

Objeto subscription

1. O resultado do create depende da primeira cobrança

2. Caminho feliz: cartão salvo e resposta active

3. Sem cartão salvo? Mande a fatura hospedada

4. Cartão recusado? Tente pagar a invoice de novo

5. Reaja ao estado atual de cada evento

Quando a primeira cobrança não fecha

incomplete, past_due e unpaid não são a mesma coisa

E o trial?

Próximos passos