From dac8af7a8a829745ffe15eef8f897cfbcc71d909 Mon Sep 17 00:00:00 2001 From: Teesofttech Date: Sat, 18 Jul 2026 23:17:21 +0100 Subject: [PATCH] Build redesigned GitHub Pages documentation portal --- .github/workflows/docs-pages.yml | 58 +++++++++++++++++++++++++++++ .gitignore | 3 ++ README.md | 13 +++++++ README.nuget.md | 1 + docs/assets/logo.svg | 6 +++ docs/index.md | 55 ++++++++++++++++++++++++++++ docs/quickstart.md | 58 +++++++++++++++++++++++++++++ docs/stylesheets/extra.css | 51 ++++++++++++++++++++++++++ mkdocs.yml | 63 ++++++++++++++++++++++++++++++++ 9 files changed, 308 insertions(+) create mode 100644 .github/workflows/docs-pages.yml create mode 100644 docs/assets/logo.svg create mode 100644 docs/index.md create mode 100644 docs/quickstart.md create mode 100644 docs/stylesheets/extra.css create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml new file mode 100644 index 0000000..4483bd5 --- /dev/null +++ b/.github/workflows/docs-pages.yml @@ -0,0 +1,58 @@ +name: Docs - GitHub Pages + +on: + push: + branches: + - master + paths: + - docs/** + - mkdocs.yml + - .github/workflows/docs-pages.yml + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v7 + + - name: Setup Python + uses: actions/setup-python@v6 + with: + python-version: '3.12' + + - name: Install MkDocs Material + run: | + python -m pip install --upgrade pip + pip install mkdocs-material + + - name: Build documentation + run: mkdocs build --strict + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v4 + with: + path: site + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 9491a2f..13784ea 100644 --- a/.gitignore +++ b/.gitignore @@ -258,6 +258,9 @@ _UpgradeReport_Files/ Backup*/ UpgradeLog*.XML UpgradeLog*.htm + +# MkDocs build output +site/ ServiceFabricBackup/ *.rptproj.bak diff --git a/README.md b/README.md index 6601b48..c2fb7d9 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,9 @@

+ + Documentation + Latest Release @@ -27,6 +30,16 @@ --- +## Documentation Portal + +The redesigned docs site is published on GitHub Pages: + +- https://teesofttech.github.io/PayBridge/ + +Use it as the canonical operational guide for setup, security hardening, routing, idempotency, and integration testing. + +--- + ## 🚀 Features - **Unified API**: Interact with multiple payment gateways (e.g., Flutterwave, Paystack, Stripe, Korapay, PeachPayments) through a single, consistent interface. diff --git a/README.nuget.md b/README.nuget.md index 07d37a7..01be1bb 100644 --- a/README.nuget.md +++ b/README.nuget.md @@ -4,6 +4,7 @@ [![NuGet](https://img.shields.io/nuget/v/PayBridge.SDK)](https://www.nuget.org/packages/PayBridge.SDK) [![NuGet Downloads](https://img.shields.io/nuget/dt/PayBridge.SDK)](https://www.nuget.org/packages/PayBridge.SDK) +[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0f766e)](https://teesofttech.github.io/PayBridge/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/teesofttech/PayBridge/blob/master/LICENSE) [![GitHub](https://img.shields.io/badge/GitHub-teesofttech%2FPayBridge-blue)](https://github.com/teesofttech/PayBridge) diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg new file mode 100644 index 0000000..95add1d --- /dev/null +++ b/docs/assets/logo.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..d3fce6e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,55 @@ +# PayBridge Documentation + +

+
Production-grade Payment Orchestration for .NET
+

Build once. Route safely. Operate confidently.

+

+ PayBridge gives your team one integration surface for multi-gateway payments, + verification, refunds, webhook security, and operational safeguards. +

+ Start with Quick Start +
+ +## What You Get + +- Unified gateway abstraction for payment creation, verification, and refund operations. +- Secure webhook path with signature verification, replay protection, and fail-closed behavior. +- Deterministic automatic routing with clear configuration validation at startup. +- Testable architecture with unit and integration workflows aligned to release quality. + +## Documentation Paths + +### Start Here + +- [Quick Start](quickstart.md): Configure, run, and process your first transaction flow. +- [Automatic Routing](automatic-gateway-routing.md): Understand route selection and fallback behavior. +- [Payment Idempotency](payment-idempotency.md): Prevent duplicate effects across retries. + +### Security Hardening + +- [Webhook Security](webhook-security.md): Signature validation contracts and provider-specific expectations. +- [Webhook Replay Protection](webhook-replay-protection.md): Replay detection strategy and operations notes. +- [Dependency Security](dependency-security.md): Vulnerability management and CI safeguards. +- [Credential Rotation](credential-rotation-and-history-purge.md): Incident response and secret hygiene. + +### Reliability and Operations + +- [Integration Testing](integration-testing.md): Sandbox preflight gates and run interpretation. +- [Refund Persistence](refund-persistence.md): Durable refund lifecycle handling. +- [Flutterwave Refunds](flutterwave-refunds.md): Known behavior and current implementation notes. + +## Recommended Reading Order + +1. Quick Start +2. Automatic Routing +3. Webhook Security +4. Integration Testing +5. Idempotency and Refund Persistence + +## Release Readiness Checklist + +- Gateway credentials configured through secure runtime providers. +- Webhook signatures verified before payload parsing or fulfillment. +- Idempotency and replay controls active for mutation endpoints. +- Unit and integration test gates passing in CI. +- Documentation and package claims aligned with implementation. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..d824cb9 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,58 @@ +# Quick Start + +This guide takes you from a clean repository checkout to a secure first payment flow. + +## 1. Install and Restore + +```bash +dotnet restore PayBridge.SDK.sln +dotnet build PayBridge.SDK.sln +``` + +## 2. Configure Database Provider + +Use one supported provider and supply the connection string from secure sources. + +Supported provider values: + +- SqlServer (or MSSQL) +- Npgsql (or PostgreSQL/Postgres) +- MySql + +## 3. Configure Gateway Credentials + +Use .NET user-secrets locally and environment variables or managed secret stores in hosted environments. + +Example: + +```bash +dotnet user-secrets set "PaymentGatewayConfig:EnabledGateways:0" "Paystack" --project PayBridge.SDK.Example/PayBridge.SDK.Example.csproj +dotnet user-secrets set "PaymentGatewayConfig:Paystack:SecretKey" "" --project PayBridge.SDK.Example/PayBridge.SDK.Example.csproj +``` + +## 4. Register Services + +In your startup wiring: + +- Register persistence with AddDBRepository +- Register SDK services with AddPayBridge + +## 5. Run Example API + +```bash +dotnet run --project PayBridge.SDK.Example/PayBridge.SDK.Example.csproj +``` + +## 6. Process Payment Lifecycle + +1. Create payment using an explicit or automatic gateway route. +2. Redirect customer to checkout URL. +3. Verify callback/webhook reference through provider verification. +4. Persist payment status and fulfill order after successful verification. + +## 7. Harden Before Production + +- Enforce webhook signature verification and replay protection. +- Require authenticated access for hosted demo/API surfaces. +- Keep all credentials server-side. +- Ensure integration tests run against real sandbox credentials. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..45d6327 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,51 @@ +:root { + --pb-accent: #0f766e; + --pb-accent-strong: #115e59; + --pb-surface: #f0fdfa; +} + +.md-content h1 { + letter-spacing: -0.02em; +} + +.hero { + margin: 0.75rem 0 2rem; + padding: 1.5rem; + border-radius: 1rem; + background: linear-gradient(140deg, rgba(15, 118, 110, 0.12), rgba(6, 182, 212, 0.15)); + border: 1px solid rgba(15, 118, 110, 0.2); +} + +.hero__eyebrow { + font-weight: 700; + text-transform: uppercase; + font-size: 0.72rem; + letter-spacing: 0.06em; + color: var(--pb-accent-strong); + margin-bottom: 0.5rem; +} + +.hero h1 { + margin: 0.25rem 0 0.75rem; + font-size: clamp(1.5rem, 4vw, 2.35rem); + line-height: 1.15; +} + +.hero p { + max-width: 62ch; + margin: 0 0 1rem; +} + +.hero__cta { + display: inline-block; + background: var(--pb-accent); + color: #fff !important; + text-decoration: none; + font-weight: 700; + padding: 0.6rem 0.9rem; + border-radius: 0.65rem; +} + +.hero__cta:hover { + background: var(--pb-accent-strong); +} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..f8c236a --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,63 @@ +site_name: PayBridge Documentation +site_description: Production-ready integration and operations guide for PayBridge.SDK +site_url: https://teesofttech.github.io/PayBridge/ +repo_url: https://github.com/teesofttech/PayBridge +repo_name: teesofttech/PayBridge +edit_uri: edit/master/docs/ + +theme: + name: material + logo: assets/logo.svg + favicon: assets/logo.svg + language: en + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: cyan + toggle: + icon: material/weather-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + accent: cyan + toggle: + icon: material/weather-sunny + name: Switch to light mode + features: + - navigation.instant + - navigation.tracking + - navigation.top + - navigation.sections + - navigation.footer + - content.code.copy + - search.highlight + - search.suggest + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - tables + - toc: + permalink: true + +extra_css: + - stylesheets/extra.css + +nav: + - Home: index.md + - Quick Start: + - Overview: quickstart.md + - Automatic Routing: automatic-gateway-routing.md + - Payment Idempotency: payment-idempotency.md + - Security: + - Webhook Security: webhook-security.md + - Webhook Replay Protection: webhook-replay-protection.md + - Dependency Security: dependency-security.md + - Credential Rotation: credential-rotation-and-history-purge.md + - Reliability: + - Integration Testing: integration-testing.md + - Refund Persistence: refund-persistence.md + - Flutterwave Refunds: flutterwave-refunds.md