Paystack Demo API

A .NET 10 Web API application that demonstrates integration with Paystack payment gateway for processing payments in Nigeria. This project provides endpoints to initialize payments, verify transactions, and manage transaction records using SQLite database.

🚀 Features

• Payment Initialization: Initialize Paystack payments with customer email and amount
• Payment Verification: Verify payment status using transaction reference
• Transaction Management: Store and retrieve transaction records
• Automatic Database Migration: Database and tables are created automatically on startup
• Swagger/OpenAPI Documentation: Interactive API documentation
• Idempotency: Prevents duplicate transaction processing using unique reference index

📋 Prerequisites

• .NET 10 SDK or later
• A Paystack account with API keys (Sign up here)
• SQLite (included with .NET)

🛠️ Technology Stack

• .NET 10: Latest .NET framework
• ASP.NET Core Web API: RESTful API framework
• Entity Framework Core 10.0.1: ORM for database operations
• SQLite: Lightweight, file-based database
• Swashbuckle (Swagger): API documentation
• Paystack API: Payment gateway integration

📁 Project Structure

PaystackDemo.Api/
├── PaystackDemo.Api/              # Main API project
│   ├── Controllers/               # API controllers
│   │   ├── PaymentsController.cs  # Payment endpoints
│   │   └── TransactionsController.cs # Transaction endpoints
│   ├── Program.cs                 # Application entry point
│   └── appsettings.json           # Configuration
│
├── PaystackDemo.Application/      # Application layer
│   ├── Interfaces/                # Service interfaces
│   ├── Models/                    # Domain models
│   ├── Repository/                # Data access
│   │   └── AppDbContext.cs        # EF Core DbContext
│   ├── Services/                  # Business logic
│   │   ├── PaystackService.cs     # Paystack integration
│   │   └── TransactionService.cs  # Transaction management
│   └── Migrations/                 # Database migrations
│
└── PaystackDemo.Infrastructure/   # Infrastructure layer
    └── HttpClientExtension.cs      # HTTP client extensions

🔧 Setup & Installation

1. Clone the Repository

git clone <repository-url>
cd PaystackDemo.Api

2. Configure Paystack API Key

Edit PaystackDemo.Api/appsettings.json and add your Paystack secret key:

{
  "Paystack": {
    "SecretKey": "sk_test_your_secret_key_here"
  }
}

Note:

• Use sk_test_... for test mode
• Use sk_live_... for production
• Get your keys from Paystack Dashboard

3. Restore Dependencies

dotnet restore

4. Build the Project

dotnet build

5. Run the Application

dotnet run --project PaystackDemo.Api

The application will:

• Start on https://localhost:5001 (or http://localhost:5000)
• Automatically create the SQLite database (paystack.db) if it doesn't exist
• Apply database migrations automatically
• Launch Swagger UI at https://localhost:5001/swagger

📚 API Endpoints

Payment Endpoints

Initialize Payment

Initialize a new payment transaction with Paystack.

Endpoint: POST /api/payments/initialize

Request Body:

{
  "email": "customer@example.com",
  "amount": 500000,  // Amount in kobo (500000 = ₦5,000.00)
  "callbackUrl": "https://yourwebsite.com/payment/callback"
}

Response (Success):

{
  "status": true,
  "message": "Authorization URL created",
  "data": {
    "authorization_url": "https://checkout.paystack.com/...",
    "access_code": "access_code_here",
    "reference": "transaction_reference_here"
  }
}

Response (Error):

{
  "success": false,
  "error": "Error message here"
}

Verify Payment

Verify the status of a payment transaction.

Endpoint: GET /api/payments/verify/{reference}

Parameters:

• reference (path): The transaction reference returned from initialization

Response (Success):

{
  "status": true,
  "message": "Verification successful",
  "data": {
    "status": "success",
    "reference": "transaction_reference",
    "amount": 500000,
    "currency": "NGN",
    "paid_at": "2024-01-01T12:00:00.000Z"
  }
}

Transaction Endpoints

Get All Transactions

Retrieve all stored transactions from the database.

Endpoint: GET /api/transactions

Response:

[
  {
    "id": "guid-here",
    "reference": "transaction_reference",
    "amount": 500000,
    "currency": "NGN",
    "status": "success",
    "createdAt": "2024-01-01T10:00:00.000Z",
    "paidAt": "2024-01-01T12:00:00.000Z"
  }
]

🗄️ Database Schema

The application uses SQLite with the following schema:

Transactions Table

Column	Type	Description
Id	GUID	Primary key
Reference	String (Unique)	Paystack transaction reference
Amount	Decimal(18,2)	Transaction amount
Currency	String	Currency code (default: NGN)
Status	String(20)	Transaction status (pending/success)
CreatedAt	DateTime	Transaction creation timestamp
PaidAt	DateTime?	Payment completion timestamp

Indexes:

• Primary key on Id
• Unique index on Reference (for idempotency)

🔐 Security Considerations

1. API Keys: Never commit your Paystack secret keys to version control
2. HTTPS: Always use HTTPS in production
3. Environment Variables: Consider using environment variables or Azure Key Vault for sensitive configuration
4. Input Validation: Add validation attributes to request models
5. Rate Limiting: Implement rate limiting for production use

🧪 Testing

Using Swagger UI

1. Navigate to https://localhost:5001/swagger
2. Use the interactive UI to test endpoints
3. Click "Try it out" on any endpoint
4. Fill in the required parameters
5. Click "Execute" to send the request

Using cURL

Initialize Payment:

curl -X POST "https://localhost:5001/api/payments/initialize" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "amount": 500000,
    "callbackUrl": "https://yourwebsite.com/callback"
  }'

Verify Payment:

curl -X GET "https://localhost:5001/api/payments/verify/transaction_reference_here"

Get All Transactions:

curl -X GET "https://localhost:5001/api/transactions"

🔄 Database Migrations

The application automatically applies migrations on startup. However, you can manually manage migrations:

Create a Migration

dotnet ef migrations add MigrationName --project PaystackDemo.Application --startup-project PaystackDemo.Api

Apply Migrations

dotnet ef database update --project PaystackDemo.Application --startup-project PaystackDemo.Api

Remove Last Migration

dotnet ef migrations remove --project PaystackDemo.Application --startup-project PaystackDemo.Api

📝 Configuration

appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Paystack": {
    "SecretKey": "sk_test_your_key_here"
  },
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=paystack.db"
  }
}

Environment-Specific Configuration

Create appsettings.Development.json for development settings:

{
  "Paystack": {
    "SecretKey": "sk_test_development_key"
  }
}

🐛 Troubleshooting

Database Not Found

• The database is created automatically on first run
• Ensure the application has write permissions in the project directory
• Check that migrations are being applied (see startup logs)

Paystack API Errors

• Verify your secret key is correct
• Check your Paystack account status
• Ensure you're using the correct key type (test vs live)
• Review Paystack API documentation for error codes

Migration Errors

• Ensure Entity Framework Core tools are installed: dotnet tool install --global dotnet-ef
• Verify connection string is correct
• Check that the database file isn't locked by another process

📖 Additional Resources

• Paystack API Documentation
• Entity Framework Core Documentation
• ASP.NET Core Documentation
• .NET 10 Documentation

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Created as a demonstration project for Paystack payment integration.

🙏 Acknowledgments

• Paystack for providing excellent payment gateway services
• .NET team for the robust framework
• Entity Framework Core team for the powerful ORM

---

Note: This is a demo project. For production use, implement additional security measures, error handling, logging, and testing.