Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spotflow.one/llms.txt

Use this file to discover all available pages before exploring further.

​
Mobile Money Subscriptions

Spotflow supports recurring billing through mobile money, allowing you to charge customers using their Mobile Money (MoMo) wallets on a set schedule without requiring them to re-authorise each payment manually. This page covers how mobile money subscriptions work, how they differ from card subscriptions, and how to set them up.
How MoMo Subscriptions differ from Card Subscriptions:When a customer subscribes with a credit card, future charges happen automatically in the background without the customer doing anything.Mobile Money networks do not allow silent background charges. Because of telecom safety rules, the customer needs to approve the recurring payment.
To make this seamless, Spotflow uses a semi-automated subscription workflow that manages notifications, checkout links, payment retries, and system events for you.

​
What Spotflow automates:

  • Automatic reminders: Sent to customers via email before their next billing due date.
  • Renewal checkout links: Built into reminder emails so customers can log in and pay early.
  • Direct phone prompts (STK Push): Sent directly to the customer’s phone on the exact due date for instant PIN approval.
  • Smart retries: Automated follow-ups if the due-date payment fails.
  • Webhooks: Real-time system notifications sent directly to your server when states change.

​
How It Works

When a customer pays via mobile money for the first time on a subscription plan, Spotflow initiates a mandate request. A mandate is the customer’s standing permission to debit their mobile money wallet on a recurring basis. The customer receives a prompt on their phone to approve the mandate. Once they approve it, Spotflow can charge their wallet automatically on each billing cycle without requiring them to take any action again. If the mandate is declined or expires, the subscription will not renew until a new one is authorised.

​
How This Differs from Card Subscriptions

Card subscriptions on Spotflow use card tokenisation—after the first successful payment, a secure token replaces the card details for future charges. Mobile money subscriptions work differently:
Card SubscriptionsMobile Money Subscriptions
How recurring charges workCard token stored after first paymentMandate approved by customer
Customer action requiredFirst payment onlyMandate approval on sign-up
Renewal triggerAutomatic via stored tokenAutomatic via active mandate
Failure scenarioCard decline or expiryMandate declined, expired, or insufficient balance
Supported currenciesUSD, NGN, GHS, and othersDependent on mobile money provider and region

​
Supported Regions and Providers

Mobile money subscriptions are available in the following regions:
CountryProvider
GhanaMTN Mobile Money, Vodafone Cash, AirtelTigo Money
KenyaM-Pesa
Support for additional providers and regions is being rolled out. Contact support@spotflow.one to check availability for your region.

​
The Subscription Lifecycle

The step-by-step process below shows how a subscription moves from start to finish:
1

Create a Subscription Plan

Create a plan the same way you would for card subscriptions. There is no difference at the plan level. Before you can subscribe a user, you must create a Plan that sets the price, currency, and frequency (weekly, monthly, or yearly).
{
"title": "Basic Plan",
"frequency": "MONTHLY",
"pricingOptions": [
  { "amount": 5000, "currency": "GHS" }
]
}
See Create Subscription Plan for the full API reference.
2

Collect the First Payment

The customer authorizes the initial payment. Once successful, their active subscription cycle officially begins. When initiating the first charge, include the planId and set the payment channel to mobile money. Spotflow will trigger the mandate request automatically.
3

Receive Renewal Reminders

Before the next billing period ends, Spotflow automatically sends out reminder emails containing a secure checkout link:
  • Weekly Plans: Reminders are sent 3 days before expiry.
  • Monthly & Yearly Plans: Reminders are sent 1 week before expiry, and again 3 days before expiry.
4

Approve the Due Date Prompt

If the customer has not manually renewed early via the checkout link, Spotflow triggers an automatic request on the exact due date. A payment prompt pops up directly on the customer’s mobile phone screen asking them to enter their mobile wallet PIN.
5

Handle Retries or Cancellation

If the transaction fails (e.g., phone turned off, insufficient funds, or prompt timed out):
  • Spotflow sends a retry email containing a fresh checkout link every 3 days past the due date.
  • If no payment is completed by the 4th day after the due date, the system automatically changes the subscription status to cancelled.
The customer will receive a prompt on their mobile device to approve the mandate. Their subscription will only activate once they confirm.

​
Subscription Statuses

As a subscription progresses, it will reflect one of these four system statuses:
StatusDescription
activeThe subscription is healthy, and the customer is waiting for their next billing cycle prompt.
failedThe recurring billing cycle failed completely after exhausting all automatic retry updates.
completedThe subscription successfully reached its maximum number of set cycles.
cancelledThe subscription was stopped manually by you, by the customer, or dropped due to non-payment.

​
Subscription Management Endpoints

Manage existing subscriptions using these standard REST routes:
MethodEndpointDescription
GET/subscriptionsReturns a paginated list of all customer subscriptions.
GET/subscriptions/{subscription-id}Returns information for a single specific subscription record.
GET/subscriptions/count/{plan-id}Returns a summary breakdown of totals grouped by status (active, cancelled, etc.).
POST/subscriptions/{subscription-id}/activateInstantly reactivates a previously cancelled subscription profile.
POST/subscriptions/{subscription-id}/cancelImmediately cancels an active subscription and halts future prompts.

​
Webhooks & Events

Spotflow sends an HTTP POST webhook notification payload to your server whenever a subscription changes state. All subscription webhooks share the exact same JSON format structure.

​
Webhook Payload Structure

{
  "event": "subscription_successful",
  "data": {
    "id": "subscription-id",
    "customerId": "customer-id",
    "planId": "plan-id",
    "status": "successful",
    "amount": 10,
    "currency": "GHS",
    "regionName": "Ghana",
    "startDate": "2026-05-15T12:55:45.407Z",
    "nextPaymentDate": "2026-05-22T12:55:45.407Z",
    "createdAt": "2026-05-15T12:55:45.408Z",
    "metadata": {
      "webhook": "test"
    }
  }
}

​
Mandate Expiry and Renewal Failures

If a customer’s mandate expires or a charge fails after renewal reminders, Spotflow will not automatically retry. You have two options: Re-initiate the mandate Send the customer back through the payment flow with the same planId. This will trigger a new mandate request. Cancel the subscription If the customer no longer wishes to continue, cancel their subscription via the Cancel Subscription endpoint.
Do not attempt to charge a mobile money wallet without an active mandate. Doing so will result in a failed transaction and may affect your account standing.

​
Cancelling a Mobile Money Subscription

Cancellation works the same way as card subscriptions.

​
Best Practices

  • Always collect the customer’s phone number at enrolment. Spotflow needs it to route the mandate request to the correct wallet.
  • Communicate the mandate clearly. Tell customers they will receive a prompt to approve recurring charges before they start the payment flow. Unexpected prompts lead to declines.
  • Handle mandate failures gracefully. Build a re-enrolment flow for customers whose mandates expire or are declined, so they can re-authorise without losing their subscription.
  • Test in test mode first. Use Spotflow’s test environment to simulate mandate approvals, declines, and renewal failures before going live.

​
Need Help?

If you have questions about mobile money subscriptions or need help with a specific provider or region, reach out to the team at support@spotflow.one.