Referência
Status de assinatura
Estados normalizados que uma assinatura pode assumir na Allya Payments.
A Allya normaliza os status de assinatura dos três gateways para um conjunto pequeno.
| Status | Tipicamente vindo de | Significado |
|---|---|---|
trialing | trial configurado via trialDays > 0 (Abacate Pay) ou trial_period_days do plano (Pagar.me) | Período gratuito antes da primeira cobrança real. Nenhuma cobrança gerada. Asaas não entra neste status: o gateway não suporta trial em checkout hospedado; veja Período de trial. |
active | gateway confirmou primeiro pagamento ou trial expirou com sucesso | Em dia. Próxima cobrança ocorre em nextBillingAt. |
past_due | falha na cobrança recorrente | Última tentativa de débito falhou. O gateway pode estar retentando automaticamente (dunning). |
canceled | cancelamento imediato ou fim do período após cancelAtPeriodEnd=true | Encerrada. Nenhuma cobrança futura. |
Campos relacionados
trialEndsAt: data ISO em que o trial acaba.nullquandotrialDays = 0.nextBillingAt: próxima cobrança prevista. Pode ficarnulllogo após a criação até o gateway confirmar o cartão no checkout hospedado.cancelAtPeriodEnd:trueenquanto o cancelamento agendado não foi efetivado. Quando o gateway efetiva, o status muda paracanceledvia webhook.canceledAt: quando o cancelamento foi efetivado.nullse ainda agendado ou nunca cancelado.
Estados que não existem na Allya
Para manter o domínio enxuto, alguns estados internos dos gateways são mapeados:
- Gateway diz
incomplete/incomplete_expired(cobrança inicial falhou) → Allya mapeia comocanceled. - Gateway diz
unpaid→past_due. - Gateway diz
paused→ ainda não é modelado: cai na regra de fallback abaixo (activecom warning interno), não emcanceled.
Qualquer estado não reconhecido (incluindo paused) cai em active e loga um warning interno para revisarmos o mapeamento. A Allya ainda não distingue assinatura pausada.
Veja também
- Criar assinatura: onde os campos aparecem na resposta.
- Cancelar assinatura: transições para
canceled. - Webhooks: eventos
subscription.*por transição. - Status de pagamento: cobranças individuais geradas por assinatura usam essa tabela.