AlphaPay 0.0.1

AlphaPay

Unified payment abstraction for .NET — One clean interface for Stripe, M-Pesa, Microsoft Store, PayPal, Paystack, and more.

Why AlphaPay?

Global payment systems are incompatible by design. Each has its own authentication, signatures, webhook formats, and error codes. AlphaPay provides a clean abstraction layer so you can:

• Switch payment providers without rewriting your code
• Support multiple providers simultaneously
• Mock payments easily for testing
• Add new providers without touching existing code

Installation

Install the core library:

dotnet add package AlphaPay

Then add the providers you need:

dotnet add package AlphaPay.Providers.Stripe
dotnet add package AlphaPay.Providers.Mpesa
dotnet add package AlphaPay.Providers.MicrosoftStore  # For Windows apps with MSIX

Quick Start

Single Provider (Stripe)

using AlphaPay;
using AlphaPay.Core;
using AlphaPay.Providers.Stripe;

var gateway = new PaymentGateway()
    .UseStripe("sk_test_YOUR_STRIPE_KEY");

var result = await gateway.CreatePaymentAsync(new PaymentRequest
{
    Amount = 50.00m,
    Currency = "USD",
    CustomerEmail = "customer@example.com",
    Reference = "ORDER-12345",
    Description = "Premium subscription"
});

if (result.Success)
{
    Console.WriteLine($"Payment successful! ID: {result.TransactionId}");
}
else
{
    Console.WriteLine($"Payment failed: {result.ErrorMessage}");
}

Multiple Providers

var gateway = new PaymentGateway()
    .UseStripe("sk_test_STRIPE_KEY", setAsDefault: true)
    .UseMpesa(
        consumerKey: "YOUR_MPESA_KEY",
        consumerSecret: "YOUR_MPESA_SECRET",
        shortCode: "174379",
        passkey: "YOUR_PASSKEY",
        environment: MpesaEnvironment.Sandbox
    );

// Use default provider (Stripe)
var stripePayment = await gateway.CreatePaymentAsync(new PaymentRequest
{
    Amount = 100.00m,
    Currency = "USD",
    CustomerEmail = "user@example.com",
    Reference = "ORDER-001"
});

// Use specific provider (M-Pesa)
var mpesaPayment = await gateway.CreatePaymentAsync("M-Pesa", new PaymentRequest
{
    Amount = 1000m,
    Currency = "KES",
    CustomerPhone = "254712345678",
    Reference = "ORDER-002"
});

Core Features

1. Create Payment

var request = new PaymentRequest
{
    Amount = 25.99m,
    Currency = "USD",
    CustomerEmail = "john@example.com",
    CustomerPhone = "254712345678", // Required for M-Pesa
    Reference = "INV-2024-001",
    Description = "Product purchase",
    CallbackUrl = "https://yourapp.com/webhook",
    Metadata = new Dictionary<string, string>
    {
        ["user_id"] = "12345",
        ["product_id"] = "SKU-789"
    }
};

var result = await gateway.CreatePaymentAsync(request);

2. Verify Payment

var result = await gateway.VerifyPaymentAsync("txn_1234567890");

Console.WriteLine($"Status: {result.Status}");
Console.WriteLine($"Amount: {result.Amount} {result.Currency}");

3. Refund Payment

var refund = await gateway.RefundAsync(
    transactionId: "txn_1234567890",
    amount: 25.99m,
    reason: "Customer requested refund"
);

if (refund.Success)
{
    Console.WriteLine($"Refund ID: {refund.RefundId}");
}

4. Handle Webhooks

// In your ASP.NET Core controller
[HttpPost("webhook/stripe")]
public async Task<IActionResult> StripeWebhook()
{
    var payload = await new StreamReader(Request.Body).ReadToEndAsync();
    var headers = Request.Headers.ToDictionary(h => h.Key, h => h.Value.ToString());

    try
    {
        var webhookEvent = await gateway.ParseWebhookAsync("Stripe", payload, headers);

        if (webhookEvent.IsValid && webhookEvent.Status == PaymentStatus.Success)
        {
            // Update your database
            await UpdateOrder(webhookEvent.Reference, "paid");
        }

        return Ok();
    }
    catch (WebhookValidationException ex)
    {
        return BadRequest(ex.Message);
    }
}

Provider-Specific Examples

Stripe Configuration

var stripeConfig = new StripeConfiguration
{
    SecretKey = "sk_test_...",
    WebhookSecret = "whsec_...", // For webhook validation
    ApiVersion = "2023-10-16"
};

var gateway = new PaymentGateway().UseStripe(stripeConfig);

M-Pesa Configuration

var mpesaConfig = new MpesaConfiguration
{
    ConsumerKey = "YOUR_KEY",
    ConsumerSecret = "YOUR_SECRET",
    ShortCode = "174379",
    Passkey = "YOUR_PASSKEY",
    Environment = MpesaEnvironment.Sandbox,
    CallbackUrl = "https://yourapp.com/mpesa/callback"
};

var gateway = new PaymentGateway().UseMpesa(mpesaConfig);

Microsoft Store Configuration

using AlphaPay.Providers.MicrosoftStore;

// Simple configuration
var gateway = new PaymentGateway()
    .UseMicrosoftStore(enableDebugLogging: true);

// Or with advanced config
var storeConfig = new MicrosoftStoreConfiguration
{
    EnableDebugLogging = true,
    AllowOfflineLicenseCheck = true,
    PartnerCenterAppId = "Your app ID from Partner Center"
};

var gateway = new PaymentGateway().UseMicrosoftStore(storeConfig);

// Purchase a product (Product ID from Partner Center)
var result = await gateway.CreatePaymentAsync(new PaymentRequest
{
    Reference = "9NBLGGH4R315",  // Store Product ID
    Description = "Premium Unlock"
});

// Check subscription status
var provider = new MicrosoftStoreProvider();
var subscription = await provider.CheckSubscriptionAsync("monthly_pro");

if (subscription.IsActive)
{
    Console.WriteLine($"Subscription expires: {subscription.ExpirationDate}");
}

Note: Microsoft Store provider requires:

• Windows 10/11 app
• MSIX packaging
• Products configured in Partner Center

See MICROSOFT_STORE_GUIDE.md for complete Partner Center setup instructions.

Payment Status Flow

Pending → Processing → Success
                     ↘ Failed
                     ↘ Cancelled
                     ↘ Expired
                     ↘ RequiresAction

Architecture

AlphaPay (Core)
├── IPaymentProvider (interface)
├── PaymentRequest, PaymentResult (models)
├── PaymentGateway (facade)
└── PaymentException (errors)

AlphaPay.Providers.Stripe
└── StripeProvider : IPaymentProvider

AlphaPay.Providers.Mpesa
└── MpesaProvider : IPaymentProvider

AlphaPay.Providers.MicrosoftStore
└── MicrosoftStoreProvider : IPaymentProvider

Your App
└── Uses PaymentGateway with any provider

Building & Publishing

Build All Projects

dotnet build -c Release

Pack NuGet Packages

# Pack all projects
dotnet pack -c Release

# Individual projects
dotnet pack AlphaPay/AlphaPay.csproj -c Release
dotnet pack AlphaPay.Providers.Stripe/AlphaPay.Providers.Stripe.csproj -c Release
dotnet pack AlphaPay.Providers.Mpesa/AlphaPay.Providers.Mpesa.csproj -c Release
dotnet pack AlphaPay.Providers.MicrosoftStore/AlphaPay.Providers.MicrosoftStore.csproj -c Release

Publish to NuGet

dotnet nuget push bin/Release/AlphaPay.1.0.0.nupkg \
    -k YOUR_API_KEY \
    -s https://api.nuget.org/v3/index.json

dotnet nuget push bin/Release/AlphaPay.Providers.Stripe.1.0.0.nupkg \
    -k YOUR_API_KEY \
    -s https://api.nuget.org/v3/index.json

Adding Your Own Provider

1. Create a new class library: AlphaPay.Providers.YourProvider
2. Reference AlphaPay core library
3. Implement IPaymentProvider:

public class YourProvider : PaymentProviderBase
{
    public override string ProviderName => "YourProvider";

    public override async Task<PaymentResult> CreatePaymentAsync(
        PaymentRequest request,
        CancellationToken cancellationToken = default)
    {
        // Your implementation
    }

    // Implement other methods...
}

4. Add extension method:

public static class YourProviderExtensions
{
    public static PaymentGateway UseYourProvider(
        this PaymentGateway gateway,
        string apiKey,
        bool setAsDefault = false)
    {
        var provider = new YourProvider(apiKey);
        return gateway.AddProvider(provider, setAsDefault);
    }
}

Roadmap

Implemented Providers ✓

• AlphaPay.Providers.Stripe - Stripe payment integration
• AlphaPay.Providers.Mpesa - M-Pesa (Safaricom) mobile money
• AlphaPay.Providers.MicrosoftStore - Microsoft Store Commerce for Windows apps

Planned Providers

• AlphaPay.Providers.PayPal - PayPal integration
• AlphaPay.Providers.Paystack - Paystack (Africa)
• AlphaPay.Providers.Flutterwave - Flutterwave (Africa)
• AlphaPay.Providers.Razorpay - Razorpay (India)
• AlphaPay.Providers.Square - Square payments
• AlphaPay.Providers.Adyen - Adyen global platform

Best Practices

1. Store credentials securely

// Use configuration or secrets manager
var stripeKey = configuration["Stripe:SecretKey"];
var gateway = new PaymentGateway().UseStripe(stripeKey);

2. Always validate webhooks

var webhookEvent = await gateway.ParseWebhookAsync(
    "Stripe",
    payload,
    headers // Includes signature for validation
);

if (!webhookEvent.IsValid)
{
    return BadRequest("Invalid signature");
}

3. Handle idempotency

var request = new PaymentRequest
{
    Reference = $"ORDER-{orderId}", // Use unique reference
    Amount = 100m,
    Currency = "USD"
};

4. Log raw provider responses

var result = await gateway.CreatePaymentAsync(request);

logger.LogInformation(
    "Payment result: {Status}, Raw: {RawData}",
    result.Status,
    JsonSerializer.Serialize(result.RawData)
);

License

MIT License - see LICENSE file for details

Contributing

Contributions welcome! Please open an issue or PR.

To add a new provider:

1. Fork the repository
2. Create a new provider project following the structure
3. Add tests
4. Submit a PR

Support

• Issues: https://github.com/alphacore/alphapay/issues
• Discussions: https://github.com/alphacore/alphapay/discussions