AlphaPay 0.0.4

AlphaPay

Unified payment abstraction for .NET — One clean interface for Stripe, PayPal, Checkout.com, M-Pesa, Microsoft Store, 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

One package includes everything:

dotnet add package AlphaPay

Includes 8 payment providers out of the box:

• ✅ Stripe (Global)
• ✅ PayPal (Global)
• ✅ Checkout.com (Global)
• ✅ M-Pesa (Africa - Kenya)
• ✅ Paystack (Africa)
• ✅ Flutterwave (Africa)
• ✅ Razorpay (India)
• ✅ Square (Global)

For Windows apps (separate package):

dotnet add package AlphaPay.Providers.MicrosoftStore  # Windows Store integration

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

using AlphaPay.Providers.Stripe;
using AlphaPay.Providers.PayPal;
using AlphaPay.Providers.Checkout;
using AlphaPay.Providers.Mpesa;

var gateway = new PaymentGateway()
    .UseStripe("sk_test_STRIPE_KEY", setAsDefault: true)
    .UsePayPal("CLIENT_ID", "CLIENT_SECRET", useSandbox: true)
    .UseCheckout("sk_test_CHECKOUT_KEY", useSandbox: 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 PayPal
var paypalPayment = await gateway.CreatePaymentAsync("PayPal", new PaymentRequest
{
    Amount = 50.00m,
    Currency = "USD",
    CustomerEmail = "customer@example.com",
    Reference = "ORDER-002"
});

// Use Checkout.com
var checkoutPayment = await gateway.CreatePaymentAsync("Checkout.com", new PaymentRequest
{
    Amount = 75.50m,
    Currency = "EUR",
    Reference = "ORDER-003"
});

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

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

using AlphaPay.Providers.Stripe;

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

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

PayPal Configuration

using AlphaPay.Providers.PayPal;

var paypalConfig = new PayPalConfiguration
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET",
    UseSandbox = true,
    WebhookId = "YOUR_WEBHOOK_ID"
};

var gateway = new PaymentGateway().UsePayPal(paypalConfig);

// Create payment
var result = await gateway.CreatePaymentAsync("PayPal", new PaymentRequest
{
    Amount = 99.99m,
    Currency = "USD",
    Description = "Product Purchase",
    Reference = "ORDER-123"
});

// If payment requires customer approval
if (result.PaymentUrl != null)
{
    Console.WriteLine($"Redirect customer to: {result.PaymentUrl}");
}

Checkout.com Configuration

using AlphaPay.Providers.Checkout;

var checkoutConfig = new CheckoutConfiguration
{
    SecretKey = "sk_test_...",
    PublicKey = "pk_test_...",
    UseSandbox = true,
    WebhookSignatureKey = "YOUR_SIGNATURE_KEY"
};

var gateway = new PaymentGateway().UseCheckout(checkoutConfig);

// Create payment
var result = await gateway.CreatePaymentAsync("Checkout.com", new PaymentRequest
{
    Amount = 49.99m,
    Currency = "GBP",
    CustomerEmail = "customer@example.com",
    Reference = "INV-456"
});

M-Pesa Configuration

using AlphaPay.Providers.Mpesa;

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 Package)
├── Core/
│   ├── IPaymentProvider (interface)
│   ├── PaymentProviderBase (base class)
│   ├── PaymentRequest, PaymentResult (models)
│   ├── PaymentGateway (facade)
│   └── PaymentException (errors)
│
├── Providers/ (All built-in)
│   ├── Stripe/
│   │   └── StripeProvider : PaymentProviderBase
│   ├── PayPal/
│   │   └── PayPalProvider : PaymentProviderBase
│   ├── Checkout/
│   │   └── CheckoutProvider : PaymentProviderBase
│   └── Mpesa/
│       └── MpesaProvider : PaymentProviderBase

AlphaPay.Providers.MicrosoftStore (Separate - Windows only)
└── MicrosoftStoreProvider : IPaymentProvider

Your App
└── Uses PaymentGateway with any provider

Building & Publishing

Build All Projects

dotnet build -c Release

Pack NuGet Packages

# Pack main library (includes all cross-platform providers)
dotnet pack AlphaPay/AlphaPay.csproj -c Release

# Pack Windows-specific provider
dotnet pack AlphaPay.Providers.MicrosoftStore/AlphaPay.Providers.MicrosoftStore.csproj -c Release

Publish to NuGet

# Publish main package (includes Stripe, PayPal, Checkout.com, M-Pesa)
dotnet nuget push AlphaPay/bin/Release/AlphaPay.0.0.2.nupkg \
    -k YOUR_API_KEY \
    -s https://api.nuget.org/v3/index.json

# Publish MicrosoftStore provider separately
dotnet nuget push AlphaPay.Providers.MicrosoftStore/bin/Release/AlphaPay.Providers.MicrosoftStore.0.0.1.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 ✅

Built into AlphaPay core (v0.0.4):

• Stripe - Payment Intents, refunds, webhooks with HMAC-SHA256 validation
• PayPal - Orders API, OAuth 2.0 authentication, refunds
• Checkout.com - Payments API, refunds, webhook signature validation
• M-Pesa - Safaricom mobile money, STK Push, callbacks
• Paystack - Transaction API (Africa), webhooks, HMAC-SHA512 validation
• Flutterwave - Payments API (Africa), refunds, webhook hash validation
• Razorpay - Orders API (India), refunds, HMAC-SHA256 webhooks
• Square - Payments API v2, refunds, webhook signature validation

Separate package (Windows-specific):

• MicrosoftStore - Microsoft Store Commerce for Windows apps (MSIX)

Providers In Development

• Adyen 🚧 - Adyen global platform
• Braintree 🚧 - Braintree (PayPal)
• Authorize.Net 🚧 - Authorize.Net payment gateway

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