{"title": "Direct Funding", "content": "# Direct Wallet Funding Endpoint - Temporary Solution\n\n## Overview\n\nThis document describes the temporary direct wallet funding endpoint created to bypass the ALAT payment gateway while integration issues are being resolved.\n\n**\u26a0\ufe0f IMPORTANT: This is a temporary solution for development/testing purposes only. Remove or disable in production once ALAT integration is fixed.**\n\n## Endpoint Details\n\n### POST `/api/wallets/direct-fund/`\n\nDirectly funds a user's wallet without third-party payment processing.\n\n#### Authentication\n- Requires user authentication\n- Rate limited to 20 requests per hour per user\n\n#### Request Body\n```json\n{\n  \"amount\": \"1000.00\",\n  \"currency\": \"NGN\",\n  \"description\": \"Test wallet funding\"\n}\n```\n\n#### Fields\n- `amount` (required): Decimal amount to fund (min: 0.01, max: 1,000,000.00)\n- `currency` (optional): Currency code, defaults to \"NGN\"\n- `description` (optional): Description for the transaction, defaults to \"Direct wallet funding\"\n\n#### Success Response (201)\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"Wallet funded successfully\",\n  \"data\": {\n    \"amount\": 1000.00,\n    \"new_balance\": 5000.00,\n    \"transaction_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n    \"reference\": \"TOP_123456789\",\n    \"status\": \"completed\",\n    \"funding_type\": \"direct\"\n  }\n}\n```\n\n#### Error Responses\n\n**400 Bad Request**\n```json\n{\n  \"status\": \"error\",\n  \"message\": \"Invalid input\",\n  \"errors\": {\n    \"amount\": [\"Amount must be greater than 0\"]\n  }\n}\n```\n\n**429 Too Many Requests**\n```json\n{\n  \"status\": \"error\",\n  \"message\": \"Rate limit exceeded\"\n}\n```\n\n## Usage Examples\n\n### cURL\n```bash\ncurl -X POST http://localhost:8000/api/wallets/direct-fund/ \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"amount\": \"500.00\",\n    \"description\": \"Test funding\"\n  }'\n```\n\n### JavaScript (Fetch)\n```javascript\nconst response = await fetch('/api/wallets/direct-fund/', {\n  method: 'POST',\n  headers: {\n    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    amount: '500.00',\n    description: 'Test funding'\n  })\n});\n\nconst data = await response.json();\nconsole.log(data);\n```\n\n### Python (requests)\n```python\nimport requests\n\nurl = 'http://localhost:8000/api/wallets/direct-fund/'\nheaders = {\n    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',\n    'Content-Type': 'application/json'\n}\ndata = {\n    'amount': '500.00',\n    'description': 'Test funding'\n}\n\nresponse = requests.post(url, headers=headers, json=data)\nresult = response.json()\nprint(result)\n```\n\n## Security Features\n\n1. **Authentication Required**: Only authenticated users can access this endpoint\n2. **Rate Limiting**: Maximum 20 requests per hour per user\n3. **Amount Validation**:\n   - Minimum amount: 0.01\n   - Maximum amount: 1,000,000.00\n4. **Audit Logging**: All transactions are logged for audit purposes\n5. **Atomic Operations**: Database operations are atomic to prevent inconsistencies\n\n## Implementation Details\n\n### Files Modified/Created\n\n1. **Serializer**: `payment/serializers/wallet.py`\n   - Added `DirectWalletFundingSerializer`\n\n2. **Service**: `payment/services/wallet.py`\n   - Added `direct_fund_wallet()` method\n\n3. **Controller**: `payment/controllers/wallet.py`\n   - Added `DirectWalletFundingView` class\n\n4. **URLs**: `api/urls/wallet.py`\n   - Added route: `path('direct-fund/', DirectWalletFundingView.as_view(), name='wallet-direct-fund')`\n\n### Transaction Metadata\n\nEach direct funding transaction includes the following metadata:\n```json\n{\n  \"funding_type\": \"direct\",\n  \"description\": \"User provided description\",\n  \"currency\": \"NGN\",\n  \"note\": \"Temporary direct funding - bypassing third-party integration\"\n}\n```\n\n## Differences from Regular Top-Up\n\n| Feature | Regular Top-Up | Direct Funding |\n|---------|----------------|----------------|\n| Card Required | \u2705 Yes | \u274c No |\n| Third-party Integration | \u2705 ALAT | \u274c None |\n| Transaction Status | Pending \u2192 Completed | Completed immediately |\n| 3DS Authentication | \u2705 Yes | \u274c No |\n| Payment Verification | \u2705 Required | \u274c Not needed |\n\n## Monitoring and Logging\n\n- All direct funding transactions are logged with:\n  - User ID\n  - Amount\n  - Transaction reference\n  - Balance before/after\n  - Timestamp\n\n- Search logs for: `\"Direct wallet funding\"`\n\n## Removal Instructions\n\nWhen ALAT integration is fixed, remove this temporary endpoint by:\n\n1. Delete the URL route from `api/urls/wallet.py`\n2. Remove `DirectWalletFundingView` from `payment/controllers/wallet.py`\n3. Remove `direct_fund_wallet()` method from `payment/services/wallet.py`\n4. Remove `DirectWalletFundingSerializer` from `payment/serializers/wallet.py`\n5. Delete this documentation file\n\n## Testing\n\nTo test the endpoint:\n\n1. Ensure you have a valid authentication token\n2. Use any of the usage examples above\n3. Check wallet balance before and after\n4. Verify transaction appears in transaction history\n5. Confirm notification is sent (if enabled)\n\n---\n\n**\u26a0\ufe0f Remember: This is a temporary workaround. Ensure proper payment processing is implemented before production deployment.**\n"}