feat: (docs) added User Stories

RafaelJohn9 · RafaelJohn9 · commit 8842b07b47d8 · 2025-08-31T20:35:34.000+03:00
Signed-off-by: rafaeljohn9 &lt;rafaeljohb@gmail.com&gt;
diff --git a/docs/docs/account-balance.mdx b/docs/docs/account-balance.mdx
@@ -15,6 +15,14 @@ import Tabs from '@site/docs/components/Tabs';
     size="large"
 />
 
+<SectionHeader title="User Story" size="small" subtitle="Who can use this service" />
+
+    As a finance or operations user, I want to query my organization's M-Pesa account balance so I can reconcile payments and spot problems quickly.
+
+    - Finance analyst: runs balance checks and reconciliation reports.
+    - Till manager / cashier: monitors till balances and requests top-ups when low.
+    - Backend system / automation: polls balances regularly and creates alerts or workflows on anomalies.
+
 <Alert type="info" title="What this page covers">
     This guide documents the Account Balance flow: how to construct queries, expected acknowledgement responses, how to parse ResultURL callbacks (final balances) and QueueTimeOutURL notifications, and important validation/safety checks to implement on your side.
 </Alert>
diff --git a/docs/docs/b2c-account-top-up.mdx b/docs/docs/b2c-account-top-up.mdx
@@ -15,6 +15,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically top up business accounts so that merchants receive funds immediately after customer payments.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/b2c.mdx b/docs/docs/b2c.mdx
@@ -15,6 +15,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically initiate B2C payouts so that customers receive funds immediately after approval.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/business-buygoods.mdx b/docs/docs/business-buygoods.mdx
@@ -15,6 +15,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically initiate B2B payments so that suppliers receive funds immediately after approval.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/business-paybill.mdx b/docs/docs/business-paybill.mdx
@@ -15,6 +15,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically initiate B2B payments so that suppliers receive funds immediately after approval.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/c2b.mdx b/docs/docs/c2b.mdx
@@ -19,6 +19,14 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     NB: C2B Transaction Validation is an optional feature that needs to be activated on M-Pesa. The owner of the shortcode must request activation by emailing apisupport@safaricom.co.ke or M-pesabusiness@safaricom.co.ke if they need their transactions validated before execution.
 </Alert>
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically manage C2B payments so that customers receive funds immediately after approval.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/dynamic-qr.mdx b/docs/docs/dynamic-qr.mdx
@@ -19,6 +19,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically generate dynamic QR codes so that customers can easily make payments.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters" size="small" />
 
 <ParametersTable 
diff --git a/docs/docs/mpesa-express/stk-push.mdx b/docs/docs/mpesa-express/stk-push.mdx
@@ -14,6 +14,19 @@ import ParametersTable from '@site/docs/components/ParametersTable';
   gradient={true}
   size="large"
 />
+<SectionHeader title="User Story" size="small" />
+
+<p>
+  As an e‑commerce merchant, I want to prompt customers to approve payments on their phones so they can complete purchases quickly and securely using M‑Pesa STK Push. When a customer checks out, my backend triggers an STK Push request; the customer receives a prompt to enter their M‑Pesa PIN; once the payment is confirmed via the webhook callback, the order is processed.
+</p>
+
+<ul>
+  <li><strong>Actors:</strong> Merchant, Customer, Developer (integrator)</li>
+  <li><strong>When:</strong> At checkout or when accepting a customer-initiated payment</li>
+  <li><strong>Why:</strong> Fast, secure, and familiar payment flow for users with M‑Pesa</li>
+  <li><strong>Outcome:</strong> Customer authorizes payment on their phone; merchant receives confirmation through the callback and completes the order.</li>
+</ul>
+
 
 <SectionHeader title="Parameters Definition" size="small" />
 
diff --git a/docs/docs/mpesa-express/stk-query.mdx b/docs/docs/mpesa-express/stk-query.mdx
@@ -9,6 +9,12 @@ import Alert from '@site/docs/components/Alert';
 import Tabs from '@site/docs/components/Tabs';
 import ParametersTable from '@site/docs/components/ParametersTable';
 
+<SectionHeader title="User stories" size="small" />
+
+- As an online merchant, I want customers to pay with M-Pesa STK Push so they can pay on their phones without leaving my site or app.
+- As a developer, I want to start an STK Push and check its status so I can update orders even if callbacks are late or missing.
+- As a support agent, I want to look up STK Push results to troubleshoot problems and confirm payments before issuing refunds or fulfilling orders.
+
 
 <SectionHeader title="Parameters" size="small" />
 
diff --git a/docs/docs/reversal.mdx b/docs/docs/reversal.mdx
@@ -15,6 +15,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically reverse M-Pesa transactions so that I can handle customer requests efficiently.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/tax-remittance.mdx b/docs/docs/tax-remittance.mdx
@@ -15,6 +15,13 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+- As a fintech product owner, I want to programmatically remit taxes to KRA so that I can automate compliance processes.
+- As an integrations developer, I want a simple client and clear webhook callbacks so I can implement reliable end-to-end flows with minimal boilerplate.
+- As a billing operations engineer, I want result and timeout notifications with acknowledgements so I can reconcile transactions and trigger retries or alerts when needed.
+- As a reseller partner, I want a tested SDK and examples so I can onboard quickly and reduce integration defects.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
diff --git a/docs/docs/transaction-status.mdx b/docs/docs/transaction-status.mdx
@@ -15,6 +15,18 @@ import ParametersTable from '@site/docs/components/ParametersTable';
     size="large"
 />
 
+<SectionHeader title="User Stories" size="small" />
+
+As a payments engineer or backend developer at a merchant/PSP, I want to query the status of an M‑Pesa transaction and reliably handle result and timeout callbacks so I can reconcile payments, notify customers, and trigger compensating workflows when needed.
+
+- **Persona:** Payments engineer, reconciliation analyst, or backend developer integrating M‑Pesa.
+- **Goal:** Retrieve definitive transaction state (success, failed, pending) and process callbacks for downstream business logic.
+- **Acceptance criteria:**
+    - Submit a Transaction Status query and receive an accepted response from Daraja.
+    - ResultURL receives structured result payloads and the service acknowledges with ResultCode 0.
+    - QueueTimeOutURL receives timeout notifications that trigger retry or compensation flows.
+    - Request validation prevents invalid MSISDNs, enforces identifier rules, and blocks overly long remarks/occasions.
+
 <SectionHeader title="Parameters Definition" size="small" />
 
 <ParametersTable
