Major Upgrade: Gradio 6, Global Fintech Assistant, Improved prompts and token limits

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.faiss filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -38,5 +38,13 @@ venv.bak/
 # Logs
 *.log
 
-# Model cache
-.cache/
+# Model cache (large downloaded model weights — don't commit)
+.cache/
+
+# HuggingFace model downloads
+*.bin
+*.safetensors
+*.gguf
+
+# FAISS index MUST be committed — DO NOT add faiss_index/ here
+# Run build_index.py once, then: git add faiss_index/

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

README.md

@@ -9,79 +9,72 @@ app_file: app.py
 pinned: false
 ---
 
-# 🏦 ocs4dev - Fintech API Integration Assistant
+# 🏦 ocs4dev — Fintech API Integration Assistant
 
-## Overview
-ocs4dev is a specialized AI assistant designed to help developers integrate fintech APIs including MTN MoMo, Pesapal, Airtel,Sentezo etc. It provides code examples, implementation guidance, and best practices for payment gateway integration.
+Specialized AI chatbot for integrating African fintech APIs. Powered by **local FAISS RAG** — no cloud database required.
 
 ## Features
-- 🔧 **Code-Focused**: Optimized for API integration tasks with practical examples
-- 🤖 **Multi-Model Support**: Choose between local Qwen2.5-Coder or API models (OpenAI, Anthropic, Google)
-- 🔒 **Secure**: No API keys stored permanently
-- 📋 **Copy-Friendly**: Built-in code copying functionality
-- 🚀 **Fast**: Multiple model options for optimal performance
-- 🔄 **RAG-Powered**: Retrieves relevant documentation from vector database
+
+- 🔍 **Local RAG** — FAISS vector search over bundled API docs (no Supabase, no cloud DB)
+- 🤖 **Multi-Model** — Google Gemini 3, OpenAI GPT-5, Anthropic Claude 4, or local Qwen 3B
+- 📋 **Code-Focused** — Working code examples with proper error handling
+- 🔒 **Secure** — API keys entered at runtime, never stored
+- 🚀 **HF Spaces Ready** — CPU-optimized, fits free tier
 
 ## Supported APIs
-- **MTN MoMo**: Mobile money integration
-- **Airtel API**: Airtel api integration
-- **Pesapal**: Payment gateway services
-- **Sentezo**: Mobile payment platform
-- And more fintech APIs...
 
-## Model Options
+| API | Coverage |
+|---|---|
+| **MTN MoMo** | Collections, Disbursements, Remittances, Callbacks |
+| **Pesapal** | E-Commerce API 3.0, POS, Recurring Payments, IPN |
+| **Sentezo** | Wallet Deposits, Withdrawals, Bank Transfers |
 
-### Local Model (Free)
-- **Qwen2.5-Coder-7B-Instruct-AWQ**: Quantized model optimized for code generation
-- Requires GPU for best performance
-- No API key needed
+## Model Options (March 2026)
 
-### API Models
-- **OpenAI**: GPT-4o-mini (budget) / O4-mini (premium)
-- **Anthropic**: Claude-3.5-Sonnet / Claude-4-Sonnet
-- **Google**: Gemini-2.0-Flash / Gemini-2.0-Flash-Thinking
+| Provider | Budget | Premium |
+|---|---|---|
+| **Google** ⭐ | Gemini 3 Flash | Gemini 3.1 Pro |
+| **OpenAI** | GPT-5 mini | GPT-5.2 |
+| **Anthropic** | Claude Haiku 4.5 | Claude Opus 4.6 |
+| **Local** | Qwen2.5-Coder-3B-Int4 | — |
 
 ## Quick Start
+
 1. Visit the [Space URL](https://huggingface.co/spaces/YOUR_USERNAME/ocs4dev)
-2. Choose your preferred model provider
-3. Add API keys if using cloud models
-4. Start asking questions about fintech API integration!
+2. Choose a model in the **☰ Settings** panel
+3. Add your API key (or use the free local model)
+4. Start asking questions!
 
-## Example Questions
-- "How do I authenticate with MTN MoMo API?"
-- "Show me a Pesapal payment integration example"
-- "What are the required headers for Sentezo API?"
-- "How do I handle payment webhooks?"
-- "Best practices for API error handling"
+## Self-Hosting / Development
 
-## Environment Variables
-For self-hosting, set these environment variables:
 ```bash
-# Supabase (for vector store)
-SUPABASE_URL=your-supabase-url
-SUPABASE_SERVICE_KEY=your-service-key
+# Install dependencies
+pip install -r requirements.txt
+
+# Build the FAISS vector index (run once)
+python build_index.py
+
+# Start the app
+python app.py
+```
+
+## Environment Variables
+
+Only needed if you want API keys pre-loaded (users can also enter them in the UI):
 
-# API Keys (optional)
+```bash
 OPENAI_API_KEY=your-openai-key
 ANTHROPIC_API_KEY=your-anthropic-key
 GOOGLE_API_KEY=your-google-key
 ```
 
 ## Technical Stack
-- **Frontend**: Gradio
-- **LLM Framework**: LangChain
-- **Vector Store**: Supabase
-- **Models**: Qwen2.5-Coder, OpenAI, Anthropic, Google
-- **Embeddings**: OpenAI text-embedding-3-small
 
-## Contributing
-Contributions are welcome! Please feel free to submit a Pull Request.
-
-## License
-This project is licensed under the MIT License.
-
-## Support
-For issues or questions, please open an issue on GitHub or contact me.
+- **Frontend**: Gradio 5
+- **LLM Framework**: LangChain
+- **Vector Store**: FAISS (local, no cloud)
+- **Embeddings**: sentence-transformers/all-MiniLM-L6-v2 (free, CPU)
+- **Local Model**: Qwen2.5-Coder-3B-Instruct-Int4
 
 ---
-Built with ❤️ using Qwen2.5-Coder, LangChain, and Gradio
+Built with ❤️ by Aaron

build_index.py

@@ -0,0 +1,181 @@
+"""
+build_index.py — One-time FAISS index builder for ocs4dev
+==========================================================
+Run this script ONCE locally before deploying to HuggingFace Spaces.
+It reads all markdown files from knowledge_base/ and builds a FAISS
+vector index that the main app uses for retrieval.
+
+After running, commit the generated faiss_index/ folder to your repo:
+    git add faiss_index/
+    git commit -m "Add FAISS vector index"
+    git push
+
+Usage:
+    python build_index.py
+    python build_index.py --kb ./knowledge_base --out ./faiss_index
+"""
+
+import os
+import argparse
+from pathlib import Path
+
+from langchain_community.document_loaders import TextLoader, DirectoryLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+
+# --- Defaults ---
+DEFAULT_KB_DIR   = "./knowledge_base"
+DEFAULT_OUT_DIR  = "./faiss_index"
+EMBEDDING_MODEL  = "sentence-transformers/all-MiniLM-L6-v2"
+CHUNK_SIZE       = 1000
+CHUNK_OVERLAP    = 200
+
+
+def load_documents(kb_dir: str):
+    """Recursively load all .md files from the knowledge base directory."""
+    print(f"\n📂 Loading documents from: {kb_dir}")
+    loader = DirectoryLoader(
+        kb_dir,
+        glob="**/*.md",
+        loader_cls=TextLoader,
+        loader_kwargs={"encoding": "utf-8"},
+        show_progress=True,
+        use_multithreading=True,
+    )
+    docs = loader.load()
+
+    # Enrich metadata with API provider based on folder name
+    for doc in docs:
+        source = doc.metadata.get("source", "")
+        path_parts = Path(source).parts
+        # Detect provider from folder structure
+        for part in path_parts:
+            if "mtn" in part.lower():
+                doc.metadata["provider"] = "MTN MoMo"
+                break
+            elif "pesapal" in part.lower():
+                doc.metadata["provider"] = "Pesapal"
+                break
+            elif "sentezo" in part.lower() or "ssentezo" in part.lower():
+                doc.metadata["provider"] = "Sentezo"
+                break
+        else:
+            doc.metadata["provider"] = "General"
+
+    print(f"✅ Loaded {len(docs)} documents")
+    return docs
+
+
+def split_documents(docs):
+    """Split documents into overlapping chunks for better retrieval."""
+    print(f"\n✂️  Splitting into chunks (size={CHUNK_SIZE}, overlap={CHUNK_OVERLAP})...")
+    splitter = RecursiveCharacterTextSplitter(
+        chunk_size=CHUNK_SIZE,
+        chunk_overlap=CHUNK_OVERLAP,
+        separators=["\n## ", "\n### ", "\n#### ", "\n\n", "\n", ". ", " "],
+    )
+    chunks = splitter.split_documents(docs)
+    print(f"✅ Created {len(chunks)} chunks from {len(docs)} documents")
+    return chunks
+
+
+def build_faiss_index(chunks, out_dir: str):
+    """Generate embeddings and save FAISS index to disk."""
+    print(f"\n🔢 Loading embedding model: {EMBEDDING_MODEL}")
+    print("   (This may take a minute on first run — model will be cached)")
+    embeddings = HuggingFaceEmbeddings(
+        model_name=EMBEDDING_MODEL,
+        model_kwargs={"device": "cpu"},
+        encode_kwargs={"normalize_embeddings": True},
+    )
+
+    print(f"\n🔄 Building FAISS index from {len(chunks)} chunks...")
+    vector_store = FAISS.from_documents(chunks, embeddings)
+
+    os.makedirs(out_dir, exist_ok=True)
+    vector_store.save_local(out_dir)
+    print(f"✅ FAISS index saved to: {out_dir}/")
+    return vector_store
+
+
+def run_verification(vector_store):
+    """Run a quick search test to confirm the index works."""
+    print("\n🧪 Running verification queries...")
+    test_queries = [
+        ("MTN MoMo authentication", "MTN MoMo"),
+        ("Pesapal payment integration", "Pesapal"),
+        ("Sentezo wallet deposit", "Sentezo"),
+    ]
+
+    all_passed = True
+    for query, expected_provider in test_queries:
+        try:
+            results = vector_store.similarity_search(query, k=3)
+            providers = [r.metadata.get("provider", "?") for r in results]
+            hit = any(expected_provider in p for p in providers)
+            status = "✅" if hit else "⚠️ "
+            if not hit:
+                all_passed = False
+            print(f"   {status} '{query}'")
+            print(f"      Top result: {Path(results[0].metadata.get('source', '?')).name}")
+            print(f"      Preview: {results[0].page_content[:80].strip()}...")
+        except Exception as e:
+            print(f"   ❌ '{query}' — Error: {e}")
+            all_passed = False
+
+    return all_passed
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Build FAISS vector index for ocs4dev"
+    )
+    parser.add_argument(
+        "--kb", default=DEFAULT_KB_DIR,
+        help=f"Path to knowledge base directory (default: {DEFAULT_KB_DIR})"
+    )
+    parser.add_argument(
+        "--out", default=DEFAULT_OUT_DIR,
+        help=f"Output directory for FAISS index (default: {DEFAULT_OUT_DIR})"
+    )
+    args = parser.parse_args()
+
+    print("=" * 60)
+    print("  ocs4dev — FAISS Vector Index Builder")
+    print("=" * 60)
+
+    # Validate knowledge base dir
+    if not os.path.exists(args.kb):
+        print(f"\n❌ Knowledge base directory not found: {args.kb}")
+        print("   Make sure your knowledge_base/ folder exists with .md files.")
+        return
+
+    # Load → split → index
+    docs = load_documents(args.kb)
+    if not docs:
+        print("❌ No .md files found in the knowledge base!")
+        return
+
+    chunks = split_documents(docs)
+    vector_store = build_faiss_index(chunks, args.out)
+
+    # Verify
+    passed = run_verification(vector_store)
+
+    print("\n" + "=" * 60)
+    if passed:
+        print("🎉 Index built and verified successfully!")
+    else:
+        print("⚠️  Index built, but some queries returned unexpected results.")
+        print("   Consider checking your knowledge base content.")
+    print()
+    print("📋 Next steps:")
+    print(f"   1. git add {args.out}/")
+    print(f"   2. git commit -m 'Add FAISS vector index'")
+    print(f"   3. git push (to deploy to HuggingFace Spaces)")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

env_example.txt

@@ -1,8 +1,4 @@
-# Supabase Configuration (Required for vector store)
-SUPABASE_URL=your-supabase-project-url
-SUPABASE_SERVICE_KEY=your-supabase-service-key
-
-# API Keys (Optional - users can add via UI)
+# API Keys (optional — users can also enter via the UI)
 OPENAI_API_KEY=your-openai-api-key
 ANTHROPIC_API_KEY=your-anthropic-api-key
 GOOGLE_API_KEY=your-google-api-key

faiss_index/index.faiss

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a1f3acd97960c02d07d137e5c67e9f0159c3e3b4df1c8085b5da4aad3cbd0602
+size 440877

faiss_index/index.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7bf44f2327bab40775d8c7b0e4005ac4ad377608a1583c92d654ab19687eb236
+size 210119

knowledge_base/mtn_momo/mtn_momo_api_brand_guidelines.md

@@ -0,0 +1,11 @@
+# MoMo API
+
+## Brand Guidelines
+
+The **MTN MoMo logo** will only be used at the **payment stage** of your customer journey. Below are the brand guidelines for use of the **MTN MoMo Brand**:
+
+- When used, the logo sits in the **bottom right hand corner** of the messaging, against a **white** or **MoMo Blue** background
+- The distance between the logo and the border to the right and border to the bottom is always **equal** and equivalent size to the **blue bulb** that forms the MTN logo
+- The size of the logo will occupy the rectangle space of the ad where it features, scaled to feature **prominently** relative to all the other content in the ad
+
+Reference to or usage of the **MTN MoMo logo** in other instances other than at the payment stage in the customer journey, will be restricted a statement of endorsement i.e. **"Supported by MTN MoMo"**. The use of the **MTN MoMo** in these instances is **prohibited**.

knowledge_base/mtn_momo/mtn_momo_api_callback_docs.md

@@ -0,0 +1,91 @@
+# MoMo API
+
+## Callback
+
+### Setting up a callback URL
+
+**Transfer** and **RequestToPay** APIs are **Asynchronous** in MTN MoMo API Platform
+
+When a merchant system sends a POST of either `/transfer`, or `/requesttopay` APIs, the Gateway validates the request and then responds with **'202 Accepted'**
+
+The transaction is then queued for processing.
+
+Once processed, a callback with the final result of the transaction is sent to the merchant system
+
+In order to receive the callback for your transactions, please consider the following:
+
+#### a) On Sandbox
+
+- Register your callback host by specifying the domain as **providerCallbackHost** when creating your API Keys. On production this will be done via the Account Portal
+- Specify the callback URL in each of your `/requesttopay` or `/transfer` POST
+- Use **http** and not **https** on sandbox
+- Allow **PUT & POST** on your callback listener host
+
+#### b) On Production
+
+- After Go-live you will be provided a link to log on to your **Accounts Portal**
+- You will be required to register you callback host on the portal when creating your API keys as shown below
+- Only **https** is allowed on production
+- Allow **PUT & POST** on your callback listener host
+
+The Wallet Platform will only send the callback **once**. There is no retry on the callback if the Partner system does not respond. A merchant system can, in cases where a callback was not received, poll for the transaction status as described in the **GET method**
+
+Let's look at the **Deposit API** under the product set **Disbursement** for instance.
+
+The are two Deposit APIs - **Deposit-V1** and **Deposit-V2**.
+
+The callback request for **Deposit-V1** can be sent via
+
+```
+https://momodeveloper.mtn.com/API-collections#api=disbursement&operation=Deposit-V1
+```
+
+The callback received would be of the type **POST**.
+
+### Approved Intermediate CA's for Open API
+
+For Open API callbacks to function, the **3PP Intermediate certificate chains** must be imported on the PG's **tls_keystore** and callback URL's are required to use **https L7 protocol**:
+
+**CN** – Refers to the Common name of the immediate intermediate CA Chain
+
+**Alias** – Name that is used while storing the Certificate in PG's tls_keystore
+
+Below is the list of **Approved Intermediate CA's** that's already available to use:
+
+| Alias | CN |
+|-------|-----|
+| `GTS_CA_1C3` | CN=GTS CA 1C3; O=Google Trust Services LLC; C=US |
+| `Go_Daddy_Secure_Certificate_Authority_-_G2` | CN=Go Daddy Secure Certificate Authority - G2; OU=http://certs.godaddy.com/repository/; O=GoDaddy.com, Inc.; C=US |
+| `R3` | CN=R3; O=Let's Encrypt; C=US |
+| `Sectigo_RSA_Domain_Validation_Secure_Server_CA` | CN=Sectigo RSA Domain Validation Secure Server CA; O=Sectigo Limited; C=GB |
+| `AmazonRCA4` | CN = Amazon Root CA 4,O = Amazon,C = US |
+| `AmazonCA1B` | CN = Amazon,OU = Server CA 1B,O = Amazon,C = US |
+| `Encryption_Everywhere_DV_TLS_CA_-_G1` | CN=Encryption Everywhere DV TLS CA - G1; OU=www.digicert.com; O=DigiCert Inc; C=US |
+| `cPanel,_Inc._Certification_Authority` | CN=cPanel, Inc. Certification Authority; O=cPanel, Inc.; C=US |
+| `DigiCert_SHA2_Secure_Server_CA` | CN=DigiCert SHA2 Secure Server CA; O=DigiCert Inc; C=US |
+| `GTS_CA_1D4` | CN=GTS CA 1D4; O=Google Trust Services LLC; C=US |
+| `Cloudflare_Inc_ECC_CA-3` | CN=Cloudflare Inc ECC CA-3; O=Cloudflare, Inc.; C=US |
+| `DigiCert_SHA2_High_Assurance_Server_CA` | CN=DigiCert SHA2 High Assurance Server CA; OU=www.digicert.com; O=DigiCert Inc; C=US |
+| `ZeroSSL_RSA_Domain_Secure_Site_CA` | CN=ZeroSSL RSA Domain Secure Site CA; O=ZeroSSL; C=AT |
+| `AlphaSSL_CA_-_SHA256_-_G2` | CN=AlphaSSL CA - SHA256 - G2; O=GlobalSign nv-sa; C=BE |
+| `RapidSSL_TLS_DV_RSA_Mixed_SHA256_2020_CA-1` | CN=RapidSSL TLS DV RSA Mixed SHA256 2020 CA-1; O=DigiCert Inc; C=US |
+| `Thawte_RSA_CA_2018` | CN=Thawte RSA CA 2018; OU=www.digicert.com; O=DigiCert Inc; C=US |
+| `GoGetSSL_RSA_DV_CA` | CN=GoGetSSL RSA DV CA; O=GoGetSSL; C=LV |
+| `Gandi_Standard_SSL_CA_2` | CN=Gandi Standard SSL CA 2; O=Gandi; C=FR |
+| `GlobalSign_RSA_OV_SSL_CA_2018` | CN=GlobalSign RSA OV SSL CA 2018; O=GlobalSign nv-sa; C=BE |
+| `DigiCert_TLS_RSA_SHA256_2020_CA1` | CN=DigiCert TLS RSA SHA256 2020 CA1; O=DigiCert Inc; C=US |
+| `GeoTrust_RSA_CA_2018` | CN=GeoTrust RSA CA 2018; OU=www.digicert.com; O=DigiCert Inc; C=US |
+| `Microsoft_RSA_TLS_CA_02` | CN=Microsoft RSA TLS CA 02; O=Microsoft Corporation; C=US |
+| `SSL.com_RSA_SSL_subCA` | CN=SSL.com RSA SSL subCA; O=SSL Corporation; C=US |
+| `RapidSSL_TLS_RSA_CA_G1` | CN=RapidSSL TLS RSA CA G1; OU=www.digicert.com; O=DigiCert Inc; C=US |
+| `Thawte_EV_RSA_CA_2018` | CN=Thawte EV RSA CA 2018; OU=www.digicert.com; O=DigiCert Inc; C=US |
+| `Microsoft_Azure_TLS_Issuing_CA_05` | CN=Microsoft Azure TLS Issuing CA 05; O=Microsoft Corporation; C=US |
+| `GeoTrust_TLS_DV_RSA_Mixed_SHA256_2020_CA-1` | CN=GeoTrust TLS DV RSA Mixed SHA256 2020 CA-1; O=DigiCert Inc; C=US |
+| `E1` | CN=E1; O=Let's Encrypt; C=US |
+| `Sectigo_ECC_Domain_Validation_Secure_Server_CA` | CN=Sectigo ECC Domain Validation Secure Server CA; O=Sectigo Limited; C=GB |
+| `COMODO_RSA_Domain_Validation_Secure_Server_CA` | CN=COMODO RSA Domain Validation Secure Server CA; O=COMODO CA Limited; C=GB |
+| `entrustl1k_.entrustrootca-g2` | CN = Entrust Certification Authority - L1K,OU = (c) 2012 Entrust\, Inc. - for authorized use only,OU = See www.entrust.net/legal-terms,O = Entrust\, Inc.,C = US |
+
+**NOTE**: In case any Partner's callback URL is not part of the **Approved Intermediate CA's**, callbacks might not work for the said Partners.
+
+---

knowledge_base/mtn_momo/mtn_momo_api_error_codes.md

@@ -0,0 +1,31 @@
+# MoMo API
+
+## Common Error Codes
+
+The complete definitions of error codes are found in the swagger documentation. Below is the list of error codes available.
+
+### Common Error Codes
+
+| HTTP Code | Error Response Code | Description | Action |
+|-----------|-------------------|-------------|--------|
+| **409** | `RESOURCE_ALREADY_EXIST` | Duplicated Reference ID. Every request must have a unique reference ID; using an ID of the previous request will result in this error response. | Check **X-Reference ID** used is unique and is in **UUID V4** format |
+| **401** | `ACCESS DENIED DUE TO INVALID SUBSCRIPTION KEY` | Authentication failed. Credentials invalid. Header **Ocp-APIM-Subscription-Key** value is incorrect. | Check the User Profile Section to verify the related product subscription key is used. **Collection**, **Disbursement** and **Remittance** have different subscription keys. If the primary key doesn't work, try the secondary key. Contact MTN support if both provided keys aren't working.<br>- Sandbox subscription key are located in https://momodeveloper.mtn.com/developer<br>- Production subscription key are located in https://momoapi.mtn.com/developer |
+| **404** | `RESOURCE NOT FOUND` | Reference ID not found. Requested resource does not exist. Predominantly occurs with **Get Status API** and implies that the requested reference ID does not exist. This results in the Request to Debit or Transfer transaction being unsuccessful. | Check if the original request to pay or the transfer (disbursement) operation was successful with response code **202**. |
+| **400** | `REQUEST REJECTED/ BAD REQUEST` | Bad request. Request does not follow the specification. | This relates to any of the below scenarios:<br>- Incorrect/wrong values in the headers, and/or the **X-ref ID** does not meet **UUID Version 4**.<br>- Inputting a Body in an API that is not supported e.g. `/Token API`<br>- Having unsupported special characters in the Body request for example an apostrophe (`'`).<br>- Invalid currency – needs to match the target environment currency.<br>- More than 160 characters in the note and message; explore utilizing the notification API for increased number of characters.<br>- The URL posted to needs to reviewed e.g. incorrect number of forward slashes (`///`). |
+| **403** | `FORBIDDEN IP` | Authorization failed. IP not authorized to utilize **Disbursement API**. | Share your originating Public IP from which the APIs are called with your MTN Account Manager. |
+| **500** | `NOT_ALLOWED` | Authorization failed. User does not have permission. The account authenticated with the Request via Token is restricted. | Contact your MTN Account Manager. |
+| **500** | `NOT_ALLOWED_TARGET_ENVIRONMENT` | Value passed in header **X-Target-Environment** is incorrect | Use the correct **X-Target-Environment** corresponding to below country:<br>- MTN Uganda = `mtnuganda`<br>- MTN Ghana = `mtnghana`<br>- MTN Ivory Coast = `mtnivorycoast`<br>- MTN Zambia = `mtnzambia`<br>- MTN Cameroon = `mtncameroon`<br>- MTN Benin = `mtnbenin`<br>- MTN Congo = `mtncongo`<br>- MTN Swaziland = `mtnswaziland`<br>- MTN GuineaConakry = `mtnguineaconakry`<br>- MTN SouthAfrica = `mtnsouthafrica`<br>- MTN Liberia = `mtnliberia`<br><br>For Test Environment = `sandbox` |
+| **500** | `INVALID_CALLBACK_URL_HOST` | Callback URL with different host name to configured for API User. Check the Host of the Call Back URL in the request header; this needs to match what was configured on the partner portal when creating the API user and Key. | Host needs to be configured using **Hostname** and not **IP address**. |
+| **500** | `INVALID_CURRENCY` | Currency not supported on the requested account | Use **Currency Code** specific to the Country. |
+| **503** | `SERVICE_UNAVAILABLE` | Service temporary unavailable, try again later | Enquire with MTN Support. |
+
+### Common Error Responses with Action
+
+| Type | Description | Action |
+|------|-------------|--------|
+| `INTERNAL_PROCESSING_ERROR` | Default or Generic error code used when there is no specific error mapping. This predominantly occurs due to insufficient customer funds to complete the transaction. Also related to service denied or Wallet Platform is not reachable. | Advice customer to ensure they have sufficient funds to complete the transaction. Also request the customer to retry the transaction. If the problem still occurs with sufficient customer funds, please contact your MTN Account Manager for further investigation. |
+| `PAYEE_NOT_FOUND` | The **MSISDN** being paid to is invalid. | **MSISDN** format must include country code. **MSISDN** is not registered for Mobile Money Service. |
+| `PAYER_NOT_FOUND` | **MSISDN** of the number from whom the money was requested in invalid. | **MSISDN** format must include country code. **MSISDN** is not registered for Mobile Money Service. |
+| `COULD_NOT_PERFORM_TRANSACTION` | This can be attributed to transaction timeout. This predominantly occurs with a delay to approve a transaction within the given time frame (5 minutes). | Advise customer to try again and approve transaction within **5 minutes**. |
+
+---

knowledge_base/mtn_momo/mtn_momo_api_faq.md

@@ -0,0 +1,130 @@
+# MoMo API FAQ
+
+## Authentication
+
+### 1. What credentials do I need once I have subscribed to a product?
+
+- **Subscription Key** - received upon subscription to a product. It is used for authenticating the number of API calls. For information about subscription keys, refer to point 2
+- **API User and API Key** for bearer Oauth 2.0 token. In the sandbox they are self-generated from the APIs. In production these are generated from the partner portal (part of onboarding)
+
+### 2. What is a subscription Key?
+
+- This Key is used to authenticate and limit the number of calls that can be made
+- The subscription key is assigned to the **Ocp-Apim-Subscription-Key** parameter of the header
+- The Subscription Key can be found in your user profile
+- Developers - can use either the Primary Key or Secondary Key for every product they subscribe to allow access to the API
+- A developer cannot access or utilize any of the respective APIs without a Subscription Key
+- Different subscription keys can be used for different product APIs; please check in your user profile
+
+### 3. What is the API User and API Key for Oauth 2.0?
+
+- The API User and API Key are used together with your subscription key to grant access to the -wallet system and is applicable to a specific country
+- The API User and API Key are generated using respective APIs in the sandbox
+- API user and Key are wholly managed by the merchant through Partner Portal for PRODUCTION setups
+- Merchants can generate/revoke/refresh API Keys through the Partner Portal
+- For Sandbox API User and Key is generated using an API
+
+### 4. How do I generate an Oauth 2.0 token?
+
+- You require an API User and API Key in format **APIUSER: APIKey** `e16510xx-7282-4a39-xx8b-da054889a33a:xx1894d23a8d4xxdadaf62f39dae99xx`
+- Convert the concatenation of APIUser: APIKey into Base64 format
+- Use the Base64 format to generate the authorization token, the result will look similar to this string `ZTE2NTEwY2xtNzI4Mi00YTx5LTg5OGItZGEwNTQ4ODlhMzNhOjg1MTg5NGQyM2E4ZDQxMW RhZGFmNxJmMzlkYWU5OcY4`
+
+### 5. How do I create, provision and manage the API user and API key?
+
+- Please review Sandbox provisioning process under API Sandbox
+- The API User and API Key are used to grant access to the wallet system applicable to a specific country
+- API user and Key are wholly managed by the merchant through Partner Portal in production
+- Developers can generate or revoke API Keys through the Partner Portal in production
+
+### 6. How do I generate a UUID for my transactions?
+
+- This ID is used, for example, validating the status of the request. 'Universal Unique ID' for the transaction generated using UUID version 4
+- Example of Version 4 UUID: `ca58fd96-2478-4624-b663-bdacd5f914ca`
+
+## Callback
+
+### 7. I am not getting any callbacks. How do I verify or configure my callback URL?
+
+Check that you have:
+
+- Registered a **ProviderCallbackHost** when creating your API User
+- You have specified a callback URL in the Request
+- The Callback URL MUST belong to the same domain as the ProvideCallbackHost. Subdomains are not allowed.
+
+**Example:**
+
+If you have specified your ProviderCallbackHost as `mycallback.com` then the callback URL shall be specified as `https://mycallback.com/`
+
+Using `https://subdomain.mycallback.com/` as callback URL will not work
+
+Callbacks in the sandbox are set by setting the callback host when creating an API user, if my callback URL for traffic is `https://testsite.test.com:1313/api/callback`, the callback host is `testsite.test.com` and the callback host is what is set with the user, but the call back URL is used in every request where a callback is expected
+
+In the production environment, the callback is set in the merchant portal and instructions are sent as part of the onboarding documentation
+
+### Setting up a Callback URL
+
+Transfer and RequestToPay APIs are Asynchronous in MTN MoMo API Platform
+
+When a merchant system sends a POST of either `/transfer`, or `/requesttopay` APIs, the Gateway validates the request and then responds with '202 Accepted'
+
+The transaction is then queued for processing.
+
+Once processed, a callback with the final result of the transaction is sent to the merchant system
+
+In order to receive the callback for your transactions, please consider the following:
+
+#### a) On Sandbox
+
+- Register your callback host by specifying the domain as providerCallbackHost when creating your API Keys. On production this will be done via the Account Portal
+- Specify the callback URL in each of your `/requesttopay` or `/tranfer` POST
+- Use http and not https on sandbox
+- Allow PUT & POST on your callback listener host
+
+#### b) On Production
+
+- After Go-live you will be provided a link to log on to your Accounts Portal
+- You will be required to register you callback host on the portal when creating your API keys as shown below
+- Only https is allowed on production
+- Allow PUT & POST on your callback listener host
+
+**Callback Create API User**
+
+The Wallet Platform will only send the callback once. There is no retry on the callback if the Partner system does not respond. A merchant system can, in cases where a callback was not received , poll for the transaction status as described in the GET method
+
+## Error Code
+
+Transfer is used for transferring money from the provider account to a customer.
+
+### 8. What are the common error codes you may expect?
+
+- The error codes are categorized as follows (**Common Error Codes**, **Preapproval Error Codes**, **RequestToPay Error Codes**, **Transfer Error Codes** and **Validate Account Holder Error Codes**)
+- The API User and API Key are used to grant access to the wallet system applicable to a specific country
+- More information on error codes can be found under the documentation section
+
+## Support
+
+### 9. How do I get support and join the developer community?
+
+- Select the 'contact support' button
+- Select a country from the drop-down list
+- Choose WhatsApp and join the developer group - start chatting
+- Or connect via Skype
+
+## On-Boarding
+
+### 10. What steps do I need to follow go live?
+
+- Select the 'Go-Live' option on portal
+- Select Operating country from predefined list to take products Live in that Operating country
+- Choose a Package and Product set
+- Provide KYC Information for business owner and business details
+- Download, complete and submit KYC documents as well as signed contract
+- Submit documents through the Sandbox Portal for Vetting and Approval
+- Access to the partner portal granted for you to create the API User and API Key
+
+## MoMo API Developer Community
+
+Join the MoMo API Developer LinkedIn community and be the first to learn about APIs, events, and news relevant to you for accurate and deeper understanding of the APIs.
+
+Let's learn, collaborate, and get insights from the developer community to take your business to the next level using MTN MoMo APIs.

knowledge_base/mtn_momo/mtn_momo_api_getting_started.md

@@ -0,0 +1,37 @@
+# MoMo API
+
+## Getting Started
+
+**y'ello**, in this section we'll walk you through getting up and running on our Mobile Money Open API. Here you will:
+
+* Signup For An Account
+* Subscribe To Our Products
+* Manage Your Subscriptions
+* Generate API User and API Key
+
+### 1. Signup For An Account
+
+An account activation link will be sent in an email. The activation link expires within 24 hours of it being sent, and you will need to register for another account.
+
+### 2. Subscribe To Our Products
+
+On the products page on our developer portal you should see 4 items you can subscribe to:
+
+* Collection Widget
+* Collection
+* Remittances
+* Disbursements
+
+Each product will have a brief description, a link to the corresponding documentation and Subscribe button on the Products page.
+
+### 3. Manage Your Subscriptions
+
+Developers are issued a **Primary Key** and **Secondary Key** for every product.
+
+Both primary and secondary Subscription key provides access to the API. Without one of them a developer cannot access any of the APIs. Subscriptions are stored under the user profile and have no expiry.
+
+Here you can view the status of the package, date it started, conduct cancellation or activation actions, and also show or regenerate your Primary Key and Secondary Key
+
+### 4. Generate API User and API Key
+
+You are now almost ready to start we building with our Mobile Money Open API. The next thing we need to do is to Provision the API User and API Key using the Sandbox Provisioning API. We do this in the next section.

knowledge_base/mtn_momo/mtn_momo_api_intro.md

@@ -0,0 +1,14 @@
+# MoMo API
+
+## Introduction
+
+The purpose of this site is to detail the design principles, objects, behaviours and error handling for the MTN Mobile Money API. The overriding goal of the API is to enable all parties to implement MTN Mobile Money APIs in a flexible, yet consistent manner. We hope to achieve this by the implementing the following principles:
+
+* Use of REST architectural principles.
+* Providing a set of well-defined objects that are abstracted from the underlying object representations held in the various mobile money systems. This allows an API client to construct an API message without requiring specific knowledge of the target server implementation.
+* Creation of a standard set of transaction types and other key enumerations, removing the need for developers to map for each and every API implementation.
+* Use of ISO international standards for enumerators such as currency and country codes
+* Use of supplementary metadata and sub-types to enable use case and/or mobile money provider-specific properties to be conveyed where necessary.
+* Recognising that no common mobile money account identifier exists, use of a flexible construct to enable the target account(s) and transaction parties to be identified using one or multiple identifier types.
+
+The Open API is a JSON REST API that is used by Partner systems to access services in the Wallet platform. The Open API exposes services that are used by e.g. online merchants for managing payments and other financial services. This document gives an overview of the structure of the API.

knowledge_base/mtn_momo/mtn_momo_api_sandbox_use_cases.md

@@ -0,0 +1,155 @@
+# MoMo API
+
+## Sandbox Use Cases
+
+To facilitate testing a set of predefined users and Test accounts are provided. These users and accounts have a predefined test scenario. A developer needs to Signup and Subscribe to a Product before accessing any of the APIs.
+
+In order to test Sandbox Use cases, Merchants/Agents/Partners/Testers needs to use the Sandbox Provisioning Collection and generate the apiuser and apikey and the same needs to be used for testing any of the sandbox Use cases. Existing Partner Accounts created on Partner GUI can't be used for testing the sandbox usecases.
+
+## OAuth Token
+
+OAuth Token is generated from the merchants' API Key and Secret. The API Key and API Secret can be obtained through the provisioning API in Sandbox, as described in the API User and API Key Management section.
+
+## Test Environment
+
+The Target Environment used in Testing is **'Sandbox'**
+
+## Test Currency
+
+The currency used in Sandbox is **EUR**
+
+## Sandbox Use Case
+
+The following Numbers are predefined with respective response for all Testcases.
+
+| Sandbox Use Case | Testing Values |
+|------------------|----------------|
+| AccountBalanceResponses | Success, AccountNotFound, ZeroBalance, NegativeBalance, NotAllowed, NotAllowedTargetEnvironment, InternalProcessingError, ServiceUnavailable |
+| AccountHolderActiveMsisdnNotFound | 46733123450 |
+| AccountHolderActiveMsisdnNotActive | 46733123451 |
+| AccountHolderActiveMsisdnNotAllowed | 46733123452 |
+| AccountHolderActiveMsisdnNotAllowedTargetEnvironment | 46733123453 |
+| AccountHolderActiveMsisdnInternalProcessingError | 46733123454 |
+| AccountHolderActiveMsisdnServiceUnavailable | 46733123455 |
+| AccountHolderActiveEmailNotFound | notfound@email.com |
+| AccountHolderActiveEmailNotActive | notactive@email.com |
+| AccountHolderActiveEmailNotAllowed | notallowed@email.com |
+| AccountHolderActiveEmailNotAllowedTargetEnvironment | notallowedtargetenvironment@email.com |
+| AccountHolderActiveEmailInternalProcessingError | internalprocessingerror@email.com |
+| AccountHolderActiveEmailServiceUnavailable | serviceunavailable@email.com |
+| AccountHolderActivePartyCodeNotFound | 5cecb5a7-8bd0-4f49-87b1-8eb9ecc7b7bc |
+| AccountHolderActivePartyCodeNotActive | b0040b3c-b426-4a90-af6e-673e65861cd7 |
+| AccountHolderActivePartyCodeNotAllowed | 4d5f500f-c385-4901-9be5-25b6d36ad220 |
+| AccountHolderActivePartyCodeNotAllowedTargetEnvironment | d2265f9b-0c22-496d-908f-79a65ad66266 |
+| AccountHolderActivePartyCodeInternalProcessingError | 8f548a78-ceb8-4d12-a243-5640b91e91a4 |
+| AccountHolderActivePartyCodeServiceUnavailable | 585c07a4-2c80-42f7-9e73-e586b36dee68 |
+| RequestToPayPayerFailed | 46733123450 |
+| RequestToPayPayerRejected | 46733123451 |
+| RequestToPayPayerExpired | 46733123452 |
+| RequestToPayPayerOngoing | 46733123453 |
+| RequestToPayPayerDelayed | 46733123454 |
+| RequestToPayPayerNotFound | 46733123455 |
+| RequestToPayPayerPayeeNotAllowedToReceive | 46733123456 |
+| RequestToPayPayerNotAllowed | 46733123457 |
+| RequestToPayPayerNotAllowedTargetEnvironment | 46733123458 |
+| RequestToPayPayerInvalidCallbackUrlHost | 46733123459 |
+| RequestToPayPayerInvalidCurrency | 46733123460 |
+| RequestToPayPayerInternalProcessingError | 46733123461 |
+| RequestToPayPayerServiceUnavailable | 46733123462 |
+| RequestToPayPayerCouldNotPerformTransaction | 46733123463 |
+| PreApprovalPayerFailed | 46733123450 |
+| PreApprovalPayerRejected | 46733123451 |
+| PreApprovalPayerExpired | 46733123452 |
+| PreApprovalPayerOngoing | 46733123453 |
+| PreApprovalPayerDelayed | 46733123454 |
+| PreApprovalPayerNotFound | 46733123455 |
+| PreApprovalPayerNotAllowed | 46733123456 |
+| PreApprovalPayerNotAllowedTargetEnvironment | 46733123457 |
+| PreApprovalPayerInvalidCallbackUrlHost | 46733123458 |
+| PreApprovalPayerInvalidCurrency | 46733123459 |
+| PreApprovalPayerInternalProcessingError | 46733123460 |
+| PreApprovalPayerServiceUnavailable | 46733123461 |
+| RequestToWithdrawPayerFailed | 46733123450 |
+| RequestToWithdrawPayerRejected | 46733123451 |
+| RequestToWithdrawPayerExpired | 46733123452 |
+| RequestToWithdrawPayerOngoing | 46733123453 |
+| RequestToWithdrawPayerDelayed | 46733123454 |
+| RequestToWithdrawPayerNotFound | 46733123455 |
+| RequestToWithdrawPayerPayeeNotAllowedToReceive | 46733123456 |
+| RequestToWithdrawPayerNotAllowed | 46733123457 |
+| RequestToWithdrawPayerNotAllowedTargetEnvironment | 46733123458 |
+| RequestToWithdrawPayerInvalidCallbackUrlHost | 46733123459 |
+| RequestToWithdrawPayerInvalidCurrency | 46733123460 |
+| RequestToWithdrawPayerInternalProcessingError | 46733123461 |
+| RequestToWithdrawPayerServiceUnavailable | 46733123462 |
+| RequestToWithdrawPayerCouldNotPerformTransaction | 46733123463 |
+| RefundTransactionNotFound | 1 |
+| RefundTransactionFailed | 2 |
+| RefundTransactionRejected | 3 |
+| RefundTransactionExpired | 4 |
+| RefundTransactionOngoing | 5 |
+| RefundTransactionDelayed | 6 |
+| RefundTransactionNotAllowed | 7 |
+| RefundTransactionNotAllowedTargetEnvironment | 8 |
+| RefundTransactionInvalidCallbackUrlHost | 9 |
+| RefundTransactionInvalidCurrency | 10 |
+| RefundTransactionInternalProcessingError | 11 |
+| RefundTransactionServiceUnavailable | 12 |
+| RefundTransactionCouldNotPerformTransaction | 13 |
+| DepositPayerFailed | 46733123450 |
+| DepositPayerRejected | 46733123451 |
+| DepositPayerExpired | 46733123452 |
+| DepositPayerOngoing | 46733123453 |
+| DepositPayerDelayed | 46733123454 |
+| DepositPayerNotFound | 46733123455 |
+| DepositPayerPayeeNotAllowedToReceive | 46733123456 |
+| DepositPayerNotAllowed | 46733123457 |
+| DepositPayerNotAllowedTargetEnvironment | 46733123458 |
+| DepositPayerInvalidCallbackUrlHost | 46733123459 |
+| DepositPayerInvalidCurrency | 46733123460 |
+| DepositPayerInternalProcessingError | 46733123461 |
+| DepositPayerServiceUnavailable | 46733123462 |
+| DepositPayerCouldNotPerformTransaction | 46733123463 |
+| TransferPayeeFailed | 46733123450 |
+| TransferPayeeRejected | 46733123451 |
+| TransferPayeeExpired | 46733123452 |
+| TransferPayeeOngoing | 46733123453 |
+| TransferPayeeDelayed | 46733123454 |
+| TransferPayeeNotEnoughFunds | 46733123455 |
+| TransferPayeePayerLimitReached | 46733123456 |
+| TransferPayeeNotFound | 46733123457 |
+| TransferPayeeNotAllowed | 46733123458 |
+| TransferPayeeNotAllowedTargetEnvironment | 46733123459 |
+| TransferPayeeInvalidCallbackUrlHost | 46733123460 |
+| TransferPayeeInvalidCurrency | 46733123461 |
+| TransferPayeeInternalProcessingError | 46733123462 |
+| TransferPayeeServiceUnavailable | 46733123463 |
+| Oauth2CustomScopes | all_info |
+| Oauth2AccountHolderNotFound | 46733123450 |
+| Oauth2ConsentRejected | 46733123451 |
+| Oauth2ConsentPending | 46733123452 |
+| Oauth2ConsentExpired | 46733123453 |
+| Oauth2ConsentExpiredRefreshToken | 46733123454 |
+| Oauth2ConsentRevoked | 46733123455 |
+| Oauth2ConsentDeletedScope | 46733123456 |
+| Oauth2ConsentAlreadyUsed | 46733123457 |
+| Oauth2FinancialNoFunds | 46733123458 |
+| Oauth2FinancialPayeeNotFound | 46733123459 |
+| Oauth2FinancialConsentMismatch | 46733123460 |
+| Oauth2FinancialPayerLimitReached | 46733123461 |
+| Oauth2FinancialPayeeNotAllowedToReceive | 46733123462 |
+| CashTransferTransactionNotFound | 1 |
+| CashTransferTransactionFailed | 2 |
+| CashTransferTransactionRejected | 3 |
+| CashTransferTransactionExpired | 4 |
+| CashTransferTransactionPayeeNotFound | 5 |
+| CashTransferTransactionPayeeNotAllowedToReceive | 6 |
+| CashTransferTransactionNotAllowed | 7 |
+| CashTransferTransactionNotAllowedTargetEnvironment | 8 |
+| CashTransferTransactionInvalidCallbackUrlHost | 9 |
+| CashTransferTransactionInvalidCurrency | 10 |
+| CashTransferTransactionInternalProcessingError | 11 |
+| CashTransferTransactionServiceUnavailable | 12 |
+| CashTransferTransactionCouldNotPerformTransaction | 13 |
+
+**Note:** Any other number results in Success

knowledge_base/mtn_momo/mtn_momo_api_use_cases.md

@@ -0,0 +1,161 @@
+# MoMo API
+
+## Use Cases
+
+Select the product of interest and the use case
+
+Follow the APIs as shown. Execute in sequential order.
+
+**Product Set:** Select a Product  
+**Use Case:** Please select a product first
+
+## Request To Pay
+
+Request to Pay service is used for requesting a payment from a customer (Payer). This can be used by e.g. an online web shop to request a payment for a customer. The customer is requested to approve the transaction on the customer client.
+
+### Flow:
+
+1. Customer (Payer) have selected product(s) in the merchant web shop and decided to check out. Customer select to pay with Mobile Money.
+
+2. The provider system collects the account information for the customer e.g. mobile number and calculate the total amount of the products.
+
+3. The provider system sends a request to pay (`POST /requesttopay`) operation to Wallet Platform. This request includes the amount and customer (Payer) account holder number.
+
+4. Wallet Platform will respond with HTTP 202 Accepted to the provider system
+
+5. Provider shall inform the customer that a payment needs to be approved, by giving information on the merchant web page. For example, the merchant could show information that payment is being processed and that customer needs to approve using the own client, e.g. USSD, mobile app.
+
+6. Wallet Platform will process the request so that the customer can approve the payment. The request to pay will be in PENDING state until the customer have approved/Rejected the payment.
+
+7. The Customer (Payer) will use his/her own client to review the payment. Customer can approve or reject the payment.
+
+8. Wallet platform will transfer the funds if the customer approves the payment. Status of the payment is updated to SUCCESSFUL or FAILED.
+
+9. If a callback URL was provided in the `POST /requesttopay` then a callback will be sent once the request to pay have reached a final state (SUCCESSFUL, FAILED). Note the callback will only be sent once. There is no retry.
+
+10. GET request can be used for validating the status of the transaction. GET is used if the partner system has not requested a callback by providing a callback URL or if the callback was not received.
+
+## Pre-Approval
+
+Pre-approval is used to setup an auto debit towards a customer. The Partner can request a pre-approval from the customer. Once the customer has approved then the partner can debit the customer account without authorization from the customer.
+
+The call flow for setting up a pre-approval is like the request to pay use case. The following picture describes the sequence for pre-approval.
+
+### Flow:
+
+1. The Provider sends a `POST /preapproval` request to Wallet platform.
+
+2. Provider shall inform the customer that pre-approval needs to be approved.
+
+3. Customer (Payer) will use the own client to view the pre-approval request. Customer can approve or reject the request.
+
+4. Callback will be sent if a callback URL was provided in the POST request. The callback is sent when the request has reach a final state (Successful, Failed).
+
+5. The Provider can use the GET request to validate the status of the pre-approval.
+
+## Transfer
+
+Transfer is used for transferring money from the provider account to a customer.
+
+The below sequence gives an overview of the flow of the transfer use case.
+
+### Flow:
+
+1. The Provider sends a `POST /transfer` request to Wallet platform.
+
+2. Wallet platform will directly respond to indicate that the request is received and will be processed.
+
+3. Wallet platform will authorize the request to ensure that the transfer is allowed. The funds will be transferred from the provider account to the Payee account provided in the transfer request.
+
+4. Callback will be sent if a callback URL was provided in the POST request. The callback is sent when the request has reach a final state (SUCCESSFUL, FAILED).
+
+5. The Provider can use the GET request to validate the status of the transfer.
+
+## Validate Account Holder
+
+Validate account holder can be used to do a validation if a customer is active and able to receive funds. The use case will only validate that the customer is available and active. It does not validate that a specific amount can be received.
+
+The sequence for the validate account holder is described below.
+
+### Flow:
+
+1. The Partner can send a `GET /accountholder` request to validate is a customer is active. The Partner provides the id of that customer as part of the URL
+
+2. Wallet platform will respond with HTTP 200 if the account holder is active.
+
+## Get Balance
+
+Get balance request is used to check the balance on the default account connected to the API User. The following is the sequence flow for get balance use case.
+
+## Delivery Notification
+
+This service is intended to provide an additional notification to a customer after the completion of a successful financial transaction, by SMS or by email.
+
+Merchants and Service Providers using **PGW** (Partner gateway is an application responsible for connecting API manager to different Wallet instances across all the Opcos) to interact with the Wallet Platform have the capability to send a notification to their customers after completed transaction.
+
+Additional information is sent via SMS and is free text that may contain information that a partner wants to communicate for example, delivery notification reference number, a lottery number, a booking number, ticket id etc.
+
+The channel used to send the notification will be determined based on what identity was used to initiate original transaction/payment.
+
+The time window during which partner can use additional notification is configured in Partner Gateway.
+
+## Validate Consumer Identity
+
+The Validate Consumer Identity use case (**KYC as a service**) enables a partner to retrieve (limited) customer KYC information with their consent. Upon request by the service provider, the customer will authorize, authenticate and provide consent to get detailed information.
+
+The Partner will receive a short-lived token to fetch detailed information of the customer from the wallet platform.
+
+The basic information that can be retrieved by default is Profile: Name, Gender, Date of birth, locale etc.
+
+API: **GetBasicUserinfo** can be used to either validate for example, Consumer's age or name.
+
+The use case will return limited information about the Consumer that can be used to pre-populate fields, validate the Consumer's age or use it for remittance or sanctions screening purposes.
+
+## Get Consumer Information with Consent
+
+This use case (**Authentication as a Service**) is used to validate/authenticate customer information, by way of a service provider sending a request to the wallet platform, with or without customer consent. The consumer will authenticate via authorization service, and if required, the consumer will be required to provide consent. The scope is to validate or retrieve customer information.
+
+This use case will also enable a partner to obtain consent, or digitally accept terms and conditions. This can be seen as a "digital signature" (where a partner requires this).
+
+A partner may also be able to fetch limited user info without requiring customer consent. This will also enable partners to record and review that a customer has accepted the terms of a contract (amongst other use cases).
+
+This will be used as a base when any token based "as a service" is required.
+
+API: **bc-authorize**.
+
+It provides the Partner with the ability to fetch detailed information about a Consumer, after the Consumer has given the Partner consent for the retrieval of said information:
+
+## Token Based API Authorization
+
+Token based API authorization is required to support consent management for different services. The Partner will request consent from the consumer for certain financial and non-financial transactions, and this will remain valid until the account holder revokes the consent.
+
+The functionalities that can be enhanced by using consent will be:
+
+1. Transfer
+2. Payment
+3. Merchant payment
+4. Transfer to any bank account
+
+For partners, this will enable them to view the status of the transactions for which consent was given using the related parameters. For account holders, they can revoke the consent from any service at their will.
+
+Business benefit of consent can be improved customer experience. Consent can be configured for a specific time and there will be no need to get consent for each transaction. Providing better control on what services are being allowed by the account holder for consent etc.
+
+## Transfer with Consumer Consent
+
+Gives the partner the ability to transfer money on behalf of a consumer, after the consumer has given the partner consent to do so.
+
+## Merchant Payment with Consumer Consent
+
+Gives the Merchant System (partner) the possibility to perform a merchant payment on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.
+
+## Payment with Consumer Consent
+
+Gives the Merchant System (partner) the possibility to perform a payment on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.
+
+Payment with consent will be similar to Merchant Payment. For more details, Please refer above section- "Merchant Payment with Consumer Consent".
+
+## Bank Transfer with Consumer Consent
+
+Gives the Merchant System (partner) the possibility to perform a Bank Transfer on behalf of a consumer to any receiver. This will only be possible after the Consumer has given the Merchant System (partner) a consent for doing so.
+
+Bank transfer with consent will be similar to Transfer with Consent. For more details, Please refer above section- "Transfer with Consumer Consent".

knowledge_base/mtn_momo/mtn_momo_api_user_and_key_management.md

@@ -0,0 +1,162 @@
+# MoMo API Documentation
+
+## API User and Key Management
+
+### Authentication
+
+There are two credentials used in the Open API:
+
+1. **Subscription Key**
+2. **API User and API Key**
+
+The subscription key is used to give access to APIs in the API Manager portal. A user is assigned a subscription key when the user subscribes to products in the API Manager Portal.
+
+The API User and API Key are used to grant access to the wallet system in a specific country. API user and Key are wholly managed by the user through Partner Portal.
+
+Users are allowed to generate/revoke API Keys through the Partner Portal.
+
+However, on Sandbox Environment a Provisioning API is exposed to enable users to generate their own API User and API Key for testing purposes only.
+
+### Subscription Key
+
+The subscription key is part of the header of all requests sent to the API Manager. The subscription key can be found under user profile in the API Manager Portal.
+
+The subscription key is assigned to the `Ocp-Apim-Subscription-Key` parameter of the header.
+
+### API User and API Key for OAuth 2.0
+
+The API user and API key are provisioned differently in the sandbox and production environment.
+
+In the Sandbox a provisioning API is used to create the API User and API Key, whereas in the production environment the provisioning is done through the User Portal.
+
+The sections below describe the different steps required in creating API User and API key in Sandbox and Production Environments.
+
+## Create API User
+
+1. The Provider sends a `POST {baseURL}/apiuser` request to Wallet platform.
+2. The Provider specifies the UUID Reference ID in the request Header and the subscription Key
+3. Reference ID will be used as the User ID for the API user to be created.
+4. Wallet Platform creates the User and responds with 201
+
+### Example
+
+**Request**
+```http
+POST {baseURL}/apiuser HTTP/1.1
+Host: momodeveloper.mtn.com
+X-Reference-Id: c72025f5-5cd1-4630-99e4-8ba4722fad56
+Ocp-Apim-Subscription-Key: d484a1f0d34f4301916d0f2c9e9106a2
+
+{
+  "providerCallbackHost": "clinic.com"
+}
+```
+
+**Response**
+```http
+201 Created
+```
+
+## Create API Key
+
+1. The Provider sends a `POST {baseURL}/apiuser/{APIUser}/apikey` request to Wallet platform.
+2. The Provider specifies the API User in the URL and subscription Key in the header.
+3. Wallet Platform creates the API Key and responds with 201 Created with the newly Created API Key in the Body.
+4. Provider now has both API User and API Key created.
+
+### Example
+
+**Request**
+```http
+POST {baseURL}/apiuser/c72025f5-5cd1-4630-99e4-8ba4722fad56/apikey HTTP/1.1
+Host: momodeveloper.mtn.com
+Ocp-Apim-Subscription-Key: d484a1f0d34f4301916d0f2c9e9106a2
+```
+
+**Response**
+```http
+HTTP/1.1 201 Created
+Date: Wed, 10 Oct 2018 09:16:15 GMT
+Content-Type: application/json;charset=utf-8
+Content-Length: 45
+
+{
+  "apiKey": "f1db798c98df4bcf83b538175893bbf0"
+}
+```
+
+## GET API User Details
+
+It is possible to fetch API user details such as Call Back Host. However, it is not possible to fetch the API key. Provider shall be required to generate a new Key should they lose the existing one.
+
+1. The Provider sends a `GET {baseURL}/apiuser/{APIUser}` request to Wallet platform.
+2. The Provider specifies the API User in the URL and subscription Key in the header.
+3. Wallet Platform responds with 200 OK and details of the user.
+
+**Note:** TargetEnvironment is preconfigured to sandbox in the Sandbox environment, therefore Providers will not have the option of setting it to a different parameter.
+
+### Example
+
+**Request**
+```http
+GET {baseURL}/apiuser/c72025f5-5cd1-4630-99e4-8ba4722fad56
+Host: momodeveloper.mtn.com
+Ocp-Apim-Subscription-Key: d484a1f0d34f4301916d0f2c9e9106a2
+```
+
+**Response**
+```http
+HTTP/1.1 200 Accepted
+Date: Wed, 10 Oct 2018 09:16:15 GMT
+
+{
+  "providerCallbackHost": "clinic.com",
+  "targetEnvironment": "sandbox"
+}
+```
+
+## OAuth 2.0
+
+The Open API uses OAuth 2.0 token for authentication of request. User will request an access token using Client Credential Grant according to RFC 6749. The token received is according to RFC 6750 Bearer Token.
+
+The API user and API key are used in the basic authentication header when requesting the access token. The API user and key are managed in the Partner GUI for the country where the account is located. The Partner can create and manage API user and key from the Partner GUI.
+
+In the Sandbox, the API Key and API User are managed through the Provisioning API.
+
+The received token has an expiry time. The same token can be used for transactions until it expires. A new token is requested by using the `POST /token` service in the same way as the initial token. The new token can be requested for before the previous one has expired to avoid authentication failure due to expired token.
+
+**Important:** The token must be treated as a credential and kept secret. The party that have access to the token will be authenticated as the user that requested the token.
+
+### Authentication Flow
+
+The below sequence describes the flow for requesting a token and using the token in a request:
+
+1. Provider system requests an access token using the API Key and API user as authentication.
+2. Wallet platform authenticates credentials and responds with the access token
+3. Provider system will use the access token for any request that is sent to Wallet Platform, e.g. `POST /requesttopay`
+
+**Note:** The same token shall be used if it is not expired.
+
+## API Methods
+
+The API uses POST, GET, PUT methods. This section gives an overview of the interaction sequence used in the API and the usage of the methods.
+
+### POST
+
+POST method is used for creating a resource in Wallet Platform. The request includes a reference id which is used to uniquely identify the specific resource that are created by the POST request. If a POST is using a reference id that is already used, then a duplication error response will be sent to the client.
+
+**Example:** `POST /requesttopay`
+
+The POST is an asynchronous method. The Wallet Platform will validate the request to ensure that it is correct according to the API specification and then answer with HTTP 202 Accepted. The created resource will get status PENDING. Once the request has been processed the status will be updated to SUCCESSFUL or FAILED. The requester may then be notified of the final status through callback.
+
+### GET
+
+GET is used for requesting information about a specific resource. The URL in the GET shall include the reference of the resource. If a resource was created with POST then the reference id that was provided in the request is used as the identity of the resource.
+
+**Example:**
+- `POST /requesttopay` request is sent with `X-Reference-Id = 11377cbe-374c-43f6-a019-4fb70e57b617`
+- `GET /requesttopay/11377cbe-374c-43f6-a019-4fb70e57b617` will return the status of the request.
+
+### PUT
+
+The PUT method is used by the Open API when sending callbacks. Callback is sent if a callback URL is included in the POST request. The Wallet Platform will only send the callback once. There is no retry on the callback if the Partner system does not respond. If the callback is not received, then the Partner system can use GET to validate the status.

knowledge_base/mtn_momo/mtn_momo_error_codes.md

@@ -0,0 +1,72 @@
+# Error Codes
+
+MoMo OpenAPI Team is thrilled to announce that we've been listening to your feedback, and as a result, we've made significant updates to improve the failure handling with MoMoOpenAPI experience for developers, businesses, and customers.
+
+## Improved Failure Reasons and Error Codes
+
+In our ongoing effort to provide a seamless and intuitive experience, we've revamped our failure reasons and error codes. These updates ensure that error messages are clearer, more concise, and provide actionable insights. This enhancement enables developers and businesses to quickly identify and resolve issues, reducing friction and improving overall efficiency.
+
+## Benefits for all
+
+These updates bring numerous benefits to the MoMoOpenAPI ecosystem, including:
+
+1. **Enhanced Customer Experience:** Improved failure reasons and new actions lead to better, more seamless customer experiences.
+2. **Increased Efficiency:** Developers and businesses can now manage MoMo customer experiences more efficiently, reducing time and resources spent on issue resolution.
+3. **Reduced Friction:** Updated error codes and messages reduce friction, making it easier to resolve issues and get back to business as usual.
+
+## Common Error Codes
+
+### NOT_ENOUGH_FUNDS
+**Description:** The payer does not have enough funds.
+
+**Action:** Notify the payer of the total amount with fees before initiating debit, and also to ensure availability of the MoMo funds
+
+### PAYER_NOT_FOUND
+**Description:** Payer does not exist
+
+**Action:** Before initiating debit, use the Get accountholder Status to confirm the payer has an active MoMo Wallet
+
+### TRANSACTION_NOT_FOUND
+**Description:** The transaction could not be found
+
+**Action:** The transaction could not be found
+
+### PAYEE_NOT_ALLOWED_TO_RECEIVE
+**Description:** The payee is unable to receive funds.
+
+**Action:** The payee is unable to receive funds, due to a non active wallet status. If encountered request customer for an alternative MoMo number.
+
+### SENDER_ACCOUNT_NOT_ACTIVE
+**Description:** SENDER ACCOUNT NOT ACTIVE
+
+**Action:** The MoMo wallet used for the transfer has not been activated. Please contact your account manager in your respective country to activate the wallet for transactions
+
+### COULD_NOT_PERFORM_TRANSACTION
+**Description:** Transaction Not Completed
+
+**Action:** Debit transactions have a 5-minute approval window. If the transaction times out, please retry the transaction to complete the debit
+
+### PAYER_LIMIT_REACHED
+**Description:** The payer's limit has been breached.
+
+**Action:** Customer's wallet has reached its set limits for debits, which vary by country. To resolve this, the customer must either reduce the debit amount or use another MoMo wallet
+
+### PAYEE_LIMIT_REACHED
+**Description:** The payee's limit has been breached.
+
+**Action:** Customer's wallet has reached its set limits for transfers, which vary by country. To resolve this, the customer must either reduce the transfer amount or share another MoMo wallet
+
+### RESOURCE_ALREADY_EXIST
+**Description:** Duplicated reference id. Creation of resource failed.
+
+**Action:** Error implies that the X-Reference-Id header in your financial API POST request is duplicated To resolve this issue, you need to ensure that each financial API POST request has a unique X-Reference-Id header in UUID Version 4 format.
+
+### PAYEE_NOT_FOUND
+**Description:** Payee does not active
+
+**Action:** Error generated for Debit requests when the business account is blocked
+
+### VALIDATION_ERROR
+**Description:** Request failing Validation
+
+**Action:** Validation failures can occur due to incorrect data types, unsupported decimals, empty fields, incorrect field lengths, unsupported currencies, and invalid payer messages or notes (which cannot be null and must be within 128 characters).

knowledge_base/mtn_momo/mtn_momo_open_apis_ sandbox_documentation.md

@@ -0,0 +1,1358 @@
+# MoMo Open APIs SandBox Documentation
+
+MTN MoMo Open APIs are a set of APIs that allow third-party developers to create innovative digital financial services using MTN Mobile Money platform.
+
+These APIs facilitate all key use cases including consumer to business payments (C2B), business to business payments (B2B), collections, and disbursements, Cash In, Cash Out, Refund, Notification and more.
+
+MoMo APIs are completely RESTful and all our responses are returned in JSON.
+
+## Generate Subscription Keys
+
+1. Sign up at https://momodeveloper.mtn.com
+2. Navigate to the products page Product-descriptions
+3. Select drop down on product that suits the business case and subscribe
+4. After completion, you can locate the Subscription Keys in your profile
+
+**Configure the Environment variables as shown below**
+
+| Subscription name | Key Type | Variable |
+|------------------|----------|----------|
+| Disbursements | Primary | {{Disbursement_Subscription-Key}} |
+| Collections | Primary | {{Collection_Subscription-Key}} |
+
+## Fork the MoMo Open API Postman Collection
+
+Ensure the Environment is set to sandbox before running the collection.
+
+The Collections and Folders have been configured with basic testing scripts to help narrow down the error scope.
+
+## Generate API User and Key SandBox
+
+Run the below request to generate API user and Key. These will be auto saved within the environment leveraging on scripting.
+
+## Test MSISDN Numbers
+
+In the Sandbox, adjust the Test Numbers(MSISDN) within the sandbox environment as follows.
+
+Each numeric string yields a distinct response status within the Sandbox.
+
+For Production, Number begins with the country code.
+
+| Number - {{MSISDN}} | Expected Status Response |
+|---------------------|-------------------------|
+| 46733123450 | Failed |
+| 46733123451 | Rejected |
+| 46733123452 | Timeout |
+| 56733123453 | Success |
+| 46733123454 | Pending |
+
+## Authorization
+
+Consists of Bearer Access Token API, This is also saved within the environment, will refresh once its time has expired, 60 minutes.
+
+### Generate access_token
+
+**Endpoint:** `POST {{base_url}}/collection/token/`
+
+The POST /collection/token/ endpoint is used to obtain a token.
+
+**Request Body**
+No request body parameters required for this request.
+
+**Response**
+Upon a successful request, the response will be a JSON object with the following properties:
+
+- **access_token** (string): The access token obtained
+- **token_type** (string): The type of token obtained
+- **expires_in** (integer): The duration in seconds for which the token is valid
+
+**Headers**
+No specific headers are required for this request.
+
+**Example response:**
+
+```json
+{
+  "access_token": "",
+  "token_type": "",
+  "expires_in": 0
+}
+```
+
+**Authorization**
+- Basic Auth
+- Username: `{{api_user}}`
+- Password: `{{api_key}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff --request POST '{{base_url}}/collection/token/' \
+--header 'Ocp-Apim-Subscription-Key: {{Collection_Subscription-Key}}' \
+--data ''
+```
+
+**Example Response**
+
+```json
+{
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0.eyJjbGllbnRJZCI6IjA0ZGIwYjk5LTkyNmYtNGQ0Ni04YzI3LTQ2OWIwMmMxZWUxMyIsImV4cGlyZXMiOiIyMDI0LTEwLTA4VDIxOjI1OjI3LjgwNyIsInNlc3Npb25JZCI6IjVhODkwODJlLTk3NmQtNGYwMy04OTNjLTJlNTEwNWI1YWM5NiJ9.hAmAJFZkdyhuEEWGgdZZUtO5hYzIcigV-Sjrhv_zsmTBRu8X8Dhs5Zssr-mulwSaDjITcKRlCna1Eej5kJNQUYeLDDB5pKK5Xx3T3eFxNLrTNvGABMENfoWZgmlLnBgg_ux9bmm4XcncNL5pb_cpEgCZKVpv-SJh2dTtY8Q-QutUDNDG34m-ifMcwicK59RiGsF8fNPKy44wX_BJhqwrg80FYEhOhrqJhzVqSSLb807yIQkx5fNFy8ekzrR2toGusQBsAVwz06g3xaDVMGXBz7mmB35gCP_NQscIGSjtFXTNeItM-HJzTU7TDBzbMDMuRaI2DU1mb7Dt30z8D2NNrw",
+    "token_type": "access_token",
+    "expires_in": 3600
+}
+```
+
+## Get Paid
+
+MoMo get paid APIs enable businesses to collect payments from consumers and businesses in different ways.
+Partners initiate instant payment within any digital platform (website, mobile application) through MoMo channels.
+Folder also includes a set of capabilities that enhance value and offer an excellent customer experience. These include: Refund, Notification.
+
+### Request To Pay
+
+**Endpoint:** `POST {{base_url}}/collection/v1_0/requesttopay`
+
+Create Request To Pay - This endpoint allows the client to initiate a request to pay.
+
+**Request Body**
+- **amount** (string): The amount to be requested
+- **currency** (string): The currency in which the amount is requested
+- **externalId** (string): The unique identifier for the request
+- **payer** (object):
+  - **partyIdType** (string): The type of party ID for the payer (MSISDN/ALIAS/EMAIL)
+  - **partyId** (string): The ID of the payer
+- **payerMessage** (string): Message from the payer
+- **payeeNote** (string): Note for the payee
+
+**Request Body Example**
+
+```json
+{
+  "amount": "600",
+  "currency": "EUR",
+  "externalId": "00004335",
+  "payer": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerMessage": "MoMo Market Payment",
+  "payeeNote": "MoMo Market Payment"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay' \
+--header 'X-Reference-Id: 2f209631-07d4-4254-8d6a-bd0f1ef78538' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--data '{
+  "amount": "600",
+  "currency": "EUR",
+  "externalId": "00004335",
+  "payer": {
+    "partyIdType": "MSISDN",
+    "partyId": "56733123450"
+  },
+  "payerMessage": "MoMo Market Payment",
+  "payeeNote": "MoMo Market Payment"
+}'
+```
+
+### Status Request To Pay
+
+**Endpoint:** `GET {{base_url}}/collection/v1_0/requesttopay/:Request_ID_Debit`
+
+Retrieve Request To Pay Response - This endpoint retrieves the response for a specific request to pay, identified by the unique Request_ID_Debit.
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Debit**: `{{Request_ID_Debit}}` - Request Id of the debit request Posted
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay/2f209631-07d4-4254-8d6a-bd0f1ef78538' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1'
+```
+
+### Notification
+
+**Endpoint:** `POST {{base_url}}/collection/v1_0/requesttopay/{{Request_ID_Debit}}/deliverynotification`
+
+This endpoint is used to send a delivery notification for a specific request to pay.
+
+**Request Body**
+- **notificationMessage**: (string) The message for the delivery notification
+
+**Request Body Example**
+
+```json
+{
+  "notificationMessage": "Thank You for using MoMo"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttopay/2f209631-07d4-4254-8d6a-bd0f1ef78538/deliverynotification' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1' \
+--data '{
+  "notificationMessage": "Thank You for using MoMo"
+}'
+```
+
+### Refund
+
+**Endpoint:** `POST {{base_url}}/disbursement/v1_0/refund`
+
+Refund Disbursement - This endpoint allows the user to initiate a refund for a previous disbursement.
+
+**Request Body**
+- **amount** (string): The amount to be refunded
+- **currency** (string): The currency in which the refund amount is specified
+- **externalId** (string): The external identifier for the refund transaction
+- **payerMessage** (string): Message to be displayed to the payer (optional)
+- **payeeNote** (string): Note to be displayed to the payee (optional)
+- **referenceIdToRefund** (string): The reference ID of the disbursement to be refunded
+
+**Request Body Example**
+
+```json
+{
+  "amount": "300",
+  "currency": "EUR",
+  "externalId": "Refund_uibi",
+  "payerMessage": "Refund for MoMo Market Payment",
+  "payeeNote": "Refund for MoMo Market Payment",
+  "referenceIdToRefund": "{{Request_ID_Debit}}"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/refund' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--header 'X-Reference-Id: 85c66b88-abb8-4523-a81d-2d5566816c70' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc' \
+--data '{
+  "amount": "300",
+  "currency": "EUR",
+  "externalId": "Refund_uibi",
+  "payerMessage": "Refund for MoMo Market Payment",
+  "payeeNote": "Refund for MoMo Market Payment",
+  "referenceIdToRefund": "2f209631-07d4-4254-8d6a-bd0f1ef78538"
+}'
+```
+
+### Refund Status
+
+**Endpoint:** `GET {{base_url}}/disbursement/v1_0/refund/:Request_ID_Refund`
+
+This endpoint is used to check the status of a refund by providing the Request_ID_Refund, which is also mapped as the X-Reference-Id in the Refund Request.
+
+**Headers**
+- **X-Target-Environment** (string, required): The identifier specifying the country the request is meant for
+- **Ocp-Apim-Subscription-Key** (string, required): Subscription key providing access to this API
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Refund**: `{{Request_ID_Refund}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/refund/85c66b88-abb8-4523-a81d-2d5566816c70' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc'
+```
+
+## Payment
+
+Payment API enables a Business to streamline utility payments and initiate services like airtime and bundle activation through MoMo.
+
+### Create Payment
+
+**Endpoint:** `POST https://sandbox.momodeveloper.mtn.com/collection/v2_0/payment`
+
+This API endpoint is used to initiate a payment collection.
+
+**Request Body**
+- **externalTransactionId** (text): The ID of the external transaction
+- **money.amount** (text): The amount of the payment
+- **money.currency** (text): The currency of the payment
+- **customerReference** (text): Reference to the customer initiating the payment
+- **serviceProviderUserName** (text): Username of the service provider
+- **couponId** (text): ID of the coupon, if applicable
+- **productId** (text): ID of the product
+- **productOfferingId** (text): ID of the product offering
+- **receiverMessage** (text): Message for the receiver of the payment
+- **senderNote** (text): Note from the sender of the payment
+- **maxNumberOfRetries** (text): Maximum number of retries for the payment
+- **includeSenderCharges** (text): Indicator whether to include sender charges
+
+**Request Body Example**
+
+```json
+{
+  "externalTransactionId": "457373",
+  "money": {
+    "amount": "2000",
+    "currency": "EUR"
+  },
+  "customerReference": "561551442",
+  "serviceProviderUserName": "WaterProvider",
+  "couponId": "203",
+  "productId": "Monthly Payments",
+  "productOfferingId": "788",
+  "receiverMessage": "Thank You ",
+  "senderNote": "Thank You",
+  "maxNumberOfRetries": "2",
+  "includeSenderCharges": "1"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v2_0/payment' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--header 'X-Reference-Id;' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1' \
+--data '{
+  "externalTransactionId": "457373",
+  "money": {
+    "amount": "2000",
+    "currency": "EUR"
+  },
+  "customerReference": "561551442",
+  "serviceProviderUserName": "WaterProvider",
+  "couponId": "203",
+  "productId": "Monthly Payments",
+  "productOfferingId": "788",
+  "receiverMessage": "Thank You ",
+  "senderNote": "Thank You",
+  "maxNumberOfRetries": "2",
+  "includeSenderCharges": "1"
+}'
+```
+
+### Get Payment Status
+
+**Endpoint:** `GET https://sandbox.momodeveloper.mtn.com/collection/v2_0/payment/:Request_ID_Payment`
+
+Retrieve Payment Response - This endpoint retrieves the response for a specific payment request identified by the provided Request ID.
+
+**Response**
+
+```json
+{
+    "referenceId":"",
+    "status":"",
+    "reason":""
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Payment**: `{{Request_ID_Payment}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v2_0/payment/:Request_ID_Payment' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1'
+```
+
+## Pay
+
+MoMo PAY APIs enable businesses to disburse payments to other consumers or businesses. This can be used in the context of salary payment, benefits disbursements and any other pay out. It can also be used to pay other business (suppliers).
+
+PAY APIs utilize the Disbursement Subscription Keys.
+
+### Transfer
+
+Make MoMo Transfer from Your Business to Other Business, Customers, Employees in the context of salary, bet winnings, Service Payments.
+
+The MoMo Transfer API accommodates one MSISDN/ALIAS per request, and not bulk.
+
+**Business to Business Payments** by using their Merchant ID:
+
+```json
+{
+  "amount": "5900",
+  "currency": "EUR",
+  "externalId": "890695",
+  "payee": {
+    "partyIdType": "ALIAS",
+    "partyId": "678997678"
+  },
+  "payerMessage": "Salary Payment April 2023",
+  "payeeNote": "Salary Payment April 2023"
+}
+```
+
+**Business to Customer/Employee Payments** by using their MSISDN with country code:
+
+```json
+{
+  "amount": "5900",
+  "currency": "EUR",
+  "externalId": "890695",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "2567524561"
+  },
+  "payerMessage": "Salary Payment April 2023",
+  "payeeNote": "Salary Payment April 2023"
+}
+```
+
+**Endpoint:** `POST {{base_url}}/disbursement/v1_0/transfer`
+
+**Request Body**
+- **amount** (string): The amount to be transferred
+- **currency** (string): The currency in which the amount is specified
+- **externalId** (string): An ID to uniquely identify the transfer
+- **payee** (object): Information about the payee
+  - **partyIdType** (string): Type of ID for the payee
+  - **partyId** (string): ID of the payee
+- **payerMessage** (string): Message from the payer
+- **payeeNote** (string): Note for the payee
+
+**Request Body Example**
+
+```json
+{
+  "amount": "5900",
+  "currency": "EUR",
+  "externalId": "890695",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerMessage": "Salary Payment April 2023",
+  "payeeNote": "Salary Payment April 2023"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/transfer' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--header 'X-Reference-Id: 1077fbc2-9253-437f-883c-30e248bc635d' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc' \
+--data '{
+  "amount": "5900",
+  "currency": "EUR",
+  "externalId": "890695",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "56733123455"
+  },
+  "payerMessage": "Salary Payment April 2023",
+  "payeeNote": "Salary Payment April 2023"
+}'
+```
+
+### Transfer Status
+
+**Endpoint:** `GET https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/transfer/:Request_ID_Transfer`
+
+This endpoint makes an HTTP GET request to retrieve information about a specific transfer identified by the provided Request ID.
+
+**Response Body**
+The response includes the following fields in JSON format:
+- **amount**: The amount of the transfer
+- **currency**: The currency used for the transfer
+- **financialTransactionId**: The financial transaction ID associated with the transfer
+- **externalId**: The external ID associated with the transfer
+- **payee**: An object containing information about the payee, including party ID type and party ID
+- **payerMessage**: The message from the payer associated with the transfer
+- **payeeNote**: The note from the payee associated with the transfer
+- **status**: The status of the transfer
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Transfer**: `{{Request_ID_Transfer}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/transfer/1077fbc2-9253-437f-883c-30e248bc635d' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc'
+```
+
+## Account Validation
+
+To avoid Debiting Or Transferring invalid / Wrong MoMo Accounts, good practice to validate them and confirm ownership. Get Names and KYC and Account Status (Active- True, Inactive-False).
+
+### Validation No Consent
+
+API Folder containing APIs that can be validated without requiring customer consent.
+
+#### Check Account Holder
+
+Check Account Holder API - This API provides information on whether an account has a MoMo wallet or not. It returns either true or false.
+
+**Endpoint:** `GET {{base_url}}/disbursement/v1_0/accountholder/msisdn/:MSISDN/active`
+
+Retrieve Active Account Holder by MSISDN - This endpoint makes an HTTP GET request to retrieve the active account holder by MSISDN.
+
+**URL Parameters**
+- **MSISDN** (required, string): The mobile number for which the active account holder information is to be retrieved
+
+**Response**
+The response will be in JSON format and will contain the following key:
+- **result** (boolean): Indicates whether the account holder is active or not
+
+**Example response:**
+
+```json
+{
+    "result": true
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **MSISDN**: `{{MSISDN}}`
+
+#### Get Basic Info (MSISDN)
+
+Get Basic Info (MSISDN) API - This API retrieves the first and last names of the MoMo wallet owner. If the wallet does not exist, it returns an error message stating "Not Found".
+
+**Endpoint:** `GET {{base_url}}/remittance/v1_0/accountholder/msisdn/:MSISDN/basicuserinfo`
+
+This endpoint retrieves basic user information for the account holder associated with the provided MSISDN (Mobile Station International Subscriber Directory Number).
+
+**Headers**
+- **Authorization** (Bearer Token): The request is authenticated using a Bearer Token
+- **X-Target-Environment**: The identifier on the API Request specifying which country the request is to be processed for production
+- **Ocp-Apim-Subscription-Key**: Subscription key which provides access to the APIM
+
+**Path Parameter**
+- **MSISDN**: The Mobile Station International Subscriber Directory Number for which the basic user information is to be retrieved
+
+**Response**
+Upon successful execution, the response will have a status code of 200 and a JSON object with the following fields:
+
+```json
+{
+  "sub": "",
+  "name": "",
+  "given_name": "",
+  "family_name": "",
+  "birthdate": "",
+  "locale": "",
+  "gender": "",
+  "updated_at": 0
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **MSISDN**: `{{MSISDN}}`
+
+#### Get Basic Info (Alias)
+
+Get Basic Info (Alias) API - This API retrieves the first and last names of the MoMo wallet owner using an Alias (Business Merchant ID). If the wallet does not exist, it returns an error message stating "Not Found".
+
+**Endpoint:** `GET {{base_url}}/disbursement/v1_0/accountholder/Alias/:MSISDN/basicuserinfo`
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **MSISDN**: `{{MSISDN}}`
+
+### Detailed KYC - With Consent
+
+KYC With Consent APIs, Used to obtain Consent from the Customer to access their KYC information, like National ID, Date of Birth.
+
+#### bc-authorize
+
+**Endpoint:** `POST {{base_url}}/disbursement/v1_0/bc-authorize`
+
+This endpoint allows you to make an HTTP POST request to authorize a disbursement.
+
+**Request Body**
+The request should include the following parameters in x-www-form-urlencoded format:
+- **scope**: all_info
+- **login_hint**: ID:563667/MSISDN
+- **access_type**: offline
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/bc-authorize' \
+--header 'X-Target-Environment: sandbox' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc' \
+--data-urlencode 'scope=all_info' \
+--data-urlencode 'login_hint=ID:563667/MSISDN' \
+--data-urlencode 'access_type=offline'
+```
+
+#### Generate Oauth2 Token
+
+**Endpoint:** `POST {{base_url}}/disbursement/oauth2/token/`
+
+This endpoint allows the client to obtain an OAuth2 token for disbursement.
+
+**Response JSON Schema**
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "access_token": {
+      "type": "string"
+    },
+    "token_type": {
+      "type": "string"
+    },
+    "expires_in": {
+      "type": "integer"
+    },
+    "scope": {
+      "type": "string"
+    }
+  }
+}
+```
+
+**Authorization**
+- Basic Auth
+- Username: `{{api_user}}`
+- Password: `{{api_key}}`
+
+**Request Body**
+- **grant_type**: urn:openid:params:grant-type:ciba
+- **auth_req_id**: `{{Consent_Req_Id}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/oauth2/token/' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc' \
+--data-urlencode 'grant_type=urn:openid:params:grant-type:ciba' \
+--data-urlencode 'auth_req_id=010001b2-5c84-4dd1-9eaf-56d5668dabd3'
+```
+
+#### Get UserInfo
+
+**Endpoint:** `GET {{base_url}}/disbursement/oauth2/v1_0/userinfo`
+
+This endpoint is used to retrieve user information via an HTTP GET request.
+
+**Authorization**
+- Bearer Token: `{{Oauth2_Token}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/disbursement/oauth2/v1_0/userinfo' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Ocp-Apim-Subscription-Key: {{Disbursement_Subscription-Key}}'
+```
+
+## Distribute
+
+MoMo Open APIs enable business to distribute MTN and MoMo service and facilitate Cash In, Cash out and Airtime sale and get commission from MTN and MoMo.
+
+Folder contains Cash In APIs and Cash Out.
+
+### Cash IN
+
+#### Deposit Request
+
+**Endpoint:** `POST https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/deposit`
+
+Deposit Disbursement - This endpoint allows you to initiate a deposit disbursement.
+
+**Request Body**
+- **amount** (string): The amount to be deposited
+- **currency** (string): The currency of the amount
+- **externalId** (string): Your unique identifier for this transaction
+- **payee.partyIdType** (string): The type of the party ID
+- **payee.partyId** (string): The ID of the party to receive the deposit
+- **payerMessage** (string): Message from the payer
+- **payeeNote** (string): Note to the payee
+
+**Request Body Example**
+
+```json
+{
+  "amount": "2679",
+  "currency": "EUR",
+  "externalId": "004504",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerMessage": "MoMo CASH IN Thank You",
+  "payeeNote": "MoMo CASH IN Thank You"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/deposit' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--header 'X-Reference-Id;' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc' \
+--data '{
+  "amount": "2679",
+  "currency": "EUR",
+  "externalId": "004504",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "56733123455"
+  },
+  "payerMessage": "MoMo CASH IN Thank You",
+  "payeeNote": "MoMo CASH IN Thank You"
+}'
+```
+
+#### Deposit Request Status
+
+**Endpoint:** `GET {{base_url}}/disbursement/v1_0/deposit/:Request_ID_CashIn`
+
+This API endpoint makes an HTTP GET request to retrieve the details of a specific deposit identified by the Request_ID_CashIn in the URL.
+
+**Response**
+
+```json
+{
+    "externalId":"",
+    "amount":"",
+    "currency":"",
+    "payee":{
+        "partyIdType":"",
+        "partyId":""
+    },
+    "payerMessage":"",
+    "payeeNote":"",
+    "status":""
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_CashIn**: `{{Request_ID_CashIn}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/disbursement/v1_0/deposit/:Request_ID_CashIn' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Ocp-Apim-Subscription-Key: 0fd9826a39aa468fb311d23fc08a55fc'
+```
+
+### Cash OUT
+
+#### Request To Withdraw
+
+**Endpoint:** `POST {{base_url}}/collection/v1_0/requesttowithdraw`
+
+This endpoint allows the user to initiate a request to withdraw funds.
+
+**Request Body**
+- **amount** (string, required): The amount to be withdrawn
+- **currency** (string, required): The currency in which the withdrawal is to be made
+- **externalId** (string, required): The unique identifier for the withdrawal request
+- **payer** (object, required):
+  - **partyIdType** (string, required): The type of party ID for the payer
+  - **partyId** (string, required): The ID of the payer
+- **payerMessage** (string, optional): A message from the payer
+- **payeeNote** (string, optional): A note for the payee
+
+**Request Body Example**
+
+```json
+{
+  "amount": "3536636",
+  "currency": "EUR",
+  "externalId": "45757757",
+  "payer": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerMessage": "MoMo Cash Out Thank You",
+  "payeeNote": "MoMo Cash Out Thank You "
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttowithdraw' \
+--header 'X-Callback-Url: https://webhook.site/mywebhooksandbox' \
+--header 'X-Reference-Id;' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1' \
+--data '{
+  "amount": "3536636",
+  "currency": "EUR",
+  "externalId": "45757757",
+  "payer": {
+    "partyIdType": "MSISDN",
+    "partyId": "56733123455"
+  },
+  "payerMessage": "MoMo Cash Out Thank You",
+  "payeeNote": "MoMo Cash Out Thank You "
+}'
+```
+
+#### Request To Withdraw Status
+
+**Endpoint:** `GET {{base_url}}/collection/v1_0/requesttowithdraw/:Request_ID_CashOut`
+
+This endpoint makes an HTTP GET request to retrieve information about a specific cash withdrawal request identified by the provided Request_ID_CashOut.
+
+**Response**
+Upon a successful execution, the endpoint returns a JSON object with the following fields:
+- **financialTransactionId** (string): The ID of the financial transaction
+- **externalId** (string): The external ID associated with the transaction
+- **amount** (string): The amount of the withdrawal
+- **currency** (string): The currency in which the withdrawal is made
+- **payer** (object): An object containing information about the payer, including partyIdType and partyId
+- **payerMessage** (string): A message from the payer
+- **payeeNote** (string): A note from the payee
+- **status** (string): The status of the withdrawal request
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_CashOut**: `{{Request_ID_CashOut}}`
+
+**Example Request**
+
+```bash
+curl --location 'https://sandbox.momodeveloper.mtn.com/collection/v1_0/requesttowithdraw/:Request_ID_CashOut' \
+--header 'X-Target-Environment: sandbox' \
+--header 'Ocp-Apim-Subscription-Key: bca0c92d326a46cd885f443d51b859f1'
+```
+
+## Invoice
+
+A Business may use this in order to create an invoice that can be paid by an intended payer via any channel at a later stage.
+
+### Create Invoice
+
+**Endpoint:** `POST {{base_url}}collection/v2_0/invoice`
+
+This endpoint allows you to create a new invoice. The customer will receive an SMS with the Invoice ID.
+
+The Payments can be made via MoMo USSD or MoMo APP.
+
+**Request Body**
+- **externalId** (string): The external identifier for the invoice
+- **amount** (string): The amount of the invoice
+- **currency** (string): The currency in which the invoice amount is specified
+- **validityDuration** (string): The duration for which the invoice is valid
+- **intendedPayer** (object): An object containing the party ID type and party ID of the intended payer
+  - **partyIdType** ("MSISDN/ALIAS"): The type of party ID for the intended payer
+  - **partyId** (MSISDN ID): The party ID of the intended payer
+- **payee** (object): An object containing the party ID type and party ID of the payee
+  - **partyIdType** (MSISDN): The type of party ID for the payee
+  - **partyId** (string): The party ID of the payee
+- **description** (string): Description of the invoice
+
+**Request Body Example**
+
+```json
+{
+    "externalId": "005060",
+    "amount": "5000",
+    "currency": "EUR",
+    "validityDuration": "360",
+    "intendedPayer": {
+        "partyIdType": "MSISDN",
+        "partyId": "56784939"
+    },
+    "payee": {
+        "partyIdType": "MSISDN",
+        "partyId": "46733123450"
+    },
+    "description": "Invoice SandBox"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+### Invoice Status
+
+**Endpoint:** `GET {{base_url}}/collection/v2_0/invoice/:Request_ID_Invoice`
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Invoice**: `{{Request_ID_Invoice}}`
+
+### Delete Invoice
+
+**Endpoint:** `DELETE {{base_url}}/collection/v2_0/invoice/:Request_ID_Invoice`
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Invoice**: `{{Request_ID_Invoice}}`
+
+**Request Body Example**
+
+```json
+{
+    "externalId": "57r75677"
+}
+```
+
+## Pre Approval
+
+Pre Approval API is used to get consent from the customer to be Debited for a specified period of time. The Consent is approved by the customer providing the correct PIN. The Consent can be cancelled anytime by the customer.
+
+### Request Preapproval
+
+**Endpoint:** `POST {{base_url}}/collection/v2_0/preapproval`
+
+Create Preapproval - This endpoint allows you to create a preapproval for a collection.
+
+**Request Body**
+- **payer** (object, required): Information about the payer including partyIdType and partyId
+- **payerCurrency** (string, required): The currency of the payer
+- **payerMessage** (string, required): A message from the payer
+- **validityTime** (string, required): The validity time of the preapproval
+
+**Request Body Example**
+
+```json
+{
+  "payer": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerCurrency": "EUR",
+  "payerMessage": "HI MoMo API",
+  "validityTime": "300"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/collection/v2_0/preapproval' \
+--header 'X-Callback-Url: {{CallbackURL}}' \
+--header 'X-Reference-Id: {{Request_ID_Preapproval}}' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: {{Collection_Subscription-Key}}' \
+--data '{
+  "payer": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerCurrency": "EUR",
+  "payerMessage": "HI MoMo API",
+  "validityTime": "300"
+}'
+```
+
+### Get PreApproval Status
+
+**Endpoint:** `GET {{base_url}}/collection/v2_0/preapproval/:Request_ID_Preapproval`
+
+This API endpoint retrieves the details of a specific preapproval by providing the preapproval request ID in the URL.
+
+**Response**
+Upon a successful execution (Status: 200), the response will be in JSON format with the following fields:
+- **payer**
+  - **partyIdType**
+  - **partyId**
+- **payerCurrency**
+- **payerMessage**
+- **expirationDateTime**
+- **status**
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Preapproval**: `{{Request_ID_Preapproval}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/collection/v2_0/preapproval/{{Request_ID_Preapproval}}' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Ocp-Apim-Subscription-Key: {{Collection_Subscription-Key}}'
+```
+
+## Remittance
+
+The Remittance API empowers businesses by enabling users to transmit or receive funds from overseas straight into their Mobile Money accounts, all in local currency.
+
+### Transfer
+
+**Endpoint:** `POST {{base_url}}/remittance/v1_0/transfer`
+
+**Headers**
+- **X-Reference-Id**: The UUID Version 4 Format String, labeled as Request_ID_Transfer, is used to uniquely identify a transaction and retrieve the status
+- **Authorization**: Bearer Token, the Access_token, is automatically generated in the pre-request script of the collection
+- **X-Target-Environment**: Specifies the country the request is to be processed for production, using sandbox during testing
+- **Content-Type**: application/json
+- **Ocp-Apim-Subscription-Key**: Subscription key providing access to the APIM
+- **X-Callback-Url**: Secure HTTPS URL for receiving responses
+
+**Request Body**
+- **Amount** (string): Amount to be transferred to the MoMo Subscriber
+- **Currency** (string): Varies depending on the country, with Sandbox using EUR
+- **ExternalId** (string): String used for reconciliation between Partner Platform and MoMo Platform
+- **PartyIdType** (string): Supported types are MSISDN and ALIAS
+- **PartyId** (string): Value of the MSISDN Number or Merchant ID
+- **PayerMessage** (string): Notification sent to the Sender
+- **PayeeNote** (string): Notification sent to the receiver
+
+**Request Body Example**
+
+```json
+{
+  "amount": "980000",
+  "currency": "EUR",
+  "externalId": "9087699",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerMessage": "remittance amount",
+  "payeeNote": "remittance amount"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/remittance/v1_0/transfer' \
+--header 'X-Callback-Url: {{CallbackURL}}' \
+--header 'X-Reference-Id: {{Request_ID_Remit_Transfer}}' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: {{Remittance_Subscription-Key}}' \
+--data '{
+  "amount": "980000",
+  "currency": "EUR",
+  "externalId": "9087699",
+  "payee": {
+    "partyIdType": "MSISDN",
+    "partyId": "{{MSISDN}}"
+  },
+  "payerMessage": "remittance amount",
+  "payeeNote": "remittance amount"
+}'
+```
+
+### Transfer Status
+
+**Endpoint:** `GET https://sandbox.momodeveloper.mtn.com/remittance/v1_0/transfer/:Request_ID_Remit_Transfer`
+
+This HTTP GET request is used to retrieve information about a specific remittance transfer identified by the Request ID.
+
+**Response**
+Upon a successful execution, the API returns a JSON response with the following fields:
+- **amount**: The amount of the remittance transfer
+- **currency**: The currency of the remittance transfer
+- **financialTransactionId**: The financial transaction ID associated with the transfer
+- **externalId**: The external ID associated with the transfer
+- **payee**: An object containing information about the payee, including party ID type and party ID
+- **payerMessage**: The message from the payer associated with the transfer
+- **payeeNote**: The note from the payee associated with the transfer
+- **status**: The status of the remittance transfer
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Path Variables**
+- **Request_ID_Remit_Transfer**: `{{Request_ID_Remit_Transfer}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff 'https://sandbox.momodeveloper.mtn.com/remittance/v1_0/transfer/{{Request_ID_Remit_Transfer}}' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Ocp-Apim-Subscription-Key: {{Remittance_Subscription-Key}}'
+```
+
+## CashTransfer
+
+CashTransfer API is the enriched Remittance API, designed to facilitate the efficient capture of Know Your Customer (KYC) details for both the payer and payee involved in fund transfers.
+
+### Field Descriptions:
+
+- **amount**: This is the sum that the recipient will receive following currency conversion
+- **currency**: Specifies the type of currency in which the recipient will receive the amount (ISO 4217 Currency Codes)
+- **payee**: Contains information about the beneficiary
+- **partyId**: A unique identifier for the recipient, which could be a phone number, email, or a designated party code
+- **partyIdType**: The kind of identifier being used, such as MSISDN, EMAIL, or PARTY_CODE
+- **externalId**: This is the transaction ID used for business applications and is useful for reconciliation purposes
+- **originatingCountry**: The country from which the funds are being sent
+- **originalAmount**: The initial sum to be received before any currency conversion takes place
+- **originalCurrency**: The currency in which the original sum is denominated (ISO 4217 Currency Codes)
+- **payerMessage**: A message that will be delivered to the sender
+- **payeeNote**: A note that will be delivered to the beneficiary
+- **payerIdentificationType**: The type of identification used for the sender
+
+### Payer Identification Types:
+- **CPFA**: CPF account number
+- **SRSA**: SRS account number
+- **NRIN**: National registration identification number
+- **OTHR**: Other
+- **DRLC**: Drivers license number
+- **PASS**: Passport number
+- **SOCS**: Social security number
+- **AREG**: Alien registration number
+- **IDCD**: Identity card number
+- **EMID**: Employer identification number
+
+- **payerIdentificationNumber**: The identification number that corresponds to the specified identification type
+- **payerIdentity**: The MSISDN utilized by the sender in the country where the remittance originates. Format: (ID:6873248686/MSISDN)
+- **payerFirstName** / **payerSurName**: The given name and surname of the sender
+- **payerLanguageCode**: The linguistic code corresponding to the sender's nation (ISO_639-1)
+- **payerEmail**: The sender's electronic mail address (Validated)
+- **payerMsisdn**: The phone number of the sender
+- **payerGender**: The sex of the sender (MALE, FEMALE, OTHER)
+
+### cashtransfer
+
+**Endpoint:** `POST {{base_url}}/remittance/v2_0/cashtransfer`
+
+**Request Headers**
+- **X-Reference-Id**: `{{Request_ID_Cash_Transfer}}`
+- **X-Target-Environment**: `{{Target_Environment}}`
+- **Content-Type**: application/json
+- **Ocp-Apim-Subscription-Key**: `{{Remittance_Subscription-Key}}`
+
+**Request Body Example**
+
+```json
+{
+    "amount": "208",
+    "currency": "EUR",
+    "payee": {
+        "partyIdType": "MSISDN",
+        "partyId": "{{MSISDN}}"
+    },
+    "externalId": "XTR1718714047",
+    "orginatingCountry": "SO",
+    "originalAmount": "1",
+    "originalCurrency": "USD",
+    "payerMessage": "From SO to MTN UG Payer",
+    "payeeNote": "Test",
+    "payerIdentificationType": "PASS",
+    "payerIdentificationNumber": "UG0002",
+    "payerIdentity": "ID:256701081899/MSISDN",
+    "payerFirstName": "Abdirazak",
+    "payerSurName": "Ibrahim",
+    "payerLanguageCode": "en",
+    "payerEmail": "abdirazak.ibrahim@tt.com",
+    "payerMsisdn": "252654249184",
+    "payerGender": "MALE"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/remittance/v2_0/cashtransfer' \
+--header 'X-Reference-Id: {{Request_ID_Cash_Transfer}}' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: {{Remittance_Subscription-Key}}' \
+--data-raw '{
+    "amount": "208",
+    "currency": "EUR",
+    "payee": {
+        "partyIdType": "MSISDN",
+        "partyId": "{{MSISDN}}"
+    },
+    "externalId": "XTR1718714047",
+    "orginatingCountry": "SO",
+    "originalAmount": "1",
+    "originalCurrency": "USD",
+    "payerMessage": "From SO to MTN UG Payer",
+    "payeeNote": "Test",
+    "payerIdentificationType": "PASS",
+    "payerIdentificationNumber": "UG0002",
+    "payerIdentity": "ID:256701081899/MSISDN",
+    "payerFirstName": "Abdirazak",
+    "payerSurName": "Ibrahim",
+    "payerLanguageCode": "en",
+    "payerEmail": "abdirazak.ibrahim@tt.com",
+    "payerMsisdn": "252654249184",
+    "payerGender": "MALE"
+}'
+```
+
+### cashtransfer status
+
+**Endpoint:** `GET {{base_url}}/remittance/v2_0/cashtransfer/:Request_ID_Cash_Transfer`
+
+**Request Headers**
+- **X-Target-Environment**: `{{Target_Environment}}`
+- **Ocp-Apim-Subscription-Key**: `{{Remittance_Subscription-Key}}`
+
+**Path Variables**
+- **Request_ID_Cash_Transfer**: `{{Request_ID_Cash_Transfer}}`
+
+**Response Example**
+
+```json
+{
+    "financialTransactionId": "179403634",
+    "externalId": "XTR1718714047",
+    "payee": {
+        "partyIdType": "MSISDN",
+        "partyId": "56733123453"
+    },
+    "amount": "208",
+    "currency": "EUR",
+    "originalAmount": "1",
+    "originalCurrency": "USD",
+    "payerMessage": "From SO to MTN UG Payer",
+    "payeeNote": "Test",
+    "status": "SUCCESSFUL",
+    "payerIdentificationType": "PASS",
+    "payerIdentificationNumber": "UG0002",
+    "payerIdentity": "ID:256701081899/MSISDN",
+    "payerFirstName": "Abdirazak",
+    "payerSurName": "Ibrahim",
+    "payerLanguageCode": "en",
+    "payerEmail": "abdirazak.ibrahim@tt.com",
+    "payerMsisdn": "252654249184",
+    "payerGender": "MALE"
+}
+```
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/remittance/v2_0/cashtransfer/{{Request_ID_Cash_Transfer}}' \
+--header 'X-Target-Environment: {{Target_Environment}}' \
+--header 'Ocp-Apim-Subscription-Key: {{Remittance_Subscription-Key}}'
+```
+
+## Account Balance
+
+MoMo API for Account Balance to check your personal account standings. Remember, this balance isn't for the client, but specifically for the Merchant Account - the Account Owner.
+
+### Get Account Balance
+
+**Endpoint:** `GET {{base_url}}/collection/v1_0/account/balance`
+
+This endpoint makes an HTTP GET request to retrieve the account balance from the specified collection.
+
+**Authorization**
+- Bearer Token: `{{Access_Token}}`
+
+## Get API User and API Key
+
+**Endpoint:** `POST {{base_url}}/v1_0/apiuser`
+
+This endpoint makes an HTTP POST request to create an API user at the specified URL.
+
+**Request Body**
+
+```json
+{
+    "providerCallbackHost": "{{CallbackHost}}"
+}
+```
+
+**Example Request**
+
+```bash
+curl --location --globoff '{{base_url}}/v1_0/apiuser' \
+--header 'X-Reference-Id: {{api_user}}' \
+--header 'Content-Type: application/json' \
+--header 'Ocp-Apim-Subscription-Key: {{Collection_Subscription-Key}}' \
+--data '{
+    "providerCallbackHost": {{CallbackHost}}
+}'
+```

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_auth_docs.md

@@ -0,0 +1,67 @@
+# Authentication
+
+## Authentication Endpoint - `Post Request`
+
+Pesapal's API Authentication requests are done via a POST request.
+
+Your Pesapal merchant **consumer_key** and **consumer_secret** will be used to generate an access token.
+
+This access token is valid for a maximum period of **5 minutes.** Use this token (sent as a Bearer Token) to access all other Pesapal API 3.0 endpoints.
+
+The URL to our token generation API is either:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/Auth/RequestToken
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/Auth/RequestToken
+
+## HTTP Request Headers
+
+**Accept:** The response format, which is required for operations with a response body. **Content-Type:** The request format, which is required for operations with a request body.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Accept | `Required` | Should be set to `application/json` |
+| Content-Type | `Required` | Should be set to `application/json` |
+
+## Request Parameters
+
+Your live/production **consumer_key** and **consumer_secret** will be sent to your merchant email on opening a business/merchant account.
+
+Please click here to open a live/production business account.
+
+Click here to download test credentials to use while connecting to our **demo/sandbox** API.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| consumer_key | String | `Required` | The consumer_key parameter must be set to `merchant consumer_key` |
+| consumer_secret | String | `Required` | The consumer_secret parameter must be set to `merchant consumer_secret.` |
+
+## Sample Request
+
+```json
+{
+    "consumer_key": "xxxxx",
+    "consumer_secret": "xxxxxx"
+}
+```
+
+## Response Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| token | String | The access token string as issued by the server. The access token issued will have permission to invoke all Pesapa API operations. |
+| expiryDate | String | Date and time the token will expire. The access token usually expires after 5mins - `UTC` |
+| error | Object | Error object |
+| status | String | Response code |
+| message | String | A brief description about the response received. |
+
+## Sample Response
+
+```json
+{
+    "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYa",
+    "expiryDate": "2021-08-26T12:29:30.5177702Z",
+    "error": null,
+    "status": "200",
+    "message": "Request processed successfully"
+}
+```

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_e-commerce_intro.md

@@ -0,0 +1,30 @@
+# Pesapal API 3.0
+
+Welcome to **Pesapal API 3.0**. Getting started with Pesapal is quick and easy!
+
+In this release, you will learn how to use our API endpoints to access Pesapal services. Our APIs are built on **REST (Representational State Transfer)** thus our data entities are represented as HTTP resources and are accessed using HTTP verbs **GET** and **POST**. Requests and responses are **JSON encoded**.
+
+Find information about integrating your website with Pesapal. This documentation includes sample codes for each API we have.
+
+**Postman URL**: https://documenter.getpostman.com/view/6715320/UyxepTv1
+
+## Base URLs
+
+| Environment | URL |
+|-------------|-----|
+| Sandbox | https://cybqa.pesapal.com/pesapalv3 |
+| Live | https://pay.pesapal.com/v3 |
+
+## Error Object
+
+In case an error occurs during any API call, Pesapal will respond with a json string in the following format:
+
+```json
+{
+    "error": {
+        "type": "error_type",
+        "code": "response_code",
+        "message": "Detailed error message goes here..."
+    }
+}
+```

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_get_ipn_docs.md

@@ -0,0 +1,49 @@
+# Get Registered IPNs
+
+## Get Registered IPNs Endpoint - `Get Request`
+
+This endpoint allows you to fetch all registered IPN URLs for a particular Pesapal merchant account.
+
+The URL to our GetIPNList API is either:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/URLSetup/GetIpnList
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/URLSetup/GetIpnList
+
+## Authentication
+
+**Bearer Token:** Use token generated during authentication.
+
+## Request
+
+No payload is required.
+
+## Response Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| url | String | The notification url Pesapal with send a status alert to. |
+| created_date | String | Date and time the IPN URL was registered `UTC` |
+| ipn_id | String | A unique identifier that's liked to the IPN endpoint URL. `GUID` |
+| error | Integer | |
+| status | String | Response code. |
+
+## Sample Response
+
+```json
+[
+    {
+        "url": "https://www.myapplication.com/ipn",
+        "created_date": "2022-03-03T17:29:03.7208266Z",
+        "ipn_id": "e32182ca-0983-4fa0-91bc-c3bb813ba750",
+        "error": null,
+        "status": "200"
+    },
+    {
+        "url": "https://ipn.myapplication.com/application2",
+        "created_date": "2021-12-05T04:23:45.5509243Z",
+        "ipn_id": "c3bb813ba750-0983-4fa0-91bc-e32182ca",
+        "error": null,
+        "status": "200"
+    }
+]
+```

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_get_transaction_status_docs.md

@@ -0,0 +1,97 @@
+# Get Transaction Status
+
+## Get Transaction Status Endpoint - Get Request
+
+Once Pesapal redirect your customer to your callback URL and triggers your IPN URL, you need to check the status of the payment using the **OrderTrackingId**.
+
+The URL to our GetTransactionStatus API is either:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/Transactions/GetTransactionStatus?orderTrackingId=xxxxxxxxxxxx
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/Transactions/GetTransactionStatus?orderTrackingId=xxxxxxxxxxxx
+
+Where **xxxxxxxxxxxx** represents the OrderTrackingId received as part of the callback [GET] or IPN [POST/GET] params.
+
+## Authentication
+
+**Bearer Token:** Use token generated during authentication.
+
+## HTTP Request Headers
+
+**Accept:** The response format, which is required for operations with a response body.
+**Content-Type:** The request format, which is required for operations with a request body.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Accept | Required | Should be set to application/json |
+| Content-Type | Required | Should be set to application/json |
+
+## Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| orderTrackingId | string | Required | Unique order id generated by Pesapal e.g 7e6b62d9-883e-440f-a63e-e1105bbfadc3. Attached as a query parameter to the getTransactionStatus endpoint to get status of your submitted order. |
+
+## Response Parameters
+
+| Name | Description |
+|------|-------------|
+| payment_method | This refers to the payment method used by your customers to make payment. Can be through CARD, MPESA, MTN, TIGO etc. |
+| amount | Amount paid by the customer. |
+| created_date | Date the payment was made. |
+| confirmation_code | Confirmation code received from the payment provider used. |
+| payment_status_description | Contains the status of the transaction. This will include either INVALID, FAILED, COMPLETED or REVERSED. |
+| description | Description of the payment status. |
+| message | The message shows if transaction request status was processed successfully or not. |
+| payment_account | Masked card number or phone number used during payment. |
+| call_back_url | A valid URL which Pesapal will redirect the client to after payment is made. |
+| status_code | Pesapal status code representing the payment_status_description. 0 - INVALID, 1 - COMPLETED, 2 - FAILED, 3 - REVERSED |
+| merchant_reference | Your application's unique ID as received in the SubmitOrderRequest call. |
+| currency | Currency the payment was made in. ISO Currency Codes. |
+| error | An error object containing error_type, code, message and call_back_url. |
+| status | HTTP status code as defined on RFC 2616. A status of 200 means the request was successful. |
+
+## Sample Response
+
+```json
+{
+    "payment_method": "Visa",
+    "amount": 100,
+    "created_date": "2022-04-30T07:41:09.763",
+    "confirmation_code": "6513008693186320103009",
+    "payment_status_description": "Failed",
+    "description": "Unable to Authorize Transaction.Kindly contact your bank for assistance",
+    "message": "Request processed successfully",
+    "payment_account": "476173**0010",
+    "call_back_url": "https://test.com/?OrderTrackingId=7e6b62d9-883e-440f-a63e-e1105bbfadc3&OrderMerchantReference=1515111111",
+    "status_code": 2,
+    "merchant_reference": "1515111111",
+    "payment_status_code": "",
+    "currency": "KES",
+    "error": {
+        "error_type": null,
+        "code": null,
+        "message": null,
+        "call_back_url": null
+    },
+    "status": "200"
+}
+```
+
+## What Next?
+
+Once you've received the payment details, you are then required to store the same in your system and provide services / services paid for.
+
+Your IPN endpoint should then respond to Pesapal with a json string confirming receipt of the IPN call. Part of the json string contains a **status** parameter that should be set as **200** (meaning request was received and processed) or **500** (meaning IPN request was received but there was an issue completing the process).
+
+**Sample IPN JSON Response String:**
+
+```json
+{
+    "orderNotificationType": "IPNCHANGE",
+    "orderTrackingId": "d0fa69d6-f3cd-433b-858e-df86555b86c8",
+    "orderMerchantReference": "1515111111",
+    "status": 200
+}
+```
+
+**NB:** Your callback page should not implement a json response. Instead, redirect the customer to a page on your system showing the payment details.

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_ipn_docs.md

@@ -0,0 +1,88 @@
+# IPN URL Registration
+
+## IPN URL Registration Endpoint - Post Request
+
+**IPN** stands for **Instant Payment Notification**. When a payment is made against a transaction, Pesapal will trigger an IPN call to the notification URL related to this transaction. This notification URL is usually located on your servers. These notifications allows you to be alerted in real time whenever there is a status change for any transaction.
+
+An IPN is particular important as it allows you to be notified incase the following happens:
+
+- Your client gets disconnected after payment due to internet issues
+- Your client experiences server errors hence Pesapal and your application gets disconnected before callback URL is loaded
+- Your client exits your application / closes the browser during payment
+- The transaction is rejected
+
+As such, it's mandatory to have IPN configured to allow Pesapal to notify your servers when a status changes. It's also important to note that this **IPN URL must be publicly available**. In cases where you have strict server rules preventing external systems reaching your end, you must then whitelist all calls from our domain (pesapal.com). Please be informed that IP whitelisting is not feasible as our IP may change without notice.
+
+Before sending Submit Order Requests to Pesapal API 3.0, you are expected to register your IPN URL. Upon registration, you receive an **IPN ID** which is a mandatory field (**notification_id**) when submitting an order request to Pesapal API 3.0. This **notification_id** uniquely identifies the endpoint Pesapal will send alerts to whenever a payment status changes for each transaction processed via API 3.0
+
+The URL to our IPN registration API is either:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/URLSetup/RegisterIPN
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/URLSetup/RegisterIPN
+
+## Authentication
+
+**Bearer Token:** Use token generated during authentication.
+
+## HTTP Request Headers
+
+**Accept:** The response format, which is required for operations with a response body.
+**Content-Type:** The request format, which is required for operations with a request body.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Accept | Required | Should be set to application/json |
+| Content-Type | Required | Should be set to application/json |
+
+## Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| url | String | Required | The notification url Pesapal with send a status alert to. |
+| ipn_notification_type | String | Required | GET or POST. This is the http request method Pesapal will use when triggering the IPN alert. |
+
+## Sample Request
+
+```json
+{
+    "url": "https://www.myapplication.com/ipn",
+    "ipn_notification_type": "GET"
+}
+```
+
+## Response Parameters
+
+| Name | Description |
+|------|-------------|
+| url | The notification url Pesapal will send a status alert to. |
+| created_date | Date and time the IPN URL was registered UTC |
+| ipn_id | A unique identifier that's linked to the IPN endpoint URL. GUID |
+| notification_type | 1 or 0 |
+| ipn_notification_type_description | The http request method you registered your IPN url as |
+| ipn_status | 1 or 0 ie Active or Inactive |
+| ipn_status_decription | Status description ie Active or Inactive |
+| error | An error object containing error_type, code and message if any. Null to signify no error. |
+| status | Response code. |
+
+## Sample Response
+
+```json
+{
+    "url": "https://myapplication.com/ipn",
+    "created_date": "2024-06-14T07:50:22.2825997Z",
+    "ipn_id": "84740ab4-3cd9-47da-8a4f-dd1db53494b5",
+    "notification_type": 0,
+    "ipn_notification_type_description": "GET",
+    "ipn_status": 1,
+    "ipn_status_description": "Active",
+    "error": null,
+    "status": "200"
+}
+```
+
+## Alternative Registration Methods
+
+You can also use our online forms below to register your IPN URLs:
+
+- **Sandbox/Demo IPN Registration Form**
+- **Production/Live IPN Registration Form**

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_order_cancellation_api_docs.md

@@ -0,0 +1,68 @@
+# Order Cancellation API
+
+## Definitions
+
+The Order Cancellation API enables you to revoke a previously placed order request that remains incomplete on our end. This API facilitates the cancellation of orders that have encountered failures or are pending transactions.
+
+However, there are certain constraints associated with cancelling a prior request:
+
+1. Cancellation is exclusively supported for failed or pending payments.
+2. A cancellation request can only be submitted once.
+3. Cancellation is not allowed for payments that have already been processed.
+
+You can access our Cancel Order API via the endpoints provided below:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/Transactions/CancelOrder
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/Transactions/CancelOrder
+
+## Authentication
+
+**Bearer Token:** Use token generated during authentication.
+
+## HTTP Request Headers
+
+**Accept:** The response format, which is required for operations with a response body.
+**Content-Type:** The request format, which is required for operations with a request body.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Accept | Required | Should be set to `application/json` |
+| Content-Type | Required | Should be set to `application/json` |
+
+## Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| order_tracking_id | Guid | Required | This refers to the original Pesapal Order tracking ID that was returned after submitting your order request earlier during the initial submit order request api call. |
+
+## Sample Request
+
+```json
+{
+    "order_tracking_id": "xxxxxxxxxxxxxxxxxxxxxxx"
+}
+```
+
+After successfully cancelling the request, the order shall be cancelled on our systems preventing a customer from making further payments to an already cancelled order.
+
+## Response Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| status | message | 200 – Order Successfully cancelled. 500 – Order could not be cancelled. |
+| message | String | A summary of the response received. |
+
+Status **200** mean your request to cancel the order has been processed successfully.
+
+Status **500** mean your request to cancel your order has failed due to one or more reasons as shared earlier on the introduction page above.
+
+## Sample Response
+
+```json
+{
+    "status": "200",
+    "message": "Order successfully cancelled."
+}
+```
+
+**Important Note:** The Order Cancellation API uses the Pesapal Order Tracking ID to cancel the order. It's important that you store the Pesapal Order Tracking ID that is sent back to your system during your initial order placement stage i.e. on the submit order request endpoint.

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_recurring_payments_docs.md

@@ -0,0 +1,217 @@
+# Pesapal Recurring / Subscription Based Payments
+
+## Definitions
+
+**Recurring payment** is a payment model where customers authorize the business to pull funds from their accounts automatically at regular intervals for the goods and services provided to them on an ongoing basis.
+
+With Pesapal's subscription based payments, customers can set automated card payments on their account where they can be debited automatically at a different set times. Examples of services one can enroll to include cable bills, cell phone bills, gym membership fees, utility bills and magazine subscriptions. These payments can be set to run an various intervals such as daily, weekly, monthly or yearly.
+
+## How can recurring payments benefit your business?
+
+- **Saves customers time**: Customers no longer have to go through the payment process every time they need to make a payment.
+- **Ensures prompt payment**: Businesses no longer need to worry about getting paid on time. Since the payments are automated, they no longer need to send out overdue payment reminders.
+- **Boosts customer loyalty**: With a subscription model, businesses can form closer relationships with their customers.
+- **Cash flow prediction**: Businesses can easily predict their cash flow, which helps with business strategy.
+- **Lowers billing and collection costs**: Businesses no longer need to chase after missed payments, freeing up their time to concentrate on other elements of the business.
+
+## How do I enable recurring payment for my customers?
+
+Enable our subscription based payments by passing an additional **account_number** field when sending data to our **SubmitOrderRequest** endpoint. This account_number should relate to an account number / invoice number that helps you identify the payment.
+
+**Note**: It's critical that you get to understand all other Pesapal API 3.0 endpoints before implementing the recurring feature.
+
+In addition to the **SubmitOrderRequest** parameters, include one more param as shown below.
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| account_number | Optional | Customer's identification number known to your system. This can be an invoice number or an account number. |
+
+### Sample Request
+
+```json
+{
+    "id": "AA1122-3344ZZ",
+    "currency": "KES",
+    "amount": 100.00,
+    "description": "Payment description goes here",
+    "callback_url": "https://www.myapplication.com/response-page",
+    "notification_id": "fe078e53-78da-4a83-aa89-e7ded5c456e6",
+    "billing_address": {
+        "email_address": "john.doe@example.com",
+        "phone_number": "0723xxxxxx",
+        "country_code": "KE",
+        "first_name": "John",
+        "middle_name": "",
+        "last_name": "Doe",
+        "line_1": "Pesapal Limited",
+        "line_2": "",
+        "city": "",
+        "state": "",
+        "postal_code": "",
+        "zip_code": ""
+    },
+    "account_number": "555-678"
+}
+```
+
+After successfully processing your request using the **SubmitOrderRequest** endpoint, the customer will be shown an option to opt into the recurring model on the Pesapal iframe during payment. The customer will then configure the frequency (Daily, weekly, monthly, quarterly or yearly), set a start and enddate, and finally enter an amount to be automatically deducted from their card on each payment cycle.
+
+Once the customer has made a successful payment, Pesapal will automatically create a scheduled subscription on their behalf and an email alert will be sent to the provided card billing email that was used during the payment process, notifying them of the newly created subscription together with a link they can access a dashboard to manage their subscription.
+
+**Pesapal will NOT store the customer's card details.** Instead, Pesapal has implemented the **card tokenization technology**.
+
+**Credit card tokenization** is the process of de-identifying sensitive cardholder data by converting it to a string of randomly generated numbers called a "token." Similar to encryption, tokenization obfuscates the original data to render it unreadable to a user. Unlike encryption, however, credit card tokenization is irreversible.
+
+## Is it possible to send the extra subscription parameters (Frequency, amount, period) via the API?
+
+Yes, in cases where your application already handles the process where the customer opts into a subscription based model from your application, Pesapal allows you to send these extra parameters via the API. This ensures that the user does not have to fill in the same details again (on your application and on the Pesapal Iframe).
+
+However, it's important to note that the customer **MUST accept to enroll to your subscription on the iframe**. They will however not be able to edit the subscription details on the iframe.
+
+In addition to the **account_number** parameter included in the **SubmitOrderRequest**, you are required to send the following parameter.
+
+### Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| subscription_details | Optional | Customer Subscription Object You can pass subscription data to Pesapal allowing a user to setup recurring payment. |
+
+### Subscription Object
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| start_date | String | Mandatory | Your subscription's start date in the format dd-MM-yyyy e.g 24-01-2023 representing 24th Jan 2023 |
+| end_date | String | Mandatory | Your subscription's end date in the format dd-MM-yyyy e.g 31-12-2023 representing 31st Dec 2023 |
+| frequency | String | Mandatory | The period billed to the account is set out in the user contract. For instance, if users subscribe to a monthly service. Accepted values include DAILY, WEEKLY, MONTHLY or YEARLY |
+
+### Sample Request
+
+```json
+{
+    "id": "AA1122-3344ZZ",
+    "currency": "KES",
+    "amount": 100.00,
+    "description": "Payment description goes here",
+    "callback_url": "https://www.myapplication.com/response-page",
+    "notification_id": "fe078e53-78da-4a83-aa89-e7ded5c456e6",
+    "billing_address": {
+        "email_address": "john.doe@example.com",
+        "phone_number": "0723xxxxxx",
+        "country_code": "KE",
+        "first_name": "John",
+        "middle_name": "",
+        "last_name": "Doe",
+        "line_1": "Pesapal Limited",
+        "line_2": "",
+        "city": "",
+        "state": "",
+        "postal_code": "",
+        "zip_code": ""
+    },
+    "account_number": "555-678",
+    "subscription_details": {
+        "start_date": "24-01-2023",
+        "end_date": "31-12-2023",
+        "frequency": "DAILY"
+    }
+}
+```
+
+After successfully processing your request using the **SubmitOrderRequest** endpoint, the customer will be shown an option to opt into the recurring model on the Pesapal iframe during payment. The iframe will this time load without the options to re-select the Frequency, period and dates.
+
+## Can a customer opt out of recurring payments before the end date?
+
+Yes, customers have the right to cancel their subscription at anytime. Pesapal will send them email alerts a day or two prior to charging their cards. This ensures customers are always aware of all upcoming charges giving them the freedom to opt out or pausing their subscriptions.
+
+## Which cards are currently supported?
+
+We currently support **Visa** and **MasterCard** for recurring payments. More card options will be enabled in the near future.
+
+## How will Pesapal alert my business about successful recurring payments?
+
+Once a schedule is created and executed successfully, Pesapal will trigger an **IPN (Instant Payment Notification)** to the IPN endpoint you provided when calling the **SubmitOrderRequest** endpoint. This IPN call will have the **OrderNotificationType** set as **RECURRING**.
+
+**Sample IPN URL**: 
+```
+https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=555-678&OrderNotificationType=RECURRING
+```
+
+### Recurring IPN Details
+
+The IPN alert will either be a **GET** or **POST** request, depending on which HTTP method you selected when registering the IPN URL.
+
+The IPN call will have the following parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| OrderTrackingId | String | Unique order id generated by Pesapal. |
+| OrderNotificationType | String | Value set as RECURRING to represent a Recurring IPN call. |
+| OrderMerchantReference | String | Your account number received as part of the SUBMIT ORDER REQUEST. |
+
+The IPN call will **NOT** have all details of the payment for security reasons. As such, you will be required to fetch the payment using the **GetTransactionStatus API** once the IPN URL is triggered.
+
+In addition to the normal payment status details received from the **GetTransactionStatus** endpoint, Pesapal will append an object **subscription_transaction_info** containing some additional recurring payment data.
+
+### Recurring Payments Extra Data (subscription_transaction_info)
+
+| Name | Description |
+|------|-------------|
+| account_reference | Customer's identification number known to your system. This can be an invoice number or an account number. |
+| amount | Amount paid by the customer. |
+| first_name | Customer's first name. |
+| last_name | Customer's last name. |
+| correlation_id | Pesapal's unique recurring payment identifier / id. |
+
+### Sample Response
+
+```json
+{
+    "payment_method": "Visa",
+    "amount": 100,
+    "created_date": "2022-04-30T07:41:09.763",
+    "confirmation_code": "6513008693186320103009",
+    "payment_status_description": "Failed",
+    "description": "Unable to Authorize Transaction.Kindly contact your bank for assistance",
+    "message": "Request processed successfully",
+    "payment_account": "476173**0010",
+    "call_back_url": "https://test.com/?OrderTrackingId=7e6b62d9-883e-440f-a63e-e1105bbfadc3&OrderMerchantReference=555-678",
+    "status_code": 2,
+    "merchant_reference": "1515111111",
+    "payment_status_code": "",
+    "currency": "KES",
+    "subscription_transaction_info": {
+        "account_reference": "555-678",
+        "amount": 100,
+        "first_name": "John",
+        "last_name": "Doe",
+        "correlation_id": 111222
+    },
+    "error": {
+        "error_type": null,
+        "code": null,
+        "message": null,
+        "call_back_url": null
+    },
+    "status": "200"
+}
+```
+
+## What Next?
+
+Once you've fetched the recurring data, you are then required to store the same in your system and provide services / goods as subscribed.
+
+Your IPN endpoint should then respond to Pesapal with a json string confirming service delivery. Part of the json string contains a **status** parameter that should be set as **200** (meaning request was received and processed) or **500** (meaning request was received but there was an issue providing the services).
+
+**Sample JSON Response String**: 
+```json
+{
+    "orderNotificationType": "RECURRING",
+    "orderTrackingId": "d0fa69d6-f3cd-433b-858e-df86555b86c8",
+    "orderMerchantReference": "555-678",
+    "status": 200
+}
+```
+
+**NB**: Constant complaints from your customers about service / goods not delivered which were paid using recurring / subscription based payment mode will lead to the subscriptions being terminated and your profile banned from using the feature.

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_refund_api_docs.md

@@ -0,0 +1,78 @@
+# Refund Request
+
+## Definitions
+
+The refund request endpoint allow you to refund a charge that has previously been processed but not yet refunded. Funds will be refunded to the credit / debit card or mobile money wallet that was originally charged.
+
+The ability to process a refund has the following limitations:
+
+1. A refund has to be approved by the merchant.
+2. You can't refund more than what was originally collected.
+3. You can only refund payments with the status of **COMPLETED**.
+4. You can partially or fully refund a payment card payment.
+5. You can only fully refund a payment mobile payment.
+6. Refunds are performed in the currency of the original payment.
+7. Multiple refunds are not allowed. You can only request one refund against a payment.
+
+The URL to our RequestRefund API is either:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/Transactions/RefundRequest
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/Transactions/RefundRequest
+
+## Authentication
+
+**Bearer Token:** Use token generated during authentication.
+
+## HTTP Request Headers
+
+**Accept:** The response format, which is required for operations with a response body.
+**Content-Type:** The request format, which is required for operations with a request body.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Accept | Required | Should be set to `application/json` |
+| Content-Type | Required | Should be set to `application/json` |
+
+## Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| confirmation_code | String | Required | This refers to payment confirmation code that was returned by the processor |
+| amount | Float | Required | Amount to be refunded. |
+| username | String | Required | Identity of the user who has initiated the refund. |
+| remarks | String | Required | A brief description on the reason for the refund. |
+
+## Sample Request
+
+```json
+{
+    "confirmation_code": "AA11BB22",
+    "amount": "100.00",
+    "username": "John Doe",
+    "remarks": "Service not offered"
+}
+```
+
+After successfully placing a refund request, a request will be sent to our finance team to start processing the refund.
+
+## Response Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| error | Integer | 200 - Refund received successfully and is being processed. 500 - Refund rejected. |
+| message | String | A brief summary of the response received. |
+
+Status **200** mean your request to process the refund has been received successfully. However, please note that this does not mean the refund has been effected. Pesapal has to get the go ahead from the merchant before finalising the refund.
+
+Status **500** mean your request to process the refund was rejected for one reason or another. Refer to the error message for more details.
+
+## Sample Response
+
+```json
+{
+    "status": "200",
+    "message": "Refund request successfully"
+}
+```
+
+**Important Note:** The refund API uses the confirm code for identification. It's important that you store all payment confirmation codes as returned in the Get Transaction Status Endpoint.

knowledge_base/pesapal/pesapal_e-commerce-api-3.0/pesapal_e-commerce_api_3.0_submit_order_docs.md

@@ -0,0 +1,165 @@
+# Submit Order Request
+
+## Submit Order Request Endpoint - Post Request
+
+Once you have received the bearer token, the next step will be the actual request to create a payment request.
+
+A good example would be a case where the customer has clicked pay now button on your website. At this point, you call the **SubmitOrderRequest** and in return you will get a response which contains a payment redirect URL which you then redirect the customer to or load the URL as an iframe within your site in case you don't want to redirect the customer off your application.
+
+The payment URL will contain the payment methods presented to the customer by Pesapal. After the customer has made the payment, they will be redirected to your callback URL which you will have already provided to us as part of submit order request.
+
+The URL to our SubmitOrderRequest API is either:
+
+- **Sandbox/Demo URL:** https://cybqa.pesapal.com/pesapalv3/api/Transactions/SubmitOrderRequest
+- **Production/Live URL:** https://pay.pesapal.com/v3/api/Transactions/SubmitOrderRequest
+
+## Authentication
+
+**Bearer Token:** Use token generated during authentication.
+
+## HTTP Request Headers
+
+**Accept:** The response format, which is required for operations with a response body.
+**Content-Type:** The request format, which is required for operations with a request body.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| Accept | Required | Should be set to application/json |
+| Content-Type | Required | Should be set to application/json |
+
+## Request Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| id | String | Required | This refers to your unique merchant reference generated by your system. NOTE: It should be unique at all times for every order request. Maximum - 50 characters |
+| currency | String | Required | This represents the currency you want to charge your customers. ISO Currency Codes |
+| amount | Float | Required | Amount to be processed. |
+| description | String | Required | Represents the description of your order. Maximum - 100 characters |
+| redirect_mode | String | Optional | Accepts values TOP_WINDOW or PARENT_WINDOW. If left blank, the default value used will be TOP_WINDOW. This parameter allows you to define where your callback URL will be loaded; - TOP_WINDOW returns to the topmost window in the hierarchy of windows. - PARENT_WINDOW returns the immediate parent of a window. |
+| callback_url | String | Required | A valid URL which Pesapal will redirect your clients to processing the payment. |
+| cancellation_url | String | Optional | A valid URL which Pesapal will redirect your clients to incase they click on cancel request while on the Payment link. If provided, a cancellation link will appear next to the PROCEED button. |
+| notification_id | Guid | Required | This represents an IPN URL which Pesapal will send notifications to after payments have been processed. You are required to register all IPN URLs after which a corresponding notification_id will be generated. Please refer to the IPN URL registration endpoint. |
+| branch | String | Optional | If your business has multiple stores / branches, you can define the name of the store / branch to which this particular payment will be accredited to. |
+| billing_address | Object | Required | Customer Address Object |
+
+## Customer Address Object
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| phone_number | String | Optional if email address is provided. Mandatory if email address is NOT provided. | Customer's phone number |
+| email_address | String | Optional if phone number is provided. Mandatory if phone number is NOT provided. | Customer's email address |
+| country_code | String | Optional | 2 characters long country code in [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) |
+| first_name | String | Optional | Customer's first name |
+| middle_name | String | Optional | Customer's middle name |
+| last_name | String | Optional | Customer's last name |
+| line_1 | String | Optional | Customer's main address |
+| line_2 | String | Optional | Customer's alternative address |
+| city | String | Optional | Customer's city |
+| state | String | Optional | Customer's state Maximum - 3 characters |
+| postal_code | Integer | Optional | Customer's postal code |
+| zip_code | Integer | Optional | Customer's zip code |
+
+## Sample Request
+
+```json
+{
+    "id": "AA1122-3344ZZ",
+    "currency": "KES",
+    "amount": 100.00,
+    "description": "Payment description goes here",
+    "callback_url": "https://www.myapplication.com/response-page",
+    "redirect_mode": "",
+    "notification_id": "fe078e53-78da-4a83-aa89-e7ded5c456e6",
+    "branch": "Store Name - HQ",
+    "billing_address": {
+        "email_address": "john.doe@example.com",
+        "phone_number": "0723xxxxxx",
+        "country_code": "KE",
+        "first_name": "John",
+        "middle_name": "",
+        "last_name": "Doe",
+        "line_1": "Pesapal Limited",
+        "line_2": "",
+        "city": "",
+        "state": "",
+        "postal_code": "",
+        "zip_code": ""
+    }
+}
+```
+
+After successfully creating the order, your response will contain a payment URL (**redirect_url**).
+
+**Status 200** mean your request to process the payment has been received successfully meaning the order has been successfully created on our systems and you can now redirect your customer to make the payment.
+
+## Response Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| order_tracking_id | String | Unique order id generated by Pesapal. |
+| merchant_reference | String | Your application's unique ID received as part of the SUBMIT ORDER REQUEST. |
+| redirect_url | String | URL generated that contains the payment instructions. Redirect to this URL or load it within an iframe |
+| error | Integer | |
+| message | String | Response message. |
+
+## Sample Response
+
+```json
+{
+    "order_tracking_id": "b945e4af-80a5-4ec1-8706-e03f8332fb04",
+    "merchant_reference": "TEST1515111119",
+    "redirect_url": "https://cybqa.pesapal.com/pesapaliframe/PesapalIframe3/Index/?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04",
+    "error": null,
+    "status": "200"
+}
+```
+
+Redirecting your customer to this **redirect_url** will present them with a list of available payment methods which they can use to make the payment.
+
+You can either load this URL outside or within your website (using an Iframe). The advantage of using an iframe is that your customer will not be redirected off the site, hence a seamless payment process.
+
+Once your customer selects their preferred payment method and makes a payment, Pesapal will process the payment and redirect your customers to the callback URL which you had provided as part of the SubmitOrderRequest API call.
+
+## Callback Details
+
+The following parameter will be appended to your callback URL.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| OrderTrackingId | String | Unique order id generated by Pesapal. |
+| OrderNotificationType | String | Has value CALLBACKURL to represent a callback request |
+| OrderMerchantReference | String | Your application's unique ID received as part of the SUBMIT ORDER REQUEST. |
+
+**Sample Callback URL:** https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=TEST1515111119&OrderNotificationType=CALLBACKURL
+
+## IPN Details
+
+At the same time, Pesapal will send an alert to your IPN URL informing you of a status change.
+
+The IPN alert will either be a GET or POST request, depending on which HTTP method you selected when registering the IPN URL.
+
+The IPN call will have the following parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| OrderTrackingId | String | Unique order id generated by Pesapal. |
+| OrderNotificationType | String | Has value IPNCHANGE to represent an IPN call. |
+| OrderMerchantReference | String | Your application's unique ID received as part of the SUBMIT ORDER REQUEST. |
+
+### Sample GET URL
+
+```
+https://www.myapplication.com/response-page?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04&OrderMerchantReference=TEST1515111119&OrderNotificationType=IPNCHANGE
+```
+
+### Sample POST data
+
+```json
+{
+    "OrderNotificationType":"IPNCHANGE",
+    "OrderTrackingId":"b945e4af-80a5-4ec1-8706-e03f8332fb04",
+    "OrderMerchantReference":"TEST1515111119"
+}
+```
+
+The callback URL and the IPN calls will **NOT** have the status of the payment for security reasons. As such, you will be required to fetch the status of the payment using the **GetTransactionStatus API** once the callback page is loaded and when the IPN URL is triggered.

knowledge_base/pesapal/pesapal_integration_guide.md

@@ -0,0 +1,40 @@
+# Integration Guide
+
+We have outlined below the steps involved in integrating a website with PesaPal. To view samples and the complete API reference, please click **here**.
+
+## Step 1: Build your site / application that will accept payments from your customers
+
+The site / application will:
+
+- Collect customer information, such as First Name, Last Name and Email Address
+- Collect payment information, such as Amount and Currency
+
+**Please Note:** the information you collect will be dependent on your site / application requirements. But some information is required by PesaPal
+
+## Step 2: Package the request to post to PesaPal
+
+Once you have the customer and payment details, you need to package it to send to PesaPal.
+
+This involves a few steps as we need to ensure that the communication between your site and PesaPal happens in a secure manner.
+
+PesaPal uses **JSON Web Tokens (JWT)** to make sure that no one else interfers with the request you post to PesaPal
+
+## Step 3: Post the request to PesaPal and load the PesaPal payments page
+
+When a request is posted, PesaPal will display a payments page. This is where the customer will make the payment.
+
+You can embed this payments page directly in your site, providing a seamless experience to your customers. You can do this by inserting an IFrame on the page on your site customers land on when they click pay or checkout.
+
+## Step 4: Display a post-payment page to your customer
+
+Once the customer has completed the payment proces on PesaPal, they will be redirected to a page on your site.
+
+You can use this page to inform the customer that their payment is being processed.
+
+Optionally, you can also query PesaPal at this point to see if the payment has completed succesfully, has failed, or is still being processed.
+
+## Step 5: Query PesaPal for payment status
+
+One last step! When you receive an IPN notification from PesaPal, you need to query PesaPal for the payment status using the orderTrackingId that was sent with the notification
+
+A **PENDING** status indicates that the payment is being processed by PesaPal and the final status of payment (**COMPLETED** or **FAILED**) is not yet known.

knowledge_base/pesapal/pesapal_plugins/pesapal_plugin_installation_guides.md

@@ -0,0 +1,176 @@
+# Pesapal Plugin Installation Guides
+
+## PrestaShop Installation Guide
+
+### Step 1
+- Download our pesapal_prestashop_module_8.1.0 zipped file, unzip it, then inside the file locate the Pesapal folder and zip it.
+
+### Step 2
+- Log in to your PrestaShop administration panel (e.g., http://yourdomain.com/admin).
+
+### Step 3
+- Go to Modules, Module Manager. Click on the "Upload a Module" button.
+
+### Step 4
+- Browse for the module's downloaded compressed file on your local machine and select the Pesapal zipped file from Step 1.
+
+### Step 5
+- After a successful upload, "Module installed!" click on "Configure" to finish the installation.
+
+- **Live:** Enter the Consumer Key & Consumer Secret. You should have received these from the Pesapal registration email. If you lost them, log in to your Pesapal merchant account, scroll to the bottom of the dashboard to find them.
+- **Demo:** To use our Demo, you will have to use our demo consumer keys and secret available here: https://developer.pesapal.com/api3-demo-keys.txt
+
+- Save Settings, then proceed to test the gateway on your store.
+
+---
+
+## WooCommerce Installation Guide
+
+This detailed step by step process below explains how to add Pesapal to your woocommerce Shop to enable you to accept payments using Mobile money (MPESA, Airtel, Voda MPESA, Tigo Pesa, Various Mobile banking apps) and Cards (Visa, MasterCard and American Express).
+
+### Step 1: Download the plugin
+
+Download our Pesapal woo-commerce plugin from our official plugins to a known location, preferably your desktop for easy browsing.
+
+**PLEASE NOTE:** We recommend you download only the WooCommerce plugin to avoid confusion when setting up. Our latest WooCommerce version to date is v3.1.3
+
+### Step 2: Install the plugin
+
+1. Login in to the admin side of your website. Your website admin link is usually looks like this *https://yourwebsite.com/wp-admin*.
+2. Point to Plugins >> Select "Add New" to install the plugin.
+3. Select "Upload Plugin" to browse for the plugin from the location you had previously saved the plugin to during step 1 above.
+4. After browsing for the file, select "Install Now".
+5. After Installing the plugin, Activate it.
+6. From your navigation bar, point to WooCommerce >> Settings. From the settings page, select "Payments" Tab
+7. You will be able to see Pesapal among the list of payment options you have already added.
+8. Select "Manage" to enable and configure/set the integration keys
+9. Enable the plugin by checking the "Enable Pesapal Payment" option.
+10. Enter your live consumer and secret keys as was sent on your email upon your account creation. If you intend to use demo keys, check the "Use Demo Gateway" option.
+11. Make sure you save your changes for you be to be able to receive payments through Pesapal
+
+To set email notifications for IPN, scroll down the page and enter the email addresses you would like to receive IPN notification. **Please note** that this step is optional. Only use it if you wish to track your IPN call
+
+**Note** When payments are completed, you can choose between "Completed" and "Processing" for your WooCommerce order status when setting up our plugin. Simply go to WooCommerce settings > Payments > Pesapal>Mange>Update Paid Orders To to make your selection. This gives you more control over your order management.
+
+### Step 3: Confirm all is well
+
+To do so, go to your shop and checkout a product to see if Pesapal payment option appears
+
+You can now select "Place Order" to see the Pesapal Payment options listed above
+
+---
+
+## Magento Installation Guide
+
+### Step 1: Install the Plugin
+
+1. Copy the Pesapal folder into to app/code directory
+2. Run the magento setup upgrade function: bin/magento setup:upgrade
+
+Should the upgrade function fail, click here for a possible solution.
+
+### Step 2: Setup plugin and complete Configurations
+
+Once you have done this, you need to follow these steps to get it working:
+
+1. Create a merchant account (Business account) at https://www.pesapal.com. After registration, Pesapal will send you an email with you consumer keys and consumer secret needed to use on the website.
+2. Log into your Magento admin and Clear your cache
+
+Go to System or Stores -> Configuration -> Sales -> Payment Methods and you will see. "Pesapal Express"
+
+3. Set your configurations as below;
+   - **Enabled:** YES.
+   - **Test API:** NO (If you set this to yes, this means you are using our demo Pesapal API. You will have to use our demo consumer keys and secret available here: https://developer.pesapal.com/api3-demo-keys.txt)
+   - **Consumer Key & Consumer Secret:** You should have received this from the pesapal registration mail . If you lose this, login to your Pesapal merchant account, scroll to the bottom of the dashboard to find them.
+   - **New order status:** This is the default order status set when a user selects pesapal to "processing". All orders with this status mean the user created an order but pending the payment.
+
+4. Save configurations
+
+---
+
+## WHMCS Installation Guide
+
+Please follow the instructions below to setup the PesaPal gateway module.
+
+### Note
+
+1. The PesaPal gateway module requires the use of modified templates that are provided with this distribution.
+2. The templates provided are based on WHMCS 7.1.X ++ and the default theme.
+
+### Step 1: Install the WHMCS Plugin
+
+1. Upload pesapal.php and the pesapal folder to your whmcs's modules/gateways folder.
+2. Upload the callback/pesapal.php file to your whmcs's modules/gateways/callback folder.
+3. Upload templates/pesapal_callback.tpl and templates/pesapal_iframe.tpl to your template directory. This usually under : templates/six/
+4. Enable the PesaPal module in the WHMCS admin area by going to Addons-> Apps & Integrations->Browse->Payments(On the left)->View All->Under Additional Apps click on pesapal to activate then manage. Paste in your administrator username, Consumer Key and Consumer Secret.
+5. To get your consumer Key and Consumer Secret, Open a Pesapal business account on www.pesapal.com or Pesapal test credentials.
+   - If you opened an account on www.pesapal.com(live account), the key and secret have been sent to the email address you registered with.
+   - Find Pesapal test credentials here, https://developer.pesapal.com/api3-demo-keys.txt
+   - Ensure when you are done testing the plugin using the demo/sandbox account you switch to the live API.
+6. Save configurations.
+
+**NB:** Do not change display name in the configuration.
+
+---
+
+## Shopify Installation Guide
+
+This reading will guide you on how to setup your Shopify Store to accept online payments with Pesapal. Upon completion, your customers will be able to checkout online and pay with the payment options supported in your country such as Visa, Master Card, Amex, MPESA, Airtel Money, Tigo Pesa and others.
+
+### Step 1 - Ensure you have a Pesapal Account
+
+If you already have an account with www.pesapal.com go to Step 2.
+
+In case you have not yet created a Pesapal Business account, you can create a new PesaPal Business account by registering here: Create a Business Account
+
+If you would like guidance on creating an account, you may contact us here
+
+### Step 2 - Find your Consumer Key and Secret
+
+Go to the email address you used to register your Pesapal Business account and search for "**pesapal integration information**". The email should look similar to this:
+
+In case you cannot find this email, you can resend it by going to your Pesapal dashboard, scrolling to the bottom of the page and under Api Credentials, click **RESEND.**
+
+This should resend the consumer key and secret to your email.
+
+### Step 3 - Install the Pesapal App
+
+Open https://apps.shopify.com/pesapal-payments then click **Add App** then you will be directed to a page to confirm installation.
+
+In case you have not yet logged in, you might be prompted to login using your Pesapal Business account **username** and **password**.
+
+If you are not redirected to the application after entering the username and password it may mean your username or password was entered incorrectly of which you should double check your credentials.
+
+Fill in the Shop Details Form with the consumer key and secret from Step 2 above and press save.
+
+Paste your Pesapal Consumer Key and Secret
+
+You will then be redirected back to your Shopify Store Admin Dashboard to activate the Pesapal App.
+
+### Step 4 - Activate the Pesapal App
+
+Scroll to the bottom then Click 'Activate' at the bottom of the page to activate. (Ensure the "Enable Test Mode" option is NOT selected as shown in the screenshot below).
+
+Activate The Pesapal App
+
+### Step 5 - Ensure customers can checkout
+
+Visit your store website. Select an item and checkout. You should be able to see Pesapal as a payment option. Confirm the Pesapal App has been installed correctly by clicking "Pay with Pesapal". You should be directed to a Pesapal page where you can select the various payment methods supported.
+
+### What is Test Mode?
+
+Test mode allows you to checkout and see how the Pesapal payment process works without using real money.
+
+To enable the Pesapal App Test Mode, go to your Store Admin Dashboard → Settings → Payments → Pesapal -> Manage
+
+Scroll to the bottom, Activate "test mode" and press "save"
+
+Then go to your store/shop, add items to your cart, checkout an item and select Pesapal.
+
+You will then see our demo payment page where you can make a "dummy payment" without using real money.
+
+**IMPORTANT:** remember to turn off "test mode" as soon as you are done previewing the check out process. Otherwise your customers will not be able to make payments.
+
+How to Enable Test Mode
+
+In case you see any error, please send an email to developer@pesapal.com and kindy include screenshots so that we can assist you more efficiently.

knowledge_base/pesapal/pesapal_pos_api/pesapal_pos_api_intro.md

@@ -0,0 +1,22 @@
+# Pesapal POS API
+
+Our Pesapal Sabi machines have the ability to allow businesses / merchants receive transactional data once customers make payment using these machines.
+
+There are 2 ways you can receive payments done on the Pesapal Sabi machines:
+
+## 1. Wireless Connection
+
+This refers to a secure over the internet, HTTP POST REST (Representational State Transfer) API. You will need to share with Pesapal a secured URL (SSL enabled), to which Pesapal will post transactional data for each successful payment made via your Pesapal Sabi machine.
+
+Click here to view the API documentation.
+
+## 2. Wired Connection
+
+This refers to a connection between your computer hosting your on-premises POS and the Pesapal Devices through a cable from the PDQ or PinPad. The connection enables the transfer of data from your POS to Pesapal Devices. Pesapal Devices undertake the transactions and send back responses to your POS to undertake next steps based on the response received.
+
+### Access Restriction Notice (Wired Connection)
+
+Access to Pesapal's Sabi Wired connection APIs is restricted, and availability of documentation and assets is limited.
+
+- If you have a developer's account at developer.pesapal.com and wish to request access, kindly contact developer@pesapal.com
+- If you do not currently have a developer's account at **developer.pesapal.com**, Click here to register. After registration, please get in touch with developer@pesapal.com and request for access.

knowledge_base/pesapal/pesapal_pos_api/pesapal_wired_pos_api.md

@@ -0,0 +1,15 @@
+# Wired Connection
+
+This refers to a connection between your computer hosting your on-premises POS and the Pesapal Devices through a cable from the PDQ or PinPad.
+
+The connection enables the transfer of data from your POS to Pesapal Devices. Pesapal Devices undertake the transactions and send back responses to your POS to undertake next steps based on the response received.
+
+## Access Restriction Notice
+
+**Pesapal's Sabi APIs are restricted** - access to this documentation and assets are limited.
+
+If you're seeing this message, you are either not logged in or your profile has limited access to this section of our documentation.
+
+- If you have access to this APIs, make sure you're logged in. Click here to login.
+- If you have a developer's account at developer.pesapal.com and wish to request access, kindly contact developer@pesapal.com
+- If you do not currently have a developer's account at **developer.pesapal.com**, Click here to register. After registration, please get in touch with developer@pesapal.com and request for access.

knowledge_base/pesapal/pesapal_pos_api/pesapal_wireless_pos_api.md

@@ -0,0 +1,52 @@
+# Wireless Connectivity
+
+Achieving seamless integration with your Point of Sale (POS) is possible through wireless transmission of payment details to your designated endpoint.
+
+The initiation of this request will originate from the pqd devices, and upon a successful transaction, the relevant information will be transmitted to your specified endpoint, allowing you to efficiently settle the bill on your end.
+
+This guide explains the process through which merchants can obtain transactional data after customers make payments on the Sabi terminal.
+
+To facilitate the reception of payments within their external systems, merchants are required to furnish us with a secure URL featuring SSL encryption. Pesapal, in turn, will initiate an HTTP POST request to the merchant system, posting the transaction details with the specified parameters.
+
+## Request Parameters
+
+| Parameter | Data Type | Description | Example |
+|-----------|-----------|-------------|---------|
+| first_name | String | Represent the first name of the customer | John |
+| last_name | String | Represents the last name of the customer | Doe |
+| phone | String | Represents the phone number of the customer if provided | 0712345678 |
+| amount | Decimal | Represents the amount paid by the customer | 1.00 |
+| payment_option | String | Represent the payment option used by the customer eg. Visa, MasterCard, Mpesa | Visa |
+| transaction_date | datetime | Represents date and time when the transaction was done | 2019-08-14T14:41:21.4612553Z |
+| currency | String | Represents the currency used during the transaction | KES, USD |
+| merchant_reference | String | Represents the merchant reference in case it was entered by the merchant | 1234 |
+| id | int | Represents Pesapal unique ID | 12 |
+| confirmation_code | String | Represents either confirmation of payment code for mpesa and cards | QWE1234 |
+
+## Sample Request
+
+```json
+{
+  "id": 10463,
+  "first_name": "joe",
+  "last_name": "doe",
+  "phone": "+254712345678",
+  "amount": 1.0,
+  "payment_option": "Visa",
+  "transaction_date": "2022-02-04T14:19:05.0210431Z",
+  "currency": "KES",
+  "merchant_reference": "TEST",
+  "confirmation_code": "test10"
+}
+```
+
+## Sample Response
+
+```json
+{
+  "status": "200",
+  "message": "Ok"
+}
+```
+
+**NB:** For a tailored solution corresponding to the above payload, please reach out to developer@pesapal.com. Our dedicated team is ready to provide assistance and support.

knowledge_base/sentezo/sentezo_wallet_api_docs.md

@@ -0,0 +1,639 @@
+# Ssentezo Wallet Version 2.x 🤩 API Documentation
+
+**Ssentezo Wallet** is a platform which enables businesses and developers to collect or deliver payments to the last mile through digital platforms like mobile money.
+
+Our simple APIs make it easy to collect your payments in a few minutes. Add our web links to your website to collect payments with zero code.
+
+## Ssentezo Wallet Environment/MODE
+
+The Wallet has two types of environments in which it operates:
+
+- **LIVE**: In this environment, actual money is credited and debited from the MSISDN/phone numbers that you specify during Deposit and Withdraw operations. Real money is moved around, so be sure to have tested your application well from SANDBOX before moving into this mode.
+
+- **SANDBOX**: This is a testing environment where no actual money is collected and disbursed. You can perform transactions just like in LIVE mode, but all these are theoretical. The MSISDN/phone numbers that you specify during Deposit and Withdraw operations will neither be credited nor debited.
+
+In order to access **LIVE** mode, register at https://wallet.ssentezo.com/merchants/register.
+
+In order to access **SANDBOX** mode, register at https://devwallet.ssentezo.com/merchants/register.
+
+**NOTE**: Functionality in LIVE and SANDBOX modes is exactly the same. All that changes is the endpoint being called: `https://wallet.ssentezo.com/api` for LIVE mode and `https://devwallet.ssentezo.com/api` for SANDBOX mode.
+
+## Authorization
+
+The API utilizes **Auth Basic** authorization method. This requires you to possess valid API credentials which can be generated from the API Access menu in your Wallet Account.
+
+## Limits
+
+- API does not support entry of negative figures, exponential figures (e.g., e100), or characters while entering the amount to be transacted.
+- Only transactions between **UGX 500 to UGX 7,000,000** are allowed, provided the current wallet balance can meet your charges as defined in your Ssentezo agreement.
+- Charges are applicable to all transactions as specified in your contract for use of this service.
+
+## Supported Currencies
+
+The wallet currently supports only Uganda Shillings (UGX) for transactions.
+
+| ISO Code | Currency Name | Status |
+|----------|---------------|--------|
+| UGX | Uganda Shillings | Supported |
+
+## Setting up Authorization
+
+Using your generated **API USER** and **API KEY**. The wallet follows a standard basic auth to secure the API where the Authorization header is sent encoded to base64.
+
+**NOTE**: All requests must contain the authorization header.
+
+**NOTE**: All responses are JSON-encoded strings.
+
+**Example - How to encode the string using PHP**
+
+```php
+// Your API user
+$apiUser = '';
+
+// Your API key
+$apiKey = '';
+
+$encodedString = base64_encode($apiUser . ':' . $apiKey);
+
+$header = ['Authorization' => 'Basic '. $encodedString];
+$header = ['Content-Type' => "application/form-data"];
+```
+
+For other programming languages, follow the permitted syntax respectively.
+
+## Expected HTTP Response Codes
+
+These are the possible response codes that can be received in the course of the transaction.
+
+| Status Code | Interpretation |
+|-------------|----------------|
+| 202 | Succeeded Transaction |
+| 400 | Failed Transaction |
+| 401 | No Authorization Header |
+| 403 | Invalid Credentials |
+| 500 | An error occurred to check the message |
+| 422 | Unprocessable Entity check the request body |
+
+## Transaction Statuses
+
+These are the available transaction statuses that a transaction can have.
+
+| Status | Description |
+|--------|-------------|
+| PENDING | Transaction still pending. All transactions begin from this state. |
+| SUCCEEDED | Succeeded transaction |
+| FAILED | Failed Transaction |
+| INDETERMINATE | Status not yet determined. This can take up to 48hrs. |
+
+## API Request Responses
+
+### Successful Responses
+
+For successful requests, a JSON object response is sent back containing two keys:
+
+- **response**: This has a value of OK, indicating that the request was processed successfully.
+- **data**: This is an object that holds any relevant data that should be returned as per the endpoint called.
+
+**Example:**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "amount": 1834665,
+        "formatted": "1,834,665",
+        "currency": "UGX"
+    }
+}
+```
+
+### Erroneous Responses
+
+For erroneous responses, a JSON object response is sent back containing two keys:
+
+- **response**: This has a value of ERROR, indicating that there was an error during the course of the request.
+- **error**: This is an object that holds any relevant data to the error that just occurred. It always contains a message property that describes the error and may also have other properties relevant to that error.
+
+**Example:**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The currency field is required."
+    }
+}
+```
+
+## Checking the Account Balance
+
+**Endpoint**: `https://wallet.ssentezo.com/api/acc_balance`
+
+**Method**: `POST`
+
+The endpoint above is accessed via the POST method. It does not require a request body, but a valid authorization header is mandatory.
+
+### Form Data Parameters
+
+- `currency`
+
+**Example Request**
+
+```json
+{
+    "currency": "UGX"
+}
+```
+
+**Example success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "amount": 1834665,
+        "formatted": "1,834,665",
+        "currency": "UGX"
+    }
+}
+```
+
+**Example error response**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The currency field is required."
+    }
+}
+```
+
+## MSISDN/Phone Number Verification
+
+**Endpoint**: `https://wallet.ssentezo.com/api/msisdn-verification`
+
+**Method**: `POST`
+
+The endpoint above is accessed via the POST method.
+
+### Form Data Parameters
+
+- `msisdn`
+
+**Sample Request Body**
+
+```json
+{
+    "msisdn": "256709920188"
+}
+```
+
+**Sample success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "msisdn": "256712345678",
+        "FirstName": "John",
+        "Surname": "Doe"
+    }
+}
+```
+
+**Sample error response**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The msisdn field format is invalid."
+    }
+}
+```
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "Failed to verify the name of the holder of the MSISDN"
+    }
+}
+```
+
+## Withdrawing Funds from Your Wallet Account
+
+**Endpoint**: `https://wallet.ssentezo.com/api/withdraw`
+
+**Method**: `POST`
+
+### Form Data Parameters
+
+- `externalReference`
+- `msisdn`
+- `amount`
+- `currency`
+- `reason`
+- `name` (Optional)
+- `success_callback` (Optional)
+- `failure_callback` (Optional)
+
+**Example request body**
+
+```php
+// Example request body
+
+$requestBody => [
+    'externalReference' => '{your external reference}', // This should always be unique. Duplicate references will cause an error
+    'msisdn' => 256770691484,
+    'amount' => 2000,
+    'currency' => 'UGX', // should be a valid ISO code and this currency should be supported by your wallet
+    'reason' => 'Your reason for the transaction',
+    'name' => '{Optional Field, You may send  the name of the recipient}',
+    'success_callback' => 'https://yourapp.com/my-success-callback (Optional)', // A POST endpoint the wallet will call when a transaction is successful
+    'failure_callback' => 'https://yourapp.com/my-failure-callback (Optional)', // A POST endpoint the wallet will call when a transaction has failed
+];
+
+// With PHP you can use curl, Http Request 2, or Guzzle Http to perform this request.
+```
+
+### Description
+
+- **externalReference**: This is the string or number or reference that you use to refer to your transaction in your own application. It supports (250) characters. This should always be UNIQUE
+- **msisdn**: This is a phone number formatted to international standard
+- **amount**: The amount of money being transacted. It should not be formatted or contain any non-numeric characters. Amount should be between UGX 500 to UGX 7000000
+- **currency**: Valid ISO format of the currency. Currently UGX is the only currency supported for transactions
+- **reason**: Your reason for the transaction
+- **name**: Name of the recipient
+- **success_callback**: A POST endpoint the wallet will call when a transaction is successful
+- **failure_callback**: A POST endpoint the wallet will call when a transaction has failed
+
+**Example success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "transactionStatus": "PENDING",
+        "ssentezoWalletReference": "f245ddac-1622-4dad-9a94-4e289bb6b8a4",
+        "financialTransactionId": "b997c60c6f445185fcd9a3a595533734b997c60c6f445185fcd9a3a595533734"
+    }
+}
+```
+
+### Description
+
+- **transactionStatus**: Status of the transaction in our system. All transactions begin from the PENDING status
+- **ssentezoWalletReference**: A unique id that we use to identify the transaction in our system
+- **financialTransactionId**: A unique id that identifies your transaction at the network provider eg MTN/Airtel
+
+**NOTE**: The financialTransactionId is the transaction reference from the Network service provider
+
+**Example error response**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "code": "UPPER_CEILING_BREACH", // Brief overview of what the error is about
+        "message": "Maximum transaction amount is UGX 7,000,000" // A description of the error that occurred
+    }
+}
+```
+
+**Example error response (Validation)**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The given data was invalid.",
+        "errors": {
+            "amount": ["The amount field must be at least 500."],
+            "msisdn": ["The msisdn field is required."],
+            "externalReference": [
+                "The external reference has already been taken."
+            ]
+        }
+    }
+}
+```
+
+## Collecting Money into the Wallet (Deposit)
+
+**Endpoint**: `https://wallet.ssentezo.com/api/deposit`
+
+**Method**: `POST`
+
+### Form Data Parameters
+
+- `externalReference`
+- `msisdn`
+- `amount`
+- `currency`
+- `reason`
+- `name` (Optional)
+- `success_callback` (Optional)
+- `failure_callback` (Optional)
+
+**Example - Setting up a collection request**
+
+```php
+// Example request body
+
+$requestBody => [
+    'amount' => 1000,
+    'msisdn' => 256770691484,
+    'reason' => 'Your reason for the transaction',
+    'currency' => 'UGX', // should be a valid ISO code and this currency should be supported by your wallet
+    'name' => 'John Doe (Optional)', // A person's name you are collecting from
+    'success_callback' => 'https://yourapp.com/my-success-callback (Optional)', // A POST endpoint the wallet will call when a transaction is successful
+    'failure_callback' => 'https://yourapp.com/my-failure-callback (Optional)', // A POST endpoint the wallet will call when a transaction has failed
+];
+
+// With PHP you can use curl, Http Request 2, or Guzzle Http to perform this request.
+```
+
+**Example success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "transactionStatus": "PENDING",
+        "ssentezoWalletReference": "f245ddac-1622-4dad-9a94-4e289bb6b8a4",
+        "financialTransactionId": "b997c60c6f445185fcd9a3a595533734b997c60c6f445185fcd9a3a595533734"
+    }
+}
+```
+
+**Example error response**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "code": "UPPER_CEILING_BREACH", // Brief overview of what the error is about
+        "message": "Maximum transaction amount is UGX 7,000,000" // A description of the error that occurred
+    }
+}
+```
+
+**Example error response (Validation)**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The given data was invalid.",
+        "errors": {
+            "amount": ["The amount field must be at least 500."],
+            "msisdn": ["The msisdn field is required."],
+            "externalReference": [
+                "The external reference has already been taken."
+            ]
+        }
+    }
+}
+```
+
+**NOTE**: A PENDING status with an HTTP status code of 202 means the transaction has been initiated and the benefactor must enter their Mobile Money Pin. Once the transaction has succeeded, the callback endpoint is then hit using a POST request to notify you.
+
+## Checking for a Transaction Status
+
+**Endpoint**: `https://wallet.ssentezo.com/api/get_status/{externalReference}`
+
+**Method**: `POST`
+
+### URL Parameters
+
+- `externalReference`
+
+**Sample success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "transactionStatus": "SUCCEEDED",
+        "ssentezoWalletReference": "3181ead4-eff9-4b9b-b926-53b41e632ca5",
+        "externalReference": "rfg54rj59033w4672326hi45h6j6456",
+        "financialTransactionId": "QkK0UVtkMlCZN1ZEuKVv4NU5l2sFA1uO82fb7ef5f6a2530bc5c2118b34620b5a",
+        "amount": 3000,
+        "reason": "Sending money to someone",
+        "currency": "UGX",
+        "msisdn": "256770691484",
+        "transactionTime": "2024-04-24T16:24:58.000000Z"
+    }
+}
+```
+
+## Receiving a Transaction Status Notification
+
+If you would like your system to be notified immediately after a transaction status changes from the PENDING status into either SUCCEEDED or FAILED statuses, you can specify callback URLs that we shall hit to notify your system.
+
+When making a deposit or withdraw request, as part of your request data, you can pass two parameters:
+
+- `success_callback`
+- `failure_callback`
+
+These should contain valid URLs that will be called using a POST request to your system when a transaction either succeeds or fails. Check the documentation section for DEPOSIT or WITHDRAW for an example.
+
+**Sample of POST data sent using the success callback**
+
+```json
+{
+    "response": "OK", // Indicates a successful response
+    "data": {
+        "transactionStatus": "SUCCEEDED", // Indicates the status of the transaction (SUCCEEDED/FAILED)
+        "ssentezoWalletReference": "f245ddac-1622-4dad-9a94-4e289bb6b8a4",
+        "externalReference": "16011650463271",
+        "financialTransactionId": "f245ddac-1622-4dad-9a94-4e289bb6b8a4-f245ddac-1622-4dad-9a94-4e289bb6b8a4"
+    }
+}
+```
+
+**NOTE 1**: Please ensure that you provide valid and resolvable URLs to your system. If our system is to resolve your endpoint within 5 seconds, the request will timeout. In such cases, you will need to check the transaction status as described above.
+
+**NOTE 2**: Please ensure that this endpoint is publicly accessible and does not require any authentication or authorization. This is because our system is decoupled from your implementation, and we rely on unrestricted callback requests to function correctly.
+
+## Request Bank Transfer (Push Money to the Bank)
+
+Two Endpoints: In order to Push money to the bank, two endpoints are required.
+
+1. **Get list of banks** - This returns a list of all banks the we currently support. The bank id will be required in when making the actual request to transfer money to the bank.
+
+2. **Request bank transfer** - After you have a list of the banks, select the bank you would like to send money to, along side with other required parameters.
+
+### 1) Get Supported Banks
+
+**Endpoint**: `https://wallet.ssentezo.com/api/push-to-bank/get-banks`
+
+**Method**: `POST`
+
+#### Form Data Parameters
+
+Not required
+
+**Example success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "banks": [
+            {
+                "id": 3,
+                "bank_name": "Equity",
+                "address": "Church House",
+                "swift_code": "QW2456"
+            },
+            {
+                "id": 4,
+                "bank_name": "Stanbic Bank",
+                "address": "Church House",
+                "swift_code": "QW2456"
+            },
+            {
+                "id": 5,
+                "bank_name": "Housing Finance Bank",
+                "address": "Ntinda",
+                "swift_code": "QWE34E"
+            }
+        ]
+    }
+}
+```
+
+### 2) Request Bank Transfer
+
+**Endpoint**: `https://wallet.ssentezo.com/api/push-to-bank/request-bank-transfer`
+
+**Method**: `POST`
+
+#### Form Data Parameters
+
+- `external_reference`
+- `bank_id`
+- `account_name`
+- `account_number`
+- `amount`
+- `reason`
+
+```php
+// Example request body
+
+$requestBody => [
+    'external_reference' => c734d323-8c1c-4160-8649-4df22443aa57, // A unique identifier that you provide to our system that will be used to identify your transaction
+    'bank_id' => 3, // The id of one of the banks that we support. It's obtained from the get-banks endpoint
+    'account_name' => 'John Doe', // The name of the bank account you would like the funds to be transfered to
+    'account_number' => '044653389534563', // The bank account number you would like the funds to be transfered to
+    'amount' => '50000', // The amount of money you would like to transfer. Minimum amount is UGX 50,000
+    'reason' => 'Pushing my money to the bank', // A narration about the transaction.
+];
+
+// With PHP you can use curl, Http Request 2, or Guzzle Http to perform this request.
+```
+
+**Example success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "transactionStatus": "PENDING",
+        "ssentezoWalletReference": "21537d54-bcd1-44a5-8614-717e093483ac",
+        "externalReference": "82c7d1d6-850b-4e14-a0b7-5379058b17be"
+    }
+}
+```
+
+**Example error response**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "Minimum transaction amount is UGX 50,000"
+    }
+}
+```
+
+**Example error response (Validation)**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The given data was invalid.",
+        "errors": {
+            "bank_id": [
+                "The bank id field is required."
+            ],
+            "account_name": [
+                "The account name field is required."
+            ],
+            "account_number": [
+                "The account number field is required."
+            ],
+            "amount": [
+                "The amount field is required."
+            ]
+        }
+    }
+}
+```
+
+### 3) Check Bank Transfer Status
+
+**Endpoint**: `https://wallet.ssentezo.com/api/push-to-bank/check-bank-transfer-status`
+
+**Method**: `POST`
+
+#### Form Data Parameters
+
+- `external_reference`
+
+```php
+// Example request body
+
+$requestBody => [
+    'external_reference' => c734d323-8c1c-4160-8649-4df22443aa57, // A unique identifier that you provide to our system that will be used to identify your transaction
+];
+```
+
+**Example success response**
+
+```json
+{
+    "response": "OK",
+    "data": {
+        "transactionStatus": "SUCCEEDED",
+        "ssentezoWalletReference": "51c3d7b3-e70a-4016-8839-fe27a5c610fd",
+        "externalReference": "c734d323-8c1c-4160-8649-4df22443aa57",
+        "amount": 85000,
+        "transactionTime": "2024-09-30T12:40:48.000000Z"
+    }
+}
+```
+
+**Example error response (Validation)**
+
+```json
+{
+    "response": "ERROR",
+    "error": {
+        "message": "The given data was invalid.",
+        "errors": {
+            "external_reference": [
+                "The selected external reference is invalid."
+            ]
+        }
+    }
+}
+```
+
+---
+
+That's it. Go build something great 💪🏼

ocs4dev.py

@@ -1,946 +1,882 @@
+"""
+ocs4dev.py — Fintech API Integration Assistant
+================================================
+A RAG-powered chatbot for payment API integrations: Stripe, PayPal,
+MTN MoMo, Pesapal, Sentezo, Square, Adyen & more.
+Uses a local FAISS vector store (no cloud DB required) and supports
+multiple LLM providers: Local Qwen, OpenAI, Anthropic, Google Gemini.
+"""
+
 import os
-import glob
+import threading
+import warnings
 import gradio as gr
 from dotenv import load_dotenv
-from typing import List, Dict, Any, Tuple, Optional
-import uuid
+from typing import List, Tuple, Generator
+
 import torch
-from huggingface_hub import hf_hub_download
-import warnings
 warnings.filterwarnings("ignore")
 
-# Updated imports to avoid deprecation warnings
-from langchain_community.document_loaders import DirectoryLoader, TextLoader
-from langchain_text_splitters import CharacterTextSplitter
-from langchain_core.documents import Document
-from langchain_core.messages import HumanMessage, AIMessage
+# LangChain core (LCEL — works in LangChain 1.x)
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
 from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
-from langchain_core.runnables import RunnablePassthrough
 from langchain_core.output_parsers import StrOutputParser
-
-# Modern LangChain chains (replacing deprecated ConversationalRetrievalChain)
-from langchain.chains import create_history_aware_retriever, create_retrieval_chain
-from langchain.chains.combine_documents import create_stuff_documents_chain
+from langchain_core.runnables import RunnablePassthrough, RunnableLambda
 
 # Multi-provider LLM support
-from langchain_openai import OpenAIEmbeddings, ChatOpenAI
+from langchain_openai import ChatOpenAI
 from langchain_anthropic import ChatAnthropic
 from langchain_google_genai import ChatGoogleGenerativeAI
 
-# Supabase integration (pre-configured by admin)
-from langchain_community.vectorstores import SupabaseVectorStore
-from supabase.client import Client, create_client
+# Local vector store (FAISS replaces Supabase)
+from langchain_community.vectorstores import FAISS
+from langchain_huggingface import HuggingFaceEmbeddings
 
-# Hugging Face Transformers for local Qwen model
-from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
-import accelerate
+# Local model inference
+from transformers import (
+    AutoTokenizer,
+    AutoModelForCausalLM,
+    TextIteratorStreamer,
+)
 
-# Configuration
-DEFAULT_MODEL = "Qwen/Qwen2.5-Coder-7B-Instruct-AWQ"  # Quantized version for better performance
-TOP_K_DOCUMENTS = 5
+# Load environment variables
+load_dotenv(override=True)
 
-# Model configurations for each provider
+# ─────────────────────────────────────────────────────────────────────────────
+# Constants
+# ─────────────────────────────────────────────────────────────────────────────
+LOCAL_MODEL_ID  = "Qwen/Qwen2.5-Coder-1.5B-Instruct"   # ~3 GB RAM (FP16) - Best for CPU/HF Spaces
+FAISS_INDEX_DIR = "./faiss_index"
+EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+TOP_K           = 5
+
+# ─────────────────────────────────────────────────────────────────────────────
+# System Prompt — the soul of ocs4dev
+# ─────────────────────────────────────────────────────────────────────────────
+SYSTEM_PROMPT_CORE = """\
+You are **ocs4dev** — a senior-level fintech integration engineer who specialises 
+in payment APIs and financial infrastructure: Stripe, PayPal, Square, Adyen, 
+MTN MoMo, Pesapal, Sentezo (Ssentezo), Airtel Money, Flutterwave, Paystack, 
+Razorpay, Mollie, and related platforms worldwide.
+
+You are NOT a generic assistant. You are the developer's *pair-programming partner* 
+who has shipped production payment integrations across multiple continents and 
+payment rails — cards, mobile money, bank transfers, crypto on-ramps, and more.
+
+═══════════════════════════════════════════════════════════════
+                          CORE RULES
+═══════════════════════════════════════════════════════════════
+
+1. **CODE FIRST** — Every response that involves "how to" MUST include working, 
+   copy-paste-ready code. Default to Python (requests / aiohttp), but switch to 
+   whatever language the developer is using if you can infer it from context.
+   Always include:
+   • Full imports
+   • Proper error handling (try/except with specific exceptions)
+   • Environment variable usage for secrets (never hardcode keys)
+   • Comments explaining non-obvious logic
+   • Both success and failure response handling
+
+2. **ASK BEFORE YOU ASSUME** — When a developer's question is ambiguous or could 
+   lead to multiple valid approaches, ASK 1-3 targeted follow-up questions BEFORE 
+   diving into a full answer. Examples:
+   • "Are you building this for a single merchant or a marketplace with sub-accounts?"
+   • "Which environment — sandbox or production? The auth flow differs."
+   • "Do you need this to be synchronous or are you handling callbacks/webhooks?"
+   
+   However, if the question is clear and specific, answer directly — don't ask 
+   unnecessary questions just to seem thorough.
+
+3. **GO BEYOND THE DOCS** — If the retrieved documentation doesn't cover what the 
+   developer needs, don't just say "this isn't supported". Instead:
+   • Explain clearly what the API does and doesn't support
+   • Propose a concrete architecture/workaround to achieve the goal
+   • Show code for the workaround (e.g., building a virtual account ledger 
+     on top of a single-wallet API, or combining multiple providers)
+   • Flag the trade-offs and gotchas of the workaround
+
+4. **THINK IN SYSTEMS** — When a question implies a bigger architectural decision, 
+   address the architecture:
+   • Database schema snippets when relevant
+   • Webhook/callback handling patterns
+   • Idempotency and retry strategies
+   • Reconciliation approaches
+   • Security considerations (HMAC verification, IP whitelisting, PCI compliance, etc.)
+
+5. **FINTECH CONTEXT** — You deeply understand:
+   • Multiple payment rails: cards, mobile money, bank transfers, wallets, BNPL
+   • Network timeouts and eventual consistency — design for both
+   • Sandbox vs production environments often behave differently
+   • Currency handling (zero-decimal currencies like UGX/JPY, 2-decimal like USD/EUR)
+   • Regulatory requirements (PCI-DSS, KYC/AML, SCA/3DS, transaction limits)
+   • Common failure modes: insufficient funds, expired tokens, declined cards, 
+     callback URL not reachable, rate limiting, idempotency conflicts
+
+6. **FORMAT FOR DEVELOPERS** — Structure your responses for maximum scanability:
+   • Use headers (##) to separate logical sections
+   • Use fenced code blocks with language tags (```python, ```bash, ```json, ```sql)
+   • Use tables for comparing options, endpoints, or error codes
+   • Use bullet points for lists, numbered steps for sequences
+   • Bold key terms, endpoint paths, and important warnings
+   • Keep explanatory text concise — developers read code, not essays
+
+7. **BE OPINIONATED** — Don't present 5 options without a recommendation. 
+   State your preferred approach and WHY, then mention alternatives briefly. 
+   Example: "I'd go with webhooks over polling here because most payment 
+   providers deliver callbacks reliably in production, and polling status 
+   endpoints adds unnecessary load and latency."
+
+8. **WARN ABOUT PITFALLS** — Proactively mention common mistakes:
+   • ⚠️ warnings for things that will break in production
+   • 💡 tips for things that save debugging time
+   • 🔒 security notes when handling payment data
+"""
+
+def build_system_prompt(context: str) -> str:
+    """Build the full system prompt with retrieved documentation context."""
+    doc_section = (
+        f"\n═══════════════════════════════════════════════════════════════\n"
+        f"                    RETRIEVED DOCUMENTATION\n"
+        f"═══════════════════════════════════════════════════════════════\n\n"
+        f"{context}\n\n"
+        f"Use the documentation above to ground your answers with specific endpoints, \n"
+        f"headers, and request/response formats. If the docs don't fully cover the \n"
+        f"developer's question, supplement with your deep knowledge of these APIs \n"
+        f"and clearly distinguish between doc-sourced facts and your recommendations."
+    ) if context else (
+        "\nNo specific documentation was retrieved for this query. "
+        "Rely on your broad knowledge of fintech APIs, but clearly state "
+        "when you're working from general knowledge rather than specific docs."
+    )
+    return SYSTEM_PROMPT_CORE + doc_section
+
+
+def build_local_system_prompt(context: str) -> str:
+    """Shorter system prompt optimised for the local 1.5B model's context window."""
+    return (
+        "You are ocs4dev, a senior fintech integration engineer specializing in "
+        "payment APIs (Stripe, PayPal, MTN MoMo, Pesapal, Sentezo, Square, Adyen, and more).\n\n"
+        "Rules:\n"
+        "- Always include working code examples with error handling\n"
+        "- Ask follow-up questions when the intent is unclear\n"
+        "- If an API doesn't support something, propose a workaround with code\n"
+        "- Use Python by default, fenced code blocks with language tags\n"
+        "- Be concise but complete — developers read code, not essays\n"
+        "- Warn about common pitfalls with ⚠️\n\n"
+        f"Retrieved docs:\n{context if context else 'No docs retrieved — use general knowledge.'}"
+    )
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Model configurations — March 2026
+# ─────────────────────────────────────────────────────────────────────────────
 MODEL_CONFIGS = {
     "openai": {
-        "budget": "gpt-4o-mini",
-        "premium": "o4-mini"
+        "budget":  "gpt-5-mini",
+        "premium": "gpt-5.2",
     },
     "anthropic": {
-        "budget": "claude-3-5-sonnet-20241022",
-        "premium": "claude-4-sonnet-20250109"
+        "budget":  "claude-haiku-4-5",
+        "premium": "claude-opus-4-6",
     },
     "google": {
-        "budget": "gemini-2.0-flash-exp",
-        "premium": "gemini-2.0-flash-thinking-exp-1219"
-    }
+        "budget":  "gemini-2.0-flash",
+        "premium": "gemini-2.5-pro",
+    },
+}
+
+MODEL_DISPLAY = {
+    "openai": {
+        "budget":  "GPT-5 mini",
+        "premium": "GPT-5.2",
+    },
+    "anthropic": {
+        "budget":  "Claude Haiku 4.5",
+        "premium": "Claude Opus 4.6",
+    },
+    "google": {
+        "budget":  "Gemini 2.0 Flash",
+        "premium": "Gemini 2.5 Pro",
+    },
 }
 
-# Load environment variables
-load_dotenv(override=True)
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Assistant Class
+# ─────────────────────────────────────────────────────────────────────────────
 class OCS4DevAssistant:
     def __init__(self):
-        self.setup_environment()
-        self.setup_local_model()
-        self.setup_vector_store()
-        self.chat_history = []
-        self.current_provider = "local"
-        self.current_model_tier = "budget"
-
-    def setup_environment(self):
-        """Setup environment variables - only Supabase required for vector store"""
-        # Supabase credentials (pre-configured by admin)
-        self.supabase_url = os.getenv('SUPABASE_URL')
-        self.supabase_key = os.getenv('SUPABASE_SERVICE_KEY')
-
-        if not self.supabase_url or not self.supabase_key:
-            print("⚠️  Supabase not configured. Vector search will be disabled.")
-            self.supabase_url = None
-            self.supabase_key = None
-
-        # API keys (provided by users in UI)
-        self.openai_api_key = os.getenv('OPENAI_API_KEY')
-        self.anthropic_api_key = os.getenv('ANTHROPIC_API_KEY')
-        self.google_api_key = os.getenv('GOOGLE_API_KEY')
-
-    def setup_local_model(self):
-        """Initialize the local Qwen2.5-Coder model"""
-        print("🚀 Loading Qwen2.5-Coder-7B-Instruct (AWQ quantized)...")
+        self._setup_environment()
+        self._setup_vector_store()
+        # Local model is lazy-loaded on first use — keeps startup fast
+        self._local_tokenizer = None
+        self._local_model     = None
+        self._model_loaded    = False
+        self._model_loading   = False
+        self._model_lock      = threading.Lock()
+
+    # ── Environment ──────────────────────────────────────────────────────────
+    def _setup_environment(self):
+        self.openai_key    = os.getenv("OPENAI_API_KEY", "")
+        self.anthropic_key = os.getenv("ANTHROPIC_API_KEY", "")
+        self.google_key    = os.getenv("GOOGLE_API_KEY", "")
+
+    # ── Vector Store ─────────────────────────────────────────────────────────
+    def _setup_vector_store(self):
+        """Load local FAISS index built by build_index.py"""
+        if not os.path.exists(FAISS_INDEX_DIR):
+            print(f"⚠️  FAISS index not found at '{FAISS_INDEX_DIR}'.")
+            print("    Run  python build_index.py  to create it.")
+            self.vector_store = None
+            return
 
         try:
-            # Check if CUDA is available
-            device = "cuda" if torch.cuda.is_available() else "cpu"
-            print(f"Using device: {device}")
-
-            # Load tokenizer
-            self.tokenizer = AutoTokenizer.from_pretrained(
-                DEFAULT_MODEL,
-                trust_remote_code=True
-            )
-
-            # Load quantized model
-            self.local_model = AutoModelForCausalLM.from_pretrained(
-                DEFAULT_MODEL,
-                torch_dtype=torch.float16 if device == "cuda" else torch.float32,
-                device_map="auto" if device == "cuda" else None,
-                trust_remote_code=True,
-                low_cpu_mem_usage=True
+            print("🔄 Loading FAISS vector index...")
+            self.embeddings   = HuggingFaceEmbeddings(
+                model_name=EMBEDDING_MODEL,
+                model_kwargs={"device": "cpu"},
+                encode_kwargs={"normalize_embeddings": True},
             )
-
-            # Create pipeline for easier inference
-            self.local_pipeline = pipeline(
-                "text-generation",
-                model=self.local_model,
-                tokenizer=self.tokenizer,
-                torch_dtype=torch.float16 if device == "cuda" else torch.float32,
-                device_map="auto" if device == "cuda" else None,
-                max_new_tokens=1024,
-                temperature=0.3,
-                do_sample=True,
-                pad_token_id=self.tokenizer.eos_token_id
+            self.vector_store = FAISS.load_local(
+                FAISS_INDEX_DIR,
+                self.embeddings,
+                allow_dangerous_deserialization=True,
             )
-
-            print("✅ Local Qwen2.5-Coder model loaded successfully!")
-
+            print("✅ FAISS vector store loaded!")
         except Exception as e:
-            print(f"❌ Error loading local model: {e}")
-            print("Model will be downloaded on first use...")
-            self.local_model = None
-            self.local_pipeline = None
-            self.tokenizer = None
-
-    def setup_vector_store(self):
-        """Initialize vector store for retrieval only"""
-        if not self.supabase_url or not self.supabase_key:
+            print(f"❌ Failed to load FAISS index: {e}")
             self.vector_store = None
-            print("⚠️  Supabase credentials not found. Vector store disabled.")
-            print("    To enable, set SUPABASE_URL and SUPABASE_SERVICE_KEY environment variables.")
-            return
 
-        try:
-            self.supabase_client = create_client(self.supabase_url, self.supabase_key)
+    # ── Local Model (lazy) ───────────────────────────────────────────────────
+    def respond(
+        self,
+        message:       str,
+        history:       list,
+        provider:      str,
+        tier:          str,
+        openai_key:    str,
+        anthropic_key: str,
+        google_key:    str,
+    ) -> Generator[str, None, None]:
+        """
+        Chat handler for gr.ChatInterface — yield plain string chunks.
+        ChatInterface manages history format automatically (no dict wrangling here).
+        """
+        if not message.strip():
+            return
 
-            # Test connection and check if data exists
-            response = self.supabase_client.table("fintech_api_docs").select("count").execute()
-            doc_count = len(response.data) if response.data else 0
+        # ── Get FAISS retrieval context ───────────────────────────────────────
+        context = self.get_context(message)
+        system_content = build_system_prompt(context)
 
-            if doc_count == 0:
-                print("⚠️  Supabase connected but no documents found in the database.")
-                print("    Run the populate_supabase.py tool to add documents first.")
-            else:
-                print(f"✅ Supabase connected! Documents available: {doc_count}")
-
-            # Use OpenAI embeddings for retrieval
-            # Note: This requires a valid OpenAI API key for similarity search
-            if self.openai_api_key:
-                self.embeddings = OpenAIEmbeddings(
-                    model="text-embedding-3-small",
-                    openai_api_key=self.openai_api_key
-                )
-            else:
-                print("⚠️  No OpenAI API key found. Using fallback embeddings.")
-                print("    For best results, provide an OpenAI API key.")
-                # Fallback: still create embeddings object but searches may not work properly
-                self.embeddings = OpenAIEmbeddings(
-                    model="text-embedding-3-small",
-                    openai_api_key="dummy-key"
-                )
+        # ── Local model path ─────────────────────────────────────��────────────
+        if provider == "local":
+            yield from self._local_respond(message, history, system_content)
+            return
 
-            # Initialize vector store as retriever only
-            self.vector_store = SupabaseVectorStore(
-                client=self.supabase_client,
-                embedding=self.embeddings,
-                table_name="fintech_api_docs",
-                query_name="match_documents"
+        # ── API model path ────────────────────────────────────────────────────
+        key_map = {
+            "openai":    openai_key    or self.openai_key,
+            "anthropic": anthropic_key or self.anthropic_key,
+            "google":    google_key    or self.google_key,
+        }
+        api_key = key_map.get(provider, "")
+        if not api_key:
+            yield (
+                f"❌ No API key for **{provider}**.\n\n"
+                f"Open ⚙️ **Settings → API Keys** and enter your {provider.title()} key."
             )
+            return
 
-            print("✅ Vector store initialized as retriever!")
+        try:
+            llm = self._get_llm(provider, tier, api_key)
+
+            # Build message list: system + history + new user message
+            # Direct stream — avoids LCEL pipeline blocking Gradio's async loop
+            messages = [SystemMessage(content=system_content)]
+            for entry in history:
+                role    = entry.get("role", "user")    if isinstance(entry, dict) else getattr(entry, "role", "user")
+                content = entry.get("content") or ""   if isinstance(entry, dict) else getattr(entry, "content", "")
+                content = str(content)
+                if role == "user":
+                    messages.append(HumanMessage(content=content))
+                elif role == "assistant":
+                    messages.append(AIMessage(content=content))
+            messages.append(HumanMessage(content=message))
+
+            response = ""
+            for chunk in llm.stream(messages):
+                response += chunk.content
+                yield response
 
         except Exception as e:
-            print(f"❌ Vector store setup failed: {e}")
-            print("    Ensure your Supabase table 'fintech_api_docs' exists with proper schema.")
-            print("    Run the populate_supabase.py tool to set up the database.")
-            self.vector_store = None
-
-    def get_llm_instance(self, provider: str, tier: str, api_key: Optional[str] = None):
-        """Get LLM instance based on provider and tier"""
-        if provider == "local":
-            return self.local_pipeline
-
-        if not api_key:
-            raise ValueError(f"API key required for {provider}")
+            yield f"❌ Error calling {provider} API: {str(e)}"
+
+    def _local_respond(
+        self, message: str, history: list, system_content: str
+    ) -> Generator[str, None, None]:
+        """Stream response from the local Qwen model."""
+        if not self._load_local_model():
+            yield (
+                "⚠️ **Local model failed to load.**\n\n"
+                "This usually means the model weights need to be downloaded first, "
+                "or a quantization library (`auto-gptq`, `bitsandbytes`) is missing.\n\n"
+                "Try selecting **Google / OpenAI / Anthropic** instead and entering an API key."
+            )
+            return
 
-        model_name = MODEL_CONFIGS[provider][tier]
+        msgs = [{"role": "system", "content": system_content}]
+        for entry in history[-8:]:
+            role    = entry.get("role", "user")  if isinstance(entry, dict) else getattr(entry, "role", "user")
+            content = entry.get("content") or "" if isinstance(entry, dict) else getattr(entry, "content", "")
+            content = str(content)
+            if role in ("user", "assistant") and content:
+                msgs.append({"role": role, "content": content})
+        msgs.append({"role": "user", "content": message})
 
-        if provider == "openai":
-            return ChatOpenAI(
-                model=model_name,
-                temperature=0.3,
-                max_tokens=1000,
-                openai_api_key=api_key
+        try:
+            formatted = self._local_tokenizer.apply_chat_template(
+                msgs, tokenize=False, add_generation_prompt=True
             )
-        elif provider == "anthropic":
-            return ChatAnthropic(
-                model=model_name,
-                temperature=0.3,
-                max_tokens=1000,
-                anthropic_api_key=api_key
+            inputs    = self._local_tokenizer(formatted, return_tensors="pt")
+            input_ids = inputs["input_ids"]
+            mask      = inputs["attention_mask"]
+
+            streamer  = TextIteratorStreamer(
+                self._local_tokenizer,
+                skip_prompt=True,
+                skip_special_tokens=True,
             )
-        elif provider == "google":
-            return ChatGoogleGenerativeAI(
-                model=model_name,
-                temperature=0.3,
-                max_output_tokens=1000,
-                google_api_key=api_key
-            )
-        else:
-            raise ValueError(f"Unsupported provider: {provider}")
-
-    def generate_local_response(self, prompt: str, context: str = "") -> str:
-        """Generate response using local Qwen model"""
-        if not self.local_pipeline or not self.tokenizer:
-            # Try to load model if not loaded
-            self.setup_local_model()
-
-        if not self.local_pipeline or not self.tokenizer:
-            return "❌ Local model not available. Please use API providers or check your setup."
-
-        # Format prompt for Qwen2.5-Coder
-        system_prompt = f"""You are ocs4dev, a specialized fintech API integration assistant. You help developers integrate fintech APIs including MTN MoMo, Pesapal, and Sentezo.
-
-Your expertise includes:
-- API authentication and security
-- Code examples and implementation
-- Error handling and debugging
-- Testing and best practices
-- Payment gateway integration
-
-Always provide practical, code-focused responses with examples.
-
-Context: {context}"""
-
-        messages = [
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": prompt}
-        ]
-
-        # Apply chat template
-        formatted_prompt = self.tokenizer.apply_chat_template(
-            messages,
-            tokenize=False,
-            add_generation_prompt=True
-        )
-
-        try:
-            # Generate response
-            outputs = self.local_pipeline(
-                formatted_prompt,
-                max_new_tokens=1024,
+            gen_kwargs = dict(
+                input_ids=input_ids,
+                attention_mask=mask,
+                streamer=streamer,
+                max_new_tokens=16384,
                 temperature=0.3,
                 do_sample=True,
-                pad_token_id=self.tokenizer.eos_token_id
+                pad_token_id=self._local_tokenizer.eos_token_id,
             )
+            thread = threading.Thread(target=self._local_model.generate, kwargs=gen_kwargs)
+            thread.start()
 
-            # Extract generated text
-            response = outputs[0]["generated_text"]
-
-            # Remove the input prompt from response
-            if formatted_prompt in response:
-                response = response.replace(formatted_prompt, "").strip()
+            accumulated = ""
+            for token in streamer:
+                accumulated += token
+                yield accumulated
 
-            return response
+            thread.join()
 
         except Exception as e:
-            return f"❌ Error generating response: {str(e)}"
-
-    def get_retrieval_context(self, query: str) -> str:
-        """Get relevant context from vector store"""
+            yield f"❌ Local model error: {str(e)}"
+
+    def _load_local_model(self) -> bool:
+        """Attempt to load Qwen2.5-Coder-3B-Int4. Returns True on success."""
+        if self._model_loaded:
+            return True
+
+        with self._model_lock:
+            if self._model_loaded:   # Double-checked locking
+                return True
+            if self._model_loading:
+                return False
+
+            self._model_loading = True
+            print(f"\n🚀 Loading local model: {LOCAL_MODEL_ID}...")
+            try:
+                device = "cuda" if torch.cuda.is_available() else "cpu"
+                print(f"   Device: {device}")
+
+                self._local_tokenizer = AutoTokenizer.from_pretrained(
+                    LOCAL_MODEL_ID,
+                    trust_remote_code=True,
+                )
+                self._local_model = AutoModelForCausalLM.from_pretrained(
+                    LOCAL_MODEL_ID,
+                    dtype=torch.float16 if device == "cuda" else torch.float32,
+                    device_map="auto" if device == "cuda" else None,
+                    trust_remote_code=True,
+                    low_cpu_mem_usage=True,
+                )
+                if device == "cpu":
+                    self._local_model = self._local_model.to("cpu")
+
+                self._model_loaded  = True
+                self._model_loading = False
+                print("✅ Local model loaded!")
+                return True
+
+            except Exception as e:
+                print(f"❌ Failed to load local model: {e}")
+                self._model_loading = False
+                return False
+
+    # ── Retrieval ─────────────────────────────────────────────────────────────
+    def get_context(self, query: str) -> str:
+        """Return relevant doc chunks from FAISS as a string."""
         if not self.vector_store:
             return ""
-
         try:
-            docs = self.vector_store.similarity_search(query, k=TOP_K_DOCUMENTS)
-            context = "\n\n".join([doc.page_content for doc in docs])
-            return context
+            docs = self.vector_store.similarity_search(query, k=TOP_K)
+            return "\n\n---\n\n".join(
+                f"[{d.metadata.get('provider', 'Docs')}]\n{d.page_content}"
+                for d in docs
+            )
         except Exception as e:
-            print(f"Error retrieving context: {e}")
+            print(f"Retrieval error: {e}")
             return ""
 
-    def create_retrieval_chain(self, llm, provider: str):
-        """Create retrieval chain for API models"""
+    def get_retriever(self):
+        """Return a LangChain retriever from the FAISS store."""
         if not self.vector_store:
             return None
-
-        # Create retriever
-        retriever = self.vector_store.as_retriever(
+        return self.vector_store.as_retriever(
             search_type="similarity",
-            search_kwargs={"k": TOP_K_DOCUMENTS}
+            search_kwargs={"k": TOP_K},
         )
 
-        # Contextualize question prompt
-        contextualize_q_system_prompt = """
-        You are ocs4dev, a fintech API integration expert. Given a chat history and the latest user question
-        which might reference context in the chat history, formulate a standalone question
-        which can be understood without the chat history. Focus on fintech API integration.
+    # ── LLM Factory ──────────────────────────────────────────────────────────
+    def _get_llm(self, provider: str, tier: str, api_key: str):
+        """Return a streaming-capable LangChain LLM instance."""
+        model_id = MODEL_CONFIGS[provider][tier]
+        common   = {"temperature": 0.3, "streaming": True}
 
-        Do NOT answer the question, just reformulate it if needed and otherwise return it as is.
+        if provider == "openai":
+            return ChatOpenAI(
+                model=model_id,
+                openai_api_key=api_key,
+                **common,
+            )
+        elif provider == "anthropic":
+            return ChatAnthropic(
+                model=model_id,
+                max_tokens=128000,
+                anthropic_api_key=api_key,
+                **common,
+            )
+        elif provider == "google":
+            return ChatGoogleGenerativeAI(
+                model=model_id,
+                google_api_key=api_key,
+                **common,
+            )
+        raise ValueError(f"Unknown provider: {provider}")
+
+    # ── RAG Chain (LCEL) ──────────────────────────────────────────────────────
+    def _build_rag_chain(self, llm):
         """
+        Build a history-aware RAG chain using LCEL.
+        Compatible with LangChain 1.x (old langchain.chains removed in v1).
+        """
+        retriever = self.get_retriever()
+        if not retriever:
+            return None
 
-        contextualize_q_prompt = ChatPromptTemplate.from_messages([
-            ("system", contextualize_q_system_prompt),
+        # Step 1 — reformulate the question given chat history
+        condense_prompt = ChatPromptTemplate.from_messages([
+            ("system",
+             "Given the chat history and the latest user question, "
+             "rewrite it as a clear standalone question about fintech API integration. "
+             "Do NOT answer — only reformulate if needed."),
             MessagesPlaceholder("chat_history"),
             ("human", "{input}"),
         ])
+        condense_chain = condense_prompt | llm | StrOutputParser()
 
-        # Create history-aware retriever
-        history_aware_retriever = create_history_aware_retriever(
-            llm, retriever, contextualize_q_prompt
-        )
-
-        # Question answering prompt
-        qa_system_prompt = """
-        You are ocs4dev, a specialized fintech API integration assistant. Use the following context
-        to help developers integrate fintech APIs (MTN MoMo, Pesapal, Sentezo, etc.).
-
-        Your responses should:
-        1. Be technically accurate and detailed
-        2. Include relevant code examples and snippets
-        3. Provide step-by-step implementation guidance
-        4. Include error handling best practices
-        5. Reference specific API endpoints and parameters
-        6. Suggest testing approaches
-
-        Format code blocks properly with language specification for syntax highlighting.
-        Always provide practical, actionable advice.
+        def contextualized_retriever(inputs: dict):
+            """Reformulate question if history exists, then retrieve."""
+            if inputs.get("chat_history"):
+                standalone = condense_chain.invoke(inputs)
+            else:
+                standalone = inputs["input"]
+            return retriever.invoke(standalone)
 
-        Context: {context}
-        """
+        def format_docs(docs) -> str:
+            return "\n\n---\n\n".join(
+                f"[{d.metadata.get('provider', 'Docs')}]\n{d.page_content}"
+                for d in docs
+            )
 
+        # Step 2 — answer using retrieved context
         qa_prompt = ChatPromptTemplate.from_messages([
-            ("system", qa_system_prompt),
+            ("system",
+             SYSTEM_PROMPT_CORE + """
+═══════════════════════════════════════════════════════════════
+                    RETRIEVED DOCUMENTATION
+═══════════════════════════════════════════════════════════════
+
+{context}
+
+Use the documentation above to ground your answers with specific endpoints, 
+headers, and request/response formats. If the docs don't fully cover the 
+developer's question, supplement with your deep knowledge of these APIs 
+and clearly distinguish between doc-sourced facts and your recommendations."""),
             MessagesPlaceholder("chat_history"),
             ("human", "{input}"),
         ])
 
-        # Create document chain
-        question_answer_chain = create_stuff_documents_chain(llm, qa_prompt)
+        # LCEL chain: assign context → prompt → llm → parse
+        rag_chain = (
+            RunnablePassthrough.assign(
+                context=RunnableLambda(contextualized_retriever) | format_docs
+            )
+            | qa_prompt
+            | llm
+            | StrOutputParser()
+        )
+        return rag_chain
 
-        # Create final RAG chain
-        rag_chain = create_retrieval_chain(history_aware_retriever, question_answer_chain)
+    # ── Local Model Inference ─────────────────────────────────────────────────
+    def _generate_local_stream(
+        self, message: str, history: List[Tuple[str, str]]
+    ) -> Generator[str, None, None]:
+        """Stream tokens from the local Qwen model."""
+        if not self._load_local_model():
+            yield "⏳ Local model is loading, please wait a moment then try again."
+            return
 
-        return rag_chain
+        context = self.get_context(message)
+        system  = build_local_system_prompt(context)
+
+        # Build messages list — history is Gradio 6 dict format
+        messages = [{"role": "system", "content": system}]
+        # Include last 8 entries of history (4 turns)
+        for entry in history[-8:]:
+            role    = entry.get("role", "user")
+            content = entry.get("content") or ""
+            if role in ("user", "assistant") and content:
+                messages.append({"role": role, "content": str(content)})
+        messages.append({"role": "user", "content": message})
+
+        formatted = self._local_tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        inputs    = self._local_tokenizer(formatted, return_tensors="pt")
+        input_ids = inputs["input_ids"]
+        mask      = inputs["attention_mask"]
+
+        streamer = TextIteratorStreamer(
+            self._local_tokenizer,
+            skip_prompt=True,
+            skip_special_tokens=True,
+        )
 
-    def update_model_config(self, provider: str, tier: str, api_key: str = None):
-        """Update current model configuration"""
-        self.current_provider = provider
-        self.current_model_tier = tier
-
-        if provider != "local" and api_key:
-            if provider == "openai":
-                self.openai_api_key = api_key
-            elif provider == "anthropic":
-                self.anthropic_api_key = api_key
-            elif provider == "google":
-                self.google_api_key = api_key
-
-    def chat(self, message: str, history: List[Tuple[str, str]], provider: str, tier: str, api_key: str = None) -> str:
-        """Main chat function - returns full response (streaming handled by Gradio)"""
-        try:
-            # Update model configuration
-            self.update_model_config(provider, tier, api_key)
+        gen_kwargs = dict(
+            input_ids=input_ids,
+            attention_mask=mask,
+            streamer=streamer,
+            max_new_tokens=16384,
+            temperature=0.3,
+            do_sample=True,
+            pad_token_id=self._local_tokenizer.eos_token_id,
+        )
 
-            if provider == "local":
-                # Use local model with context
-                context = self.get_retrieval_context(message)
-                return self.generate_local_response(message, context)
+        thread = threading.Thread(
+            target=self._local_model.generate,
+            kwargs=gen_kwargs,
+        )
+        thread.start()
+
+        accumulated = ""
+        for token in streamer:
+            accumulated += token
+            yield accumulated
+
+        thread.join()
+
+    # ── Main Chat Dispatcher ──────────────────────────────────────────────────
+    def chat_stream(
+        self,
+        message:       str,
+        history:       list,          # Gradio 6: [{"role": ..., "content": ...}]
+        provider:      str,
+        tier:          str,
+        openai_key:    str,
+        anthropic_key: str,
+        google_key:    str,
+    ) -> Generator:
+        """
+        Yields (updated_history, cleared_input) pairs for Gradio streaming.
+        All providers use FAISS for retrieval context.
+        """
+        if not message.strip():
+            yield history, ""
+            return
+
+        # ── Local model path ──────────────────────────────────────────────────
+        if provider == "local":
+            new_history = history + [(message, "")]
+            for partial in self._generate_local_stream(message, history):
+                new_history[-1] = (message, partial)
+                yield new_history, ""
+            return
+
+        # ── API model path ────────────────────────────────────────────────────
+        key_map = {
+            "openai":    openai_key    or self.openai_key,
+            "anthropic": anthropic_key or self.anthropic_key,
+            "google":    google_key    or self.google_key,
+        }
+        api_key = key_map.get(provider, "")
+        if not api_key:
+            err_msg = (
+                f"❌ No API key provided for **{provider}**.\n\n"
+                f"Open the ⚙️ **Settings** panel and enter your {provider.title()} API key."
+            )
+            yield history + [(message, err_msg)], ""
+            return
+
+        try:
+            llm       = self._get_llm(provider, tier, api_key)
+            rag_chain = self._build_rag_chain(llm)
+
+            # Convert Gradio history → LangChain messages
+            lc_history = []
+            for h, a in history:
+                lc_history.append(HumanMessage(content=h))
+                lc_history.append(AIMessage(content=a))
+
+            partial     = ""
+            new_history = history + [(message, "")]
+
+            if rag_chain:
+                for chunk in rag_chain.stream(
+                    {"input": message, "chat_history": lc_history}
+                ):
+                    # LCEL chain yields strings directly (not dicts)
+                    if isinstance(chunk, str):
+                        partial += chunk
+                    elif isinstance(chunk, dict) and "answer" in chunk:
+                        partial += chunk["answer"]
+                    new_history[-1] = (message, partial)
+                    yield new_history, ""
             else:
-                # Use API model
-                api_key_map = {
-                    "openai": self.openai_api_key,
-                    "anthropic": self.anthropic_api_key,
-                    "google": self.google_api_key
-                }
-
-                current_api_key = api_key or api_key_map.get(provider)
-                if not current_api_key:
-                    return f"❌ No API key provided for {provider}. Please enter your API key in the settings."
-
-                # Get LLM instance
-                llm = self.get_llm_instance(provider, tier, current_api_key)
-
-                # Create retrieval chain
-                rag_chain = self.create_retrieval_chain(llm, provider)
-
-                if not rag_chain:
-                    # Fallback to simple context if no vector store
-                    context = self.get_retrieval_context(message)
-                    simple_prompt = f"Context: {context}\n\nQuestion: {message}\n\nProvide a detailed response about fintech API integration."
-                    return llm.invoke(simple_prompt).content
-
-                # Convert Gradio history to LangChain format
-                chat_history = []
-                for human, assistant in history:
-                    chat_history.append(HumanMessage(content=human))
-                    chat_history.append(AIMessage(content=assistant))
-
-                # Invoke RAG chain
-                response = rag_chain.invoke({
-                    "input": message,
-                    "chat_history": chat_history
-                })
-
-                return response["answer"]
+                # Fallback: no FAISS — direct call with injected context
+                context = self.get_context(message)
+                prompt  = (
+                    f"You are ocs4dev, a fintech API expert.\n\n"
+                    f"Context:\n{context}\n\nQuestion:\n{message}"
+                )
+                for chunk in llm.stream(prompt):
+                    partial += chunk.content
+                    new_history[-1] = {"role": "assistant", "content": partial}
+                    yield new_history, ""
 
         except Exception as e:
-            return f"❌ Error processing request: {str(e)}"
+            err = append_msg(append_msg(history, "user", message), "assistant", f"❌ Error: {str(e)}")
+            yield err, ""
+
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Gradio Interface
+# ─────────────────────────────────────────────────────────────────────────────
 def create_gradio_interface():
-    """Create the Gradio interface optimized for HuggingFace Spaces"""
-    print("🚀 Starting ocs4dev - Your Fintech API Integration Assistant")
+    print("🚀 Starting ocs4dev — Fintech API Integration Assistant")
 
-    # Initialize assistant
     try:
         assistant = OCS4DevAssistant()
-        print("✅ ocs4dev initialized successfully!")
+        print("✅ ocs4dev initialized!")
     except Exception as e:
-        print(f"❌ Failed to initialize ocs4dev: {e}")
+        print(f"❌ Initialization failed: {e}")
         return None
 
-    # Custom CSS for better styling and copy buttons
-    custom_css = """
-    .warning-box {
-        background-color: #fff3cd;
-        border: 1px solid #ffeaa7;
-        border-radius: 8px;
-        padding: 12px;
-        margin: 10px 0;
-        font-size: 14px;
-        color: #856404 !important;
-    }
-    .model-info {
-        background-color: #e3f2fd;
-        border-left: 4px solid #2196f3;
-        padding: 12px;
-        margin: 10px 0;
-        border-radius: 4px;
-        color: #1565c0 !important;
-    }
-    .feature-box {
-        background-color: #f8f9fa;
-        border: 1px solid #dee2e6;
-        border-radius: 8px;
-        padding: 15px;
-        margin: 10px 0;
-        color: #212529 !important;
-    }
-    .code-block {
-        background-color: #f8f9fa;
-        border: 1px solid #e9ecef;
-        border-radius: 6px;
-        padding: 12px;
-        margin: 8px 0;
-        position: relative;
-        font-family: 'Courier New', monospace;
-        color: #212529 !important;
+    css = """
+    /* ── Hide ALL scrollbars ── */
+    *, *::before, *::after {
+        scrollbar-width: none !important;
+        -ms-overflow-style: none !important;
     }
-    .copy-button {
-        position: absolute;
-        top: 8px;
-        right: 8px;
-        background: #007bff;
-        color: white;
-        border: none;
-        padding: 4px 8px;
-        border-radius: 4px;
-        cursor: pointer;
-        font-size: 12px;
-    }
-    .copy-button:hover {
-        background: #0056b3;
-    }
-    /* Hide Gradio footer */
-    .footer {
+    *::-webkit-scrollbar {
         display: none !important;
+        width: 0 !important;
+        height: 0 !important;
     }
 
-    /* Overlay backdrop */
-    .sidebar-backdrop {
-        position: fixed;
-        top: 0;
-        left: 0;
-        width: 100%;
-        height: 100%;
-        background: rgba(0, 0, 0, 0.5);
-        z-index: 999;
-        display: none;
-    }
-
-    .sidebar-backdrop.show {
-        display: block;
-    }
-
-    /* Sidebar as overlay */
-    .sidebar-container {
-        position: fixed;
-        left: 0;
-        top: 0;
-        height: 100vh;
-        width: 400px; /* Wider sidebar for better text display */
-        max-width: 90vw; /* Responsive on mobile */
-        background: var(--background-fill-primary);
-        border-right: 1px solid var(--border-color-primary);
-        transform: translateX(-100%);
-        transition: transform 0.3s ease;
-        z-index: 1000;
-        overflow-y: auto;
-        overflow-x: hidden;
-        padding: 20px;
-        padding-top: 60px; /* Space for close button */
-        box-sizing: border-box;
-        box-shadow: 2px 0 10px rgba(0, 0, 0, 0.1);
-    }
-
-    .sidebar-container.open {
-        transform: translateX(0);
-    }
-
-    /* Fix white spaces in sidebar */
-    .sidebar-container .gr-form {
-        gap: 0 !important;
-    }
-
-    .sidebar-container .gr-box {
-        border: none !important;
-        background: transparent !important;
-    }
-
-    .sidebar-container .gr-padded {
-        padding: 8px !important;
-    }
-
-    .sidebar-container .gr-panel {
-        background: var(--background-fill-secondary) !important;
-        padding: 12px !important;
-        border-radius: 8px;
-        margin-bottom: 12px;
-    }
-
-    /* Style sidebar content */
-    .sidebar-container h2 {
-        color: var(--body-text-color) !important;
-        margin-bottom: 20px;
-        font-size: 1.5rem;
-    }
-
-    .sidebar-container .gr-markdown h2 {
-        color: var(--body-text-color) !important;
-        margin-top: 0;
-    }
-
-    /* Remove unwanted white borders and backgrounds */
-    .sidebar-container .gradio-container {
-        background: transparent !important;
-        border: none !important;
-    }
-
-    .sidebar-container .gr-form {
-        background: transparent !important;
-        border: none !important;
-        gap: 12px !important;
-    }
-
-    .sidebar-container .gr-input-wrapper {
-        margin: 0 !important;
-    }
-
-    .sidebar-container .gr-group {
-        background: var(--background-fill-secondary) !important;
-        border: 1px solid var(--border-color-primary) !important;
-        border-radius: 8px;
-        padding: 12px;
-        margin-bottom: 12px;
-    }
-
-    /* Ensure text visibility in sidebar */
-    .sidebar-container * {
-        color: var(--body-text-color) !important;
-    }
+    .footer { display: none !important; }
 
-    .sidebar-title {
-        font-size: 1.5rem !important;
-        font-weight: bold !important;
-        margin-bottom: 20px !important;
-        color: var(--body-text-color) !important;
-    }
-
-    .sidebar-toggle {
-        position: fixed;
-        left: 20px;
-        top: 20px;
-        z-index: 998;
-        background: var(--button-primary-background-fill);
-        color: var(--button-primary-text-color);
-        border: none;
-        padding: 12px 16px;
-        border-radius: 8px;
-        cursor: pointer;
-        font-size: 18px;
-        transition: all 0.3s ease;
-        box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);
-    }
-
-    .sidebar-toggle:hover {
-        background: var(--button-primary-background-fill-hover);
-        box-shadow: 0 4px 8px rgba(0, 0, 0, 0.15);
-    }
-
-    .sidebar-close {
-        position: absolute;
-        right: 20px;
-        top: 20px;
-        background: transparent;
-        border: none;
-        font-size: 24px;
-        cursor: pointer;
-        color: var(--body-text-color);
-        padding: 5px;
-        border-radius: 4px;
-        transition: background 0.2s ease;
-        z-index: 1001;
-    }
-
-    .sidebar-close:hover {
+    /* Info / warning boxes */
+    .info-box {
         background: var(--background-fill-secondary);
+        border-left: 4px solid var(--color-accent);
+        border-radius: 4px; padding: 10px 14px;
+        margin: 8px 0; font-size: 13px;
     }
-
-    /* Main content stays in place */
-    .main-content {
-        min-height: 100vh;
-        padding-left: 70px; /* Space for menu button */
-    }
-
-    /* Custom chat styling */
-    .chat-container {
-        max-width: 100%;
-        margin: 0 auto;
-        padding: 20px;
-    }
-
-    /* Dark mode specific fixes */
-    .dark .sidebar-container {
-        background: var(--background-fill-primary);
-    }
-
-    .dark .warning-box {
-        background-color: #2d2d2d;
-        border: 1px solid #ffc107;
-        color: #ffc107 !important;
-    }
-    .dark .model-info {
-        background-color: #1a1a1a;
-        border-left: 4px solid #64b5f6;
-        color: #64b5f6 !important;
-    }
-    .dark .feature-box {
-        background-color: #2d2d2d;
-        border: 1px solid #495057;
-        color: #e9ecef !important;
-    }
-
-    /* Responsive adjustments */
-    @media (max-width: 768px) {
-        .sidebar-container {
-            width: 85vw;
-        }
-        .main-content {
-            padding-left: 60px;
-        }
+    .warn-box {
+        background: var(--background-fill-secondary);
+        border-left: 4px solid #f59e0b;
+        border-radius: 4px; padding: 10px 14px;
+        margin: 8px 0; font-size: 13px;
+    }
+    .status-ok  { color: #22c55e !important; font-weight: 600; }
+    .status-err { color: #ef4444 !important; font-weight: 600; }
+
+    /* ── Submit / Stop buttons live inside the Textbox in Gradio 6.x ── */
+    /* Ensure they are never clipped or collapsed */
+    .textbox-wrap button,
+    .textbox button {
+        display: inline-flex !important;
+        visibility: visible !important;
+        opacity: 1 !important;
+        flex-shrink: 0 !important;
     }
     """
 
-    # Create the interface
-    def chat_with_config(message, history, provider, tier, openai_key, anthropic_key, google_key):
-        """Chat function with configuration"""
-        api_key = None
-        if provider == "openai":
-            api_key = openai_key
-        elif provider == "anthropic":
-            api_key = anthropic_key
-        elif provider == "google":
-            api_key = google_key
+    rag_status = (
+        '<span class="status-ok">✅ FAISS index loaded</span>'
+        if assistant.vector_store
+        else '<span class="status-err">⚠️ FAISS index missing — run build_index.py</span>'
+    )
 
-        return assistant.chat(message, history, provider, tier, api_key)
-
-    # Create interface
     with gr.Blocks(
-        title="ocs4dev - Fintech API Assistant",
-        theme=gr.themes.Soft(
-            primary_hue="blue",
-            secondary_hue="gray",
-            neutral_hue="slate",
-        ),
-        css=custom_css,
+        title="ocs4dev — Fintech API Assistant",
+        theme=gr.themes.Soft(primary_hue="blue", secondary_hue="slate", neutral_hue="slate"),
+        css=css,
         fill_height=True,
-        js="""
-        function() {
-            // Add sidebar toggle functionality with backdrop
-            const backdrop = document.createElement('div');
-            backdrop.className = 'sidebar-backdrop';
-            document.body.appendChild(backdrop);
-
-            const toggleButton = document.createElement('button');
-            toggleButton.innerHTML = '☰';
-            toggleButton.className = 'sidebar-toggle';
-            toggleButton.title = 'Open Settings';
-
-            const sidebar = document.querySelector('.sidebar-container');
-
-            // Add close button to sidebar
-            const closeButton = document.createElement('button');
-            closeButton.innerHTML = '✕';
-            closeButton.className = 'sidebar-close';
-            closeButton.title = 'Close Settings';
-            sidebar.insertBefore(closeButton, sidebar.firstChild);
-
-            function openSidebar() {
-                sidebar.classList.add('open');
-                backdrop.classList.add('show');
-                document.body.style.overflow = 'hidden';
-            }
-
-            function closeSidebar() {
-                sidebar.classList.remove('open');
-                backdrop.classList.remove('show');
-                document.body.style.overflow = '';
-            }
-
-            toggleButton.onclick = openSidebar;
-            closeButton.onclick = closeSidebar;
-            backdrop.onclick = closeSidebar;
-
-            // ESC key to close
-            document.addEventListener('keydown', (e) => {
-                if (e.key === 'Escape' && sidebar.classList.contains('open')) {
-                    closeSidebar();
-                }
-            });
-
-            document.body.appendChild(toggleButton);
-        }
-        """
     ) as interface:
 
-        # Header
-        with gr.Column(elem_classes="main-content"):
-            gr.Markdown("# 🏦 ocs4dev - Your Fintech API Integration Assistant")
-            gr.Markdown("*Specialized AI assistant for integrating fintech APIs including MTN MoMo, Airtel, Pesapal etc*")
-
-            # Main chat interface
-            chatbot = gr.Chatbot(
-                height=500,
-                placeholder="Ask me about fintech API integration, authentication, code examples, or best practices...",
-                label="ocs4dev Assistant",
-                show_copy_button=True,  # Enable copy button for chat messages
-                render_markdown=True,
-                elem_classes="chat-container"
-            )
-
-            msg = gr.Textbox(
-                placeholder="How do I authenticate with MTN MoMo API?",
-                label="Your Question",
-                lines=2,
-                show_copy_button=True  # Enable copy button for input
-            )
-
-            with gr.Row():
-                clear = gr.Button("Clear", variant="secondary")
-                submit = gr.Button("Send", variant="primary")
-
-            # Example questions
-            gr.Examples(
-                examples=[
-                    "How do I authenticate with MTN MoMo API?",
-                    "Show me a Pesapal payment integration example",
-                    "What are the required headers for Sentezo API?",
-                    "How do I handle payment webhooks?",
-                    "Best practices for API error handling",
-                    "How to test API integrations in sandbox mode?",
-                    "Show me a complete payment flow implementation",
-                    "How to secure API keys in production?",
-                    "What's the difference between sandbox and production?",
-                    "How do I implement payment status callbacks?"
-                ],
-                inputs=msg,
-                label="💡 Example Questions"
-            )
-
-        # Sidebar (hidden by default)
-        with gr.Column(elem_classes="sidebar-container", elem_id="settings-sidebar"):
-            gr.Markdown("## ⚙️ Configuration", elem_classes="sidebar-title")
+        # ── Settings Sidebar ──────────────────────────────────────────────────
+        with gr.Sidebar(open=True):
+            gr.Markdown("## ⚙️ Settings")
 
-            # Model provider selection
             with gr.Group():
+                gr.Markdown("### 🤖 Model Provider")
                 provider = gr.Radio(
                     choices=["local", "openai", "anthropic", "google"],
                     value="local",
-                    label="Model Provider",
-                    info="Local model is free but requires GPU. API models need keys.",
-                    elem_classes="provider-selector"
+                    label="Provider",
+                    info="Local = free (Qwen 1.5B, no key).  API = cloud (needs key).",
                 )
-
                 tier = gr.Radio(
                     choices=["budget", "premium"],
                     value="budget",
-                    label="Model Tier",
-                    info="Budget models are faster/cheaper, Premium models are more capable",
-                    elem_classes="tier-selector"
+                    label="Tier",
+                    info="Budget: faster & cheaper  |  Premium: most capable",
                 )
 
-            # API Keys Section
-            with gr.Accordion("🔑 API Keys", open=True, elem_classes="api-keys-section"):
-                gr.HTML('<div class="warning-box">⚠️ <strong>Security Warning:</strong> Create test API keys for this app and delete them after use. Never share production keys.</div>')
-
-                with gr.Group():
-                    openai_key = gr.Textbox(
-                        placeholder="sk-...",
-                        label="OpenAI API Key",
-                        type="password",
-                        info="Budget: gpt-4o-mini | Premium: o4-mini (advanced reasoning)",
-                        elem_classes="api-key-input"
-                    )
-
-                    anthropic_key = gr.Textbox(
-                        placeholder="sk-ant-...",
-                        label="Anthropic API Key",
-                        type="password",
-                        info="Budget: claude-3.5-sonnet | Premium: claude-4-sonnet",
-                        elem_classes="api-key-input"
-                    )
-
-                    google_key = gr.Textbox(
-                        placeholder="AI...",
-                        label="Google API Key",
-                        type="password",
-                        info="Budget: gemini-2.0-flash | Premium: gemini-2.0-flash-thinking",
-                        elem_classes="api-key-input"
-                    )
-
-            # Updated model information
-            gr.HTML('<div class="model-info">🚀 <strong>Pro Tip:</strong> Add your API keys above for faster and better responses. Local model works but API models provide superior performance!</div>')
-
-            # Features
-            with gr.Accordion("✨ Features", open=False, elem_classes="features-section"):
-                gr.HTML('''
-                <div class="feature-box">
-                    <strong>🔧 Code-Focused:</strong> Optimized for API integration tasks<br>
-                    <strong>🔒 Secure:</strong> No API keys stored permanently<br>
-                    <strong>📋 Copy-Friendly:</strong> Easy code copying with built-in buttons<br>
-                    <strong>🚀 Fast:</strong> Multiple model options for best performance<br>
-                    <strong>🔄 Multi-Provider:</strong> Switch between AI models seamlessly
+            gr.HTML("""
+            <div class="info-box">
+            <b>Available models:</b><br>
+            🔵 Google: <b>Gemini 2.0 Flash</b> / Gemini 2.5 Pro<br>
+            🟢 OpenAI: <b>GPT-5 mini</b> / GPT-5.2<br>
+            🟠 Anthropic: <b>Claude Haiku 4.5</b> / Claude Opus 4.6<br>
+            ⚫ Local: <b>Qwen2.5-Coder-1.5B-Instruct</b> (free, no key)
+            </div>
+            """)
+
+            with gr.Accordion("🔑 API Keys", open=True):
+                gr.HTML(
+                    '<div class="warn-box">⚠️ <b>Security:</b> Use dev/test keys only. '
+                    "Never paste production keys into shared UIs.</div>"
+                )
+                openai_key = gr.Textbox(
+                    placeholder="sk-...",
+                    label="OpenAI key",
+                    type="password",
+                    info="GPT-5 mini (budget) / GPT-5.2 (premium)",
+                )
+                anthropic_key = gr.Textbox(
+                    placeholder="sk-ant-...",
+                    label="Anthropic key",
+                    type="password",
+                    info="Claude Haiku 4.5 (budget) / Claude Opus 4.6 (premium)",
+                )
+                google_key = gr.Textbox(
+                    placeholder="AIza...",
+                    label="Google key",
+                    type="password",
+                    info="Gemini 2.0 Flash (budget) / Gemini 2.5 Pro (premium)",
+                )
+                gr.Markdown(
+                    "[Get OpenAI key](https://platform.openai.com/api-keys)  ·  "
+                    "[Get Anthropic key](https://console.anthropic.com/)  ·  "
+                    "[Get Google key](https://aistudio.google.com/apikey)"
+                )
+
+            with gr.Accordion("📚 Knowledge Base", open=False):
+                gr.HTML(f"""
+                <div class="info-box">
+                {rag_status}<br><br>
+                📱 <b>MTN MoMo</b> — Auth, Collections, Disbursements, Remittances<br>
+                💳 <b>Pesapal</b> — E-commerce API 3.0, POS, Recurring Payments<br>
+                💰 <b>Sentezo</b> — Wallet Deposits, Withdrawals, Bank Transfers<br><br>
+                All retrieval is local via FAISS (no cloud DB).
                 </div>
-                ''')
-
-        # Chat functionality with simple response
-        def respond(message, history, provider, tier, openai_key, anthropic_key, google_key):
-            """Handle chat responses with simulated streaming"""
-            if not message:
-                return history, ""
-
-            # Add user message to history
-            history = history or []
-
-            # Get the full response
-            bot_message = chat_with_config(message, history, provider, tier, openai_key, anthropic_key, google_key)
-
-            # Simulate streaming by yielding partial responses
-            partial = ""
-            words = bot_message.split(" ")
-
-            # Stream words in chunks for smooth appearance
-            chunk_size = 3  # Words per chunk
-            for i in range(0, len(words), chunk_size):
-                chunk = " ".join(words[i:i+chunk_size])
-                partial += chunk + " "
-                yield history + [(message, partial.strip())], ""
-
-            # Final update with complete response
-            yield history + [(message, bot_message)], ""
-
-        # Connect the interface
-        submit.click(
-            respond,
-            inputs=[msg, chatbot, provider, tier, openai_key, anthropic_key, google_key],
-            outputs=[chatbot, msg]
+                """)
+
+        # ── Chat Interface ─────────────────────────────────────────────────────
+        gr.Markdown("# 🏦 ocs4dev — Fintech API Integration Assistant")
+        gr.Markdown(
+            "*Your AI-powered fintech integration partner. Stripe, PayPal, MTN MoMo, Pesapal, "
+            "Sentezo, Square, Adyen & more.  "
+            "Select a model in ⚙️ Settings, then start chatting.*"
         )
 
-        msg.submit(
-            respond,
-            inputs=[msg, chatbot, provider, tier, openai_key, anthropic_key, google_key],
-            outputs=[chatbot, msg]
+        gr.ChatInterface(
+            fn=assistant.respond,
+            additional_inputs=[provider, tier, openai_key, anthropic_key, google_key],
+            chatbot=gr.Chatbot(
+                height=480,
+                placeholder=(
+                    "### 👋 Welcome to ocs4dev!\n"
+                    "Ask me anything about payment API integration:\n"
+                    "- Authentication, tokens & API keys\n"
+                    "- Code examples with error handling\n"
+                    "- Webhook / callback setup\n"
+                    "- Subscriptions, payouts & refunds\n"
+                    "- Error codes & debugging"
+                ),
+                label="ocs4dev",
+                render_markdown=True,
+                avatar_images=(
+                    None,
+                    "https://huggingface.co/front/assets/huggingface_logo-noborder.svg",
+                ),
+            ),
+            textbox=gr.Textbox(
+                placeholder="Ask about Stripe payments, MTN MoMo auth, webhook setup, virtual accounts...",
+                label="",
+                lines=2,
+                scale=7,
+                submit_btn="Send ➤",
+                stop_btn="Stop ■",
+            ),
+            examples=[
+                ["How do I create a Stripe Checkout session with error handling?"],
+                ["Show me MTN MoMo API authentication and access token flow"],
+                ["How do I verify Stripe webhook signatures in Python?"],
+                ["What are the required headers for Sentezo Wallet deposit API?"],
+                ["How do I handle 3D Secure / SCA for card payments?"],
+                ["Show me how to set up PayPal subscriptions with recurring billing"],
+                ["How do I implement idempotent payment requests?"],
+                ["Compare Stripe vs Pesapal for e-commerce in East Africa"],
+                ["How do I build a virtual account system on top of a single-wallet API?"],
+            ],
+            fill_height=True,
         )
 
-        clear.click(lambda: ([], ""), outputs=[chatbot, msg])
-
-        # Footer
-        gr.Markdown("---")
-        gr.Markdown("Built with ❤️ by Aaron | Using Qwen2.5-Coder, LangChain, and Gradio | [GitHub](https://github.com/aaron-official/ocs4dev.git)")
+        gr.Markdown(
+            "Built with ❤️ by Aaron  ·  "
+            "Qwen2.5-Coder · LangChain · FAISS · Gradio"
+        )
 
     return interface
 
-def populate_knowledge_base_standalone():
-    """[DEPRECATED] Use the separate populate_supabase.py tool instead"""
-    print("⚠️  This function is deprecated!")
-    print("    Please use the separate 'populate_supabase.py' tool to populate the vector database.")
-    print("    ")
-    print("    Usage:")
-    print("    $ python populate_supabase.py --knowledge-base ./knowledge-base")
-    print("    ")
-    print("    The tool will:")
-    print("    1. Load all markdown files from your knowledge base directory")
-    print("    2. Split them into chunks for better retrieval")
-    print("    3. Generate embeddings using OpenAI")
-    print("    4. Store everything in your Supabase vector database")
-    print("    ")
-    print("    Make sure you have set these environment variables:")
-    print("    - SUPABASE_URL")
-    print("    - SUPABASE_SERVICE_KEY")
-    print("    - OPENAI_API_KEY")
-    return False
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Entry point
+# ─────────────────────────────────────────────────────────────────────────────
 def main():
-    """Main function optimized for HuggingFace Spaces"""
     interface = create_gradio_interface()
     if interface:
-        # HuggingFace Spaces optimized launch
         interface.launch(
             server_name="0.0.0.0",
             server_port=7860,
-            share=True,  # Enable public URL for HF Spaces
-            inbrowser=False,  # Don't open browser in server environment
+            share=True,
+            inbrowser=False,
             show_error=True,
             quiet=False,
-            max_threads=10  # Limit concurrent requests
+            max_threads=10,
         )
 
+
 if __name__ == "__main__":
-    main()
+    main()
+

pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "ocs4dev"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "faiss-cpu>=1.13.2",
+    "gradio>=6.8.0",
+    "langchain>=1.2.10",
+    "langchain-anthropic>=1.3.4",
+    "langchain-community>=0.4.1",
+    "langchain-google-genai>=4.2.1",
+    "langchain-huggingface>=1.2.1",
+    "langchain-openai>=1.1.10",
+    "langchain-text-splitters>=1.1.1",
+    "python-dotenv>=1.2.2",
+    "sentence-transformers>=5.2.3",
+]

requirements.txt

@@ -1,34 +1,34 @@
-# Core Dependencies (IMPORTANT: transformers>=4.37.0 required for Qwen2.5-Coder)
-transformers==4.53.2
-torch==2.6.0
+# =====================================================================
+# ocs4dev - Requirements
+# HuggingFace Spaces compatible (CPU-optimized, no external DB needed)
+# =====================================================================
+
+# --- Core ML: CPU-only torch to avoid OOM during HF Spaces build ---
+# GPU torch is ~2.5GB; CPU-only is ~250MB → prevents exit code 137
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.10.0+cpu
+transformers==5.2.0
 accelerate==1.8.1
 huggingface-hub==0.33.4
 
-# LangChain (updated to avoid deprecation warnings)
-langchain==0.3.26
+# --- LangChain ---
 langchain-community==0.3.27
 langchain-core==0.3.69
-langchain-text-splitters==0.3.8
+langchain-huggingface==0.1.2
 
-# Multi-provider LLM support
+# --- Multi-provider LLM support ---
 langchain-openai==0.3.28
 langchain-anthropic==0.3.17
 langchain-google-genai==2.1.8
 
-# Supabase
-supabase==2.16.0
-vecs==0.4.5
-
-# UI Framework
-gradio==5.31.0
+# --- Local Vector Store (replaces Supabase) ---
+faiss-cpu==1.10.0
+sentence-transformers==5.2.3
 
-# Utilities
-python-dotenv==1.1.1
-numpy==2.0.2
-sentence-transformers==4.1.0
+# --- UI Framework ---
+gradio==6.8.0
 
-# Quantization and Performance
-bitsandbytes==0.46.1    # For 8-bit quantization
-auto-gptq==0.7.1        # For GPTQ quantization
-autoawq==0.2.9          # For AWQ quantization
-intel_extension_for_pytorch==2.7.0  # Intel optimization for PyTorch
+# --- Utilities ---
+python-dotenv==1.2.2
+# numpy: use range to get pre-built binary wheel (avoids source compilation OOM)
+numpy>=2.0