Wallet & Payment System
Seamless payment and withdrawal system with automatic Hedera account management. Users never need to worry about wallets or HBAR complexity.
Overview
MediPact's payment system is designed to be completely user-friendly. Users (patients and hospitals) receive payments automatically in their Hedera wallets, which are created and managed by the platform. All balances are displayed in USD (with HBAR shown below), and withdrawals can be sent directly to bank accounts or mobile money.
Key Principle: Users should never need to understand Hedera, wallets, or HBAR. The system handles all blockchain complexity behind the scenes.
Automatic Wallet Creation
When a user (patient, hospital, or researcher) registers with MediPact, a Hedera account is automatically created for them. The platform:
- Generates a secure ECDSA key pair
- Creates an EVM-compatible Hedera account (0.0.xxxxx format)
- Pays for account creation fees
- Stores encrypted private keys securely
- Links the account to the user's profile
Users can view their Hedera Account ID and EVM Address in their wallet page, but they never need to interact with these directly.
Balance Display
All balances are displayed with USD as the primary currency, making it easy for users to understand their earnings:
Exchange rates are fetched dynamically from CoinGecko API and cached for 5 minutes to ensure accurate USD conversions.
Payment Methods
Users can configure their preferred payment method during registration or in settings:
Bank Account
- • Bank name
- • Account number (encrypted)
- • Direct bank transfer
Mobile Money
- • Provider (MTN, Airtel, Vodafone, Tigo)
- • Phone number (encrypted)
- • Instant mobile money transfer
Security: All payment account numbers and mobile money numbers are encrypted using AES-256-GCM before storage. They are only decrypted when needed for withdrawal processing.
Withdrawal Process
Manual Withdrawal
Users can initiate withdrawals at any time from their wallet page. They specify the amount in USD, and the system handles the HBAR conversion automatically.
Automatic Withdrawal
Users can enable automatic withdrawals with a threshold (e.g., $10 for patients, $100 for hospitals). When the balance reaches the threshold, a withdrawal is automatically initiated. Users receive a notification when the threshold is reached.
Withdrawal Status & Notifications
Users receive notifications at each stage of the withdrawal process:
Pending
Withdrawal request received and queued for processing
Processing
Funds are being transferred to your bank account or mobile money
Completed
Funds successfully transferred. Transaction ID provided for reference.
Failed
Withdrawal could not be processed. Funds remain in wallet. System will automatically retry with exponential backoff.
Error Handling & Retry Logic
The system includes comprehensive error handling and automatic retry mechanisms:
- Exponential Backoff: Failed withdrawals are retried with increasing delays (5s, 10s, 20s, up to 60s max)
- Maximum Retries: Up to 3 automatic retries before marking as failed
- Admin Retry: Admins can manually retry failed withdrawals from the admin dashboard
- Non-Critical Notifications: Notification failures don't block withdrawals
- Transaction Logging: All withdrawal attempts are logged for audit purposes
Revenue Distribution
When researchers purchase datasets, revenue is automatically distributed:
Important: The hospital from which the data was originally collected remains the sole beneficiary of that data's revenue, ensuring fair compensation for data collection efforts.
API Endpoints
1# Get wallet balance
2GET /api/patient/:upi/wallet
3GET /api/hospital/:hospitalId/wallet
4
5# Initiate withdrawal
6POST /api/patient/:upi/withdraw
7POST /api/hospital/:hospitalId/withdraw
8Body: { "amountUSD": 100.00 }
9
10# Get withdrawal history
11GET /api/patient/:upi/withdrawal-history
12GET /api/hospital/:hospitalId/withdrawal-history
13
14# Update payment method
15PUT /api/patient/:upi/payment-method
16PUT /api/hospital/:hospitalId/payment-method
17Body: {
18 "paymentMethod": "bank",
19 "bankName": "Bank of Uganda",
20 "bankAccountNumber": "1234567890",
21 "withdrawalThresholdUSD": 10.00,
22 "autoWithdrawEnabled": true
23}Admin Features
Administrators have access to a comprehensive withdrawal management dashboard:
- View all withdrawals with filtering by status, user type, date range
- View withdrawal statistics (total, pending, completed, failed amounts)
- Manually complete pending withdrawals after processing payments
- Retry failed withdrawals in bulk
- Trigger monthly automatic withdrawals for all eligible users
- Monitor withdrawal trends and patterns
Security Features
Encryption at Rest
Bank account numbers and mobile money numbers are encrypted using AES-256-GCM before storage. Keys are managed securely and never exposed.
Private Key Management
Hedera private keys are encrypted and stored securely. Users never need to manage or see their private keys.
Access Control
Users can only access their own wallet information. All API endpoints are protected with authentication middleware.
Future Enhancements
Planned improvements to the payment system:
- Integration with payment gateways (Flutterwave, Paystack) for automated bank and mobile money transfers
- Real-time withdrawal status updates via webhooks
- Multi-currency support for international users
- Scheduled withdrawals (e.g., monthly, weekly)
- Withdrawal limits and daily caps for security
- Email and SMS notifications for all withdrawal events