{"id":42716698,"url":"https://github.com/aluyapeter/wallet_service","last_synced_at":"2026-01-29T15:40:08.102Z","repository":{"id":327903766,"uuid":"1113418854","full_name":"aluyapeter/wallet_service","owner":"aluyapeter","description":"A high-performance, async fintech backend built with FastAPI, SQLModel, and PostgreSQL. Features secure authentication, real-time payments via Paystack, atomic wallet transfers, and a permission-based API key system.","archived":false,"fork":false,"pushed_at":"2026-01-10T10:23:10.000Z","size":61,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-10T21:56:36.855Z","etag":null,"topics":["fastapi","paystack","postgresql"],"latest_commit_sha":null,"homepage":"https://wallet-service-rpoa.onrender.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aluyapeter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T00:30:56.000Z","updated_at":"2026-01-10T10:23:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aluyapeter/wallet_service","commit_stats":null,"previous_names":["aluyapeter/wallet_service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aluyapeter/wallet_service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aluyapeter%2Fwallet_service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aluyapeter%2Fwallet_service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aluyapeter%2Fwallet_service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aluyapeter%2Fwallet_service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aluyapeter","download_url":"https://codeload.github.com/aluyapeter/wallet_service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aluyapeter%2Fwallet_service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28880341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","paystack","postgresql"],"created_at":"2026-01-29T15:40:07.349Z","updated_at":"2026-01-29T15:40:08.082Z","avatar_url":"https://github.com/aluyapeter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏦 Fintech Wallet Service API (Mini-Bank Core)\n\nA production-grade, async fintech backend built with **FastAPI**, **SQLModel**, and **PostgreSQL**. This system acts as a \"Mini-Bank\" core, featuring secure authentication, Step-Up security (PINs), real-time deposits, external bank withdrawals, and professional database migrations.\n\n## 🚀 Features\n\n### Core Banking\n\n- **Wallets:** Automatic NGN wallet creation for every user.\n- **Deposits:** Real-time funding via **Paystack** (Standard Checkout \u0026 Webhook verification).\n- **Transfers:** Atomic, ACID-compliant internal money movement between users.\n- **Withdrawals:** Automated payouts to external Nigerian bank accounts (Resolution + Transfer).\n- **Transaction History:** Optimized, paginated transaction logs for high-volume users.\n\n### Security \u0026 Identity\n\n- **Authentication:** OAuth2 (Google) \u0026 JWT-based session management.\n- **Step-Up Security:** **4-digit Transaction PIN** required for all outgoing funds (Hashed via Argon2).\n- **API Security:** Permission-based API Keys for third-party integrations.\n- **Integrity:** HMAC SHA512 signature verification for all payment webhooks.\n\n### Engineering \u0026 DevOps\n\n- **Containerization:** Fully Dockerized stack (API + Database) for consistent deployment.\n- **Migrations:** Database schema version control using **Alembic**.\n- **Observability:** Structured logging for debugging and audit trails.\n- **Testing:** Comprehensive Pytest suite covering security gates and concurrency.\n\n---\n\n## 🛠️ Tech Stack\n\n- **Language:** Python 3.11+\n- **Framework:** FastAPI\n- **Database:** PostgreSQL 15 (Dockerized)\n- **ORM:** SQLModel (SQLAlchemy + Pydantic)\n- **Migrations:** Alembic\n- **Cryptography:** Pwdlib (Argon2), Passlib\n- **Payments:** Paystack API\n- **Infrastructure:** Docker \u0026 Docker Compose\n\n---\n\n## ⚡ Quick Start (Docker)\n\nThe application is fully containerized. You do not need to install Python or Postgres locally to run this.\n\n### 1. Prerequisites\n\n- Docker Desktop \u0026 Docker Compose\n- Paystack Account (Test Mode)\n\n## 🛠 Environment Setup\n\n## 1. Copy the example environment file:\n\n```bash\ncp .env.example .env\n```\n\nOpen .env and fill in your specific credentials (DB, Google, Paystack).\n\nNote: For email testing, use your Gmail App Password.\n\n## 3. Launch the Stack\n\nRun the entire application (Database + API) with one command:\n\n```bash\ndocker-compose up --build\n```\n\n- **API:** http://localhost:8000\n- **Swagger UI:** http://localhost:8000/docs\n- **Database:** Port 5433 (Exposed for tools like DBeaver)\n\n## 4. Apply Migrations\n\nOnce the container is running, initialize the database schema:\n\n```bash\ndocker-compose exec web alembic upgrade head\n```\n\n## 💳 Payment Webhooks (Localhost)\n\nTo test deposits locally, Paystack must be able to reach your machine.\n\n**Start a Tunnel:**\n\n```bash\nssh -R 80:localhost:8000 localhost.run\n```\n\nCopy the HTTPS URL generated (e.g., `https://random-id.localhost.run`).\n\n**Configure Paystack:**\n\n1. Go to Paystack Dashboard \u003e Settings \u003e API Keys \u0026 Webhooks\n2. Set Test Webhook URL to: `https://\u003cYOUR_TUNNEL_URL\u003e/wallet/paystack/webhook`\n3. Click Save Changes\n\n## 📚 API Documentation\n\n### 🔐 Auth \u0026 Security\n\n| Method | Endpoint                    | Description                                                                                         |\n| ------ | --------------------------- | --------------------------------------------------------------------------------------------------- |\n| GET    | `/auth/google`              | Login via Google, paste the returned url in another tab to get your access token                    |\n| GET    | `/auth/google/callback`     | Handles the callback from Google. Exchanges the code for a token, gets user info, and logs them in. |\n| POST   | `/auth/signup`              | Registers a new user, creates their unique wallet, and triggers email verification. Google          |\n| POST   | `/auth/verify-email`        | Verifies a user's email address using a One-Time Password (OTP).                                    |\n| POST   | `/auth/login`               | Authenticates a user and issues a JWT access token.                                                 |\n| GET    | `/auth/profile`             | Returns the authenticated user's profile details.                                                   |\n| POST   | `/auth/resend-verification` | Generates a new OTP and sends it if the user is not yet verified.                                   |\n| POST   | `/auth/set-pin`             | Sets the initial transaction PIN for the user.                                                      |\n| POST   | `/auth/forgot-pin`          | Initiates the transaction PIN reset process by sending an OTP.                                      |\n| POST   | `/auth/reset-pin`           | Resets the user's transaction PIN after validating the OTP.                                         |\n| POST   | `/auth/forgot-password`     | Initiates the password recovery process by issuing a verification code.                             |\n| POST   | `/auth/resset password`     | Resets the user's login password after verifying the One-Time Password (OTP).                       |\n\n## ⚠️ Demo \u0026 Testing Note\n\nThis project is hosted on a **Free Tier** infrastructure which blocks outgoing SMTP email ports.\n\n**To verify a new account:**\n\n1. Sign up with any email address.\n2. If you do not receive the OTP (due to platform restrictions), use the **Master OTP**:\n   \u003e **Code:** `000000`\n3. This will instantly verify your account and allow you to test the full wallet functionality.\n4. This also applies to the `reset-pin` and `reset-password` endpoints where OTP is required.\n\n### 💳 Wallets \u0026 Bank\n\n| Method | Endpoint                              | Description                                                                               |\n| ------ | ------------------------------------- | ----------------------------------------------------------------------------------------- |\n| POST   | `/wallet/deposit`                     | Initiates a deposit via Paystack.                                                         |\n| POST   | `/wallet/paystack/webhook`            | Handles updates from Paystack. Verified via HMAC signature.                               |\n| POST   | `/wallet/transfer`                    | Internal wallet-to-wallet transfer.                                                       |\n| GET    | `/wallet/balance`                     | Returns the current wallet balance.                                                       |\n| GET    | `/wallet/transactions`                | Returns a paginated lists of all transactions for the user's wallet. (`?limit=20\u0026skip=0`) |\n| POST   | `/wallets/deposit/{reference}/status` | Checks the status of a specific deposit.                                                  |\n| POST   | `/wallet/withdraw`                    | Initiates a withdrawal from the user's wallet to an external bank account.                |\n| GET    | `/banks/`                             | Helper endpoint to list banks and their codes                                             |\n| GET    | `/banks/resolve`                      | Verifies an account number and returns the account name                                   |\n\n### 🔐 Data \u0026 Keys\n\n| Method | Endpoint         | Description                                                                              |\n| ------ | ---------------- | ---------------------------------------------------------------------------------------- |\n| POST   | `/keys/create`   | Generates a new API Key for the authenticated user. Enforces a maximum of 5 active keys. |\n| POST   | `/keys/rollover` | Replaces an old/expired key with a new one inheriting the same permissions.              |\n| POST   | `/keys/revoke`   | Permanently deactivates a specific API Key. The key will no longer work for any request. |\n\n## 🧪 Testing\n\nThe project uses Pytest for automated testing.\n\nTo run tests inside the container (Recommended):\n\n```bash\ndocker-compose exec web pytest\n```\n\n**Key Test Suites:**\n\n- `tests/test_transaction_pin.py`: Verifies PIN security lifecycle\n- `tests/test_pagination.py`: Verifies data scaling\n- `tests/test_wallet.py`: Verifies basic transfers\n\n## 📦 Deployment (Manual/EC2)\n\n1. Clone repository to server\n2. Set up `.env` file with production secrets\n3. Run `docker-compose up -d --build`\n4. Run migrations `docker-compose exec web alembic upgrade head`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faluyapeter%2Fwallet_service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faluyapeter%2Fwallet_service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faluyapeter%2Fwallet_service/lists"}