Subscrições

Uma subscrição nasce de uma sessão de checkout como as outras, com kind igual a subscription e o plano em subscription. O amount é o preço de cada ciclo. Quando o comprador paga o primeiro ciclo, a subscrição fica ativa e recebes subscription.created (além do payment.succeeded desse pagamento).

curl -s "$VIBRA_API_URL/v1/checkout/sessions" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: assinatura-cliente-77" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "subscription",
    "subscription": {"interval": "month", "cycles": 12},
    "amount": 500000,
    "currency": "AOA",
    "description": "Plano mensal",
    "success_url": "https://loja.exemplo.ao/obrigado",
    "customer": {"email": "cliente@exemplo.ao"},
    "metadata": {"cliente_id": "77"}
  }'

O dia da cobrança é o do primeiro pagamento: uma subscrição mensal paga a 31 renova no último dia dos meses mais curtos, e volta ao 31 quando o mês o tem. Os avisos das renovações vão para o email do comprador, e a sessão paga passa a trazer o id da subscrição em subscription.id.

Com first_cycle_amount, o primeiro pagamento (o livro, a taxa, o recibo e o payment.succeeded) é do valor do primeiro ciclo, e cada renovação é do amount. No cartão, o Stripe cria a subscrição pelo preço cheio com um desconto de uma vez, e continua a renovar sozinho. A subscrição mostra os dois valores, em amount e first_cycle_amount.

O objeto da subscrição (na /v1 e em todos os eventos subscription.*) diz como renova no campo renewal: automatic quando se cobra sozinho (cartão e débito direto), notice quando se renova por aviso. Para o cartão renovar sozinho, a subscrição tem de nascer de uma sessão com "kind": "subscription": nunca abras uma sessão nova por ciclo para o cartão. Se a cobrança automática falhar, a subscrição passa a past_due e o cliente recebe o aviso com o link do ciclo.

Cada ciclo pago é um pagamento normal: tem o seu payment.succeeded, o seu recibo, entra no teu saldo, e leva a subscrição ao ciclo seguinte com subscription.renewed.

O objeto de cada evento, com todos os campos, está na referência dos eventos. Dá acesso ao teu cliente enquanto a subscrição estiver active ou past_due, e até ao current_period_end.

O id da subscrição (sub_...) chega no subscription.created. Com ele:

# Ler
curl -s "$VIBRA_API_URL/v1/subscriptions/sub_..." \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY"

# Cancelar no fim do ciclo pago (com {"at_period_end": false}, termina já)
curl -s -X POST "$VIBRA_API_URL/v1/subscriptions/sub_.../cancel" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: cancelar-sub-77"

# Um link de uso único para a página do cliente
curl -s -X POST "$VIBRA_API_URL/v1/subscriptions/sub_.../portal" \
  -H "Authorization: Bearer $VIBRA_SECRET_KEY" \
  -H "Idempotency-Key: portal-77-$(date +%s)"

doze := 12
sessao, err := cliente.CreateCheckoutSession(ctx, &vibra.CheckoutSessionParams{
	Amount: 500000, Currency: vibra.AOA, Description: "Plano mensal",
	Kind:         vibra.KindSubscription,
	Subscription: &vibra.SubscriptionPlan{Interval: vibra.IntervalMonth, Cycles: &doze}, // Cycles nil: até cancelar
})

// Depois do primeiro pagamento (chega subscription.created, com o id):
sub, err := cliente.GetSubscription(ctx, idDaSubscricao)
link, err := cliente.CreateSubscriptionPortalLink(ctx, sub.ID) // mandar link.URL ao cliente
sub, err = cliente.CancelSubscription(ctx, sub.ID, nil)        // no fim do ciclo pago

await vibra.createCheckoutSession({
  amount: 500000, currency: "AOA", description: "Plano mensal",
  kind: "subscription",
  subscription: { interval: "month", cycles: 12 }, // sem cycles: até cancelar
});

// Depois do primeiro pagamento (chega subscription.created, com o id):
const sub = await vibra.getSubscription(idDaSubscricao);
const { url } = await vibra.createSubscriptionPortalLink(sub.id); // mandar ao cliente
await vibra.cancelSubscription(sub.id); // no fim do ciclo pago; { at_period_end: false } termina já

A página do cliente é onde o teu cliente cancela, muda o método do próximo ciclo e vê os recibos, sem criar conta. O link da rota portal serve uma vez e vale 24 horas; manda-o ao cliente (no teu site, num botão "Gerir a subscrição"). O cliente também o pode pedir por email, na própria página. Cada pedido dá um link novo.