Build an Insurance Premium Collection Portal

Tables: insurance_products (name, type, coverage_amount, premium_monthly, paystack_plan_code, terms_url), policies (holder_id, product_id, policy_number, paystack_subscription_code, status, start_date, grace_until, expires_at), claims (policy_id, type, amount, status, submitted_at).

function generatePolicyNumber() {
  return 'POL-' + new Date().getFullYear() + '-' + Math.random().toString(36).toUpperCase().slice(2, 8);
}

async function enrollPolicyholder(holderEmail, holderId, productId) {
  var product = await db.insuranceProducts.findById(productId);

  var policy = await db.policies.create({
    holder_id: holderId,
    product_id: productId,
    policy_number: generatePolicyNumber(),
    status: 'pending_first_payment',
    start_date: new Date(),
  });

  var res = await fetch('https://api.paystack.co/transaction/initialize', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.PAYSTACK_SECRET_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: holderEmail,
      amount: product.premium_monthly,
      plan: product.paystack_plan_code,
      metadata: { holder_id: holderId, policy_id: policy.id, product_id: productId },
    }),
  });
  return { policy, authorizationUrl: (await res.json()).data.authorization_url };
}

// Webhook: activate policy on first premium
if (event.event === 'subscription.create') {
  var meta = event.data.metadata;
  var nextPayment = new Date(event.data.next_payment_date);

  await db.policies.update(meta.policy_id, {
    paystack_subscription_code: event.data.subscription_code,
    status: 'active',
    expires_at: nextPayment,
  });
  await issuePolicyCertificate(meta.policy_id, meta.holder_id);
}

// Renewal confirmed
if (event.event === 'invoice.create' && event.data.status === 'success') {
  var code = event.data.subscription.subscription_code;
  await db.policies.update({ code }, {
    status: 'active',
    grace_until: null,
    expires_at: new Date(event.data.next_payment_date),
  });
}

// Failed payment: enter grace period
if (event.event === 'invoice.payment_failed') {
  var code = event.data.subscription.subscription_code;
  var graceUntil = new Date();
  graceUntil.setDate(graceUntil.getDate() + 14); // 14-day grace period

  await db.policies.update({ code }, { status: 'grace_period', grace_until: graceUntil });
  await sendPremiumFailedEmail(code,
    'Your premium payment failed. Coverage continues until ' + graceUntil.toDateString() +
    '. Please update your payment method to avoid policy lapse.'
  );
}

// Policy cancelled or subscription disabled — lapse
if (event.event === 'subscription.disable') {
  var code = event.data.subscription_code;
  await db.policies.update({ code }, { status: 'lapsed' });
  await notifyPolicyLapsed(code);
}

// Cron: suspend coverage after grace period expires
async function suspendLapsedPolicies() {
  var now = new Date();
  var overdue = await db.policies.findAll({ status: 'grace_period', grace_until_lt: now });
  for (var policy of overdue) {
    await db.policies.update(policy.id, { status: 'suspended' });
    await sendCoverageSuspendedEmail(policy.holder_id);
  }
}

// Claim eligibility check
async function isEligibleForClaim(policyId) {
  var policy = await db.policies.findById(policyId);
  return policy.status === 'active' || policy.status === 'grace_period';
}

See build a gym membership app for the same grace period and subscription lifecycle pattern applied to a simpler membership product.

Sign up for the McTaba newsletter