Do I need PCI compliance?

No — upstream card processor handles vaulting.

Can customers self-serve their payment method?

Yes — white-labeled portal lets them manage rails.

How accurate is MRR vs bank?

They match in real time — non-custodial settlement, no delay.

ShegerPay for Subscription Businesses

Q: What happens when a Telebirr renewal fails?

ShegerPay automatically retries on the next configured rail.

Q: Can I configure different rails per customer?

Yes — each subscription has its own rails array.

Q: How long is dunning grace?

Configurable. Default 14 days with 4 retries.

Quick Answer: Subscription businesses use ShegerPay to verify recurring payments across CBE, Telebirr, Visa, PayPal, and USDT with automatic multi-rail fallback dunning — when one rail fails, the next is tried before churn is recorded. Non-custodial settlement means renewals land in your account in real time, so MRR dashboards reflect actual cash, not pending settlement.

The problem subscription businesses face today

Subscription churn is brutal. Industry data says 20-40% of involuntary churn is just failed payments — expired cards, insufficient balance, wrong rail at the wrong moment. Stripe solves this with smart retries in markets where Stripe operates. In Ethiopia, where Stripe doesn't operate and most processors don't support recurring billing at all, you eat that churn manually.

The typical Ethiopian subscription stack looks like: a Telebirr API integration that handles maybe 60% of customers, manual CBE reconciliation for another 30%, and a PayPal subscription button for diaspora customers. Three rails, three reconciliation flows, zero unified retry logic. When a Telebirr renewal fails, nothing automatically tries the customer's card. The customer gets locked out. They write angry support tickets. They churn.

Then there's the settlement-vs-MRR mismatch. Custodial processors hold renewals 2-7 days. A subscription business measuring MRR daily sees numbers that don't match the bank for nearly a week. CFO reports become fiction. Cohort analyses lag. Investor updates need footnotes.

How ShegerPay solves it

ShegerPay models subscriptions as first-class objects with explicit rail ordering and retry policy. When a renewal date hits, ShegerPay attempts the primary rail. If it fails (insufficient funds on Telebirr, expired card, etc.), ShegerPay falls through to the next configured rail. If all rails fail, dunning kicks in — escalating notifications at configured intervals — before any subscription is marked cancelled.

Every renewal, retry, and recovery fires a signed webhook. Your application logic stays clean: listen for subscription.renewed, extend access. Listen for subscription.payment_failed, send the dunning email. Listen for subscription.recovered, celebrate.

Because settlement is non-custodial, your MRR dashboard reflects cash in the bank in real time. The webhook fires when the rail confirms — which is when the money is actually yours.

Code example

import ShegerPay from '@shegerpay/sdk';
const sp = new ShegerPay({ apiKey: 'sk_test_demo' });

// Create a subscription with full multi-rail fallback + dunning
const sub = await sp.subscriptions.create({
  customerId: 'cust_8821',
  plan: 'pro_monthly',
  amount: 499,
  currency: 'ETB',
  interval: 'month',
  rails: ['cbe', 'telebirr', 'visa', 'usdt_tron'],   // try in order
  retryPolicy: {
    attempts: 4,
    backoffHours: [4, 24, 72, 168],
    advanceRailOnFailure: true,                       // CBE fails → Telebirr next attempt
  },
  dunning: {
    notifyChannels: ['email', 'telegram'],
    finalCancellationAfterHours: 336,                 // 14 days grace
  },
  webhookUrl: 'https://app.example.et/sp-webhook',
});

// Webhook handler
app.post('/sp-webhook', (req, res) => {
  if (!sp.webhooks.verify(req.rawBody, req.headers['x-shegerpay-signature'])) return res.sendStatus(401);
  const { event, data } = req.body;

  switch (event) {
    case 'subscription.renewed':
      db.users.extend(data.customerId, data.nextRenewalAt);
      break;
    case 'subscription.payment_failed':
      // ShegerPay already advanced the rail; we just notify the user
      mailer.dunning(data.customerId, { attempt: data.attemptNumber, nextRail: data.nextRail });
      break;
    case 'subscription.recovered':
      mailer.thanks(data.customerId);
      break;
    case 'subscription.cancelled':
      db.users.downgrade(data.customerId);
      break;
  }
  res.json({ ok: true });
});

Why non-custodial matters for subscriptions

Custodial settlement delay is the silent killer of subscription metrics. When your processor holds 5 days of MRR before releasing, you cannot reconcile in real time — your CFO sees one number, your bank sees another, and the gap grows worse mid-month. Cohort retention curves get distorted because "paid this month" doesn't match "settled this month." Investor decks need disclaimers.

ShegerPay's non-custodial settlement means every successful renewal is in your account before the webhook fires. The number on your dashboard is the number in your bank. MRR is real-time. Cohort math is honest. And when a customer disputes, only that customer's payment is at risk — there's no pool of held funds for a processor to freeze across your entire customer base.

Workflow features used

Subscription objects with rail ordering
Multi-rail fallback on retry (CBE → Telebirr → card → USDT)
Configurable retry backoff and attempt count
Dunning notifications (email + Telegram)
Signed renewal/failure/recovery webhooks
Real-time MRR reporting via /v1/subscriptions/metrics

Pricing fit

Subscription businesses with <100 active subs typically fit on Free. Crossing 100 active subs with monthly renewals moves you to Starter $9. 1,000+ active subs with multi-rail dunning fits Growth $29. Annual contracts, custom dunning sequences, and enterprise SLA on Enterprise.

FAQ

What happens when a Telebirr renewal fails? ShegerPay automatically retries on the next configured rail (e.g. Visa). The customer gets one dunning notification, not a churn email.

Can I configure different rails for different customers? Yes — each subscription has its own rails array, often matching what the customer signed up with.

How long is the dunning grace period? Configurable. Default 14 days with 4 retries.

Do I need to manage card storage / PCI compliance? No — the upstream card processor handles card vaulting; ShegerPay only verifies settlement events.

Can customers self-serve to update their payment method? Yes — the white-labeled customer portal lets them add/remove rails and reorder priority.

How accurate is the MRR metric vs bank reality? They match in real time, because ShegerPay only marks a renewal as confirmed after the rail-level settlement event.