Fintech Payment Rail Application

A comprehensive payment disbursement system built with Rust, Axum, and PostgreSQL, integrating with Paystack's Transfer API for NGN bank transfers.

Features

• User Authentication: JWT-based authentication system
• Payment Disbursement: Initiate NGN transfers to any Nigerian bank account
• Idempotency: Handle duplicate requests safely using transaction references
• Webhook Integration: Real-time status updates from Paystack
• Transaction Tracking: Complete transaction history and status monitoring
• Bank Account Validation: Support for all Nigerian banks

Transaction Statuses

• Pending: Transaction created, awaiting processing
• Processing: Transaction sent to Paystack, awaiting completion
• Completed: Transfer successful
• Failed: Transfer failed with reason

API Endpoints

Authentication

• POST /auth/register - Register a new user
• POST /auth/login - Login user
• GET /auth/profile - Get current user profile (protected)

Payment Operations

• POST /payouts - Initiate payout to bank account (protected)
• GET /transactions - Get all user transactions (protected)
• GET /transactions/:id - Get specific transaction details (protected)

Webhooks

• POST /webhooks/paystack - Paystack webhook endpoint

Setup

1. Start the database:

   cd Rust_Fin_Tech_Backend
   docker-compose up -d

2. Set up environment variables:

   cp env.example .env
   # Edit .env with your Paystack credentials

3. Run the application:

   cargo run

Environment Variables

• DATABASE_URL - PostgreSQL connection string
• JWT_SECRET - Secret key for JWT token signing
• PORT - Server port (default: 3000)
• PAYSTACK_SECRET_KEY - Your Paystack secret key
• PAYSTACK_BASE_URL - Paystack API base URL
• PAYSTACK_WEBHOOK_SECRET - Webhook signature verification secret

Example Usage

Register a user

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "john@example.com",
    "password": "password123"
  }'

Login

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "password": "password123"
  }'

Initiate a payout

curl -X POST http://localhost:3000/payouts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "amount": 1000.00,
    "bank_account_number": "1234567890",
    "bank_code": "058",
    "recipient_name": "John Doe",
    "description": "Payment for services",
    "tx_reference": "TXN_20240101_001"
  }'

Get transaction history

curl -X GET http://localhost:3000/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get specific transaction

curl -X GET http://localhost:3000/transactions/TRANSACTION_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Database Schema

Users Table

• id - UUID primary key
• username - Unique username
• email - Unique email address
• password_hash - Bcrypt hashed password
• created_at - Account creation timestamp
• updated_at - Last update timestamp

Transactions Table

• id - UUID primary key
• user_id - Foreign key to users table
• reference - Unique transaction reference (for idempotency)
• amount - Transfer amount in NGN
• bank_account_number - Recipient bank account number
• bank_code - Nigerian bank code
• bank_name - Bank name (optional)
• recipient_name - Recipient name (optional)
• description - Transaction description (optional)
• status - Transaction status (pending, processing, completed, failed)
• paystack_transfer_code - Paystack transfer code
• paystack_reference - Paystack reference
• failure_reason - Failure reason if transaction failed
• created_at - Transaction creation timestamp
• updated_at - Last update timestamp

Key Features

Idempotency

The application handles idempotency by using the tx_reference field. If a transaction with the same reference already exists for the user, it returns the existing transaction instead of creating a new one.

Webhook Security

Webhook signatures are verified using HMAC-SHA512 to ensure requests are genuinely from Paystack.

Error Handling

Comprehensive error handling with appropriate HTTP status codes and error messages.

Transaction Status Updates

Real-time status updates via Paystack webhooks ensure accurate transaction tracking.