Synetec.Payment.Gateway 4.1.0

Synetec.Payment.Gateway

A .NET 8 library for integrating Stripe payment processing into your applications, with support for both hosted and embedded checkout experiences. Optimized for Blazor and ASP.NET Core projects.

✨ Features

• Stripe Hosted Checkout (redirect-based)
• Stripe Embedded Checkout (Stripe Elements)
• Product and price retrieval from Stripe Portal
• Secure, validated Stripe webhook endpoint

📦 Installation

Add the NuGet package to your project:

dotnet add package Synetec.Payment.Gateway

🚀 Usage

1. Register Endpoints

In your Program.cs (Blazor or ASP.NET Core):

// Register the Payment Gateway context and services
var builder = WebApplication.CreateBuilder(args);
ConfigurationManager configuration = builder.Configuration;
builder.Services.AddPaymentGateway(configuration);

// Register Synetec.Payment.Gateway endpoints depending on your needs
var app = builder.Build();
app.AddStripeProductEndpoints();
app.AddStripeHostedCheckoutEndpoints();
app.AddStripeEmbeddedCheckoutEndpoints();
app.AddStripeWebhook();

app.Run();

2. Configuration

Add your Stripe settings to appsettings.json:

{
  "PaymentGateway": {
    "ConnectionString": "REDACTED",
    "RedirectBaseUrl": "REDACTED",
    "SuccessPath": "REDACTED",
    "CancelPath": "REDACTED",
    "Stripe": {
      "SecretKey": "REDACTED",
      "PublishableKey": "REDACTED",
      "WebhookSecret": "REDACTED",
      "ThrowOnApiVersionMismatch": false
    }
  }
}

ThrowOnApiVersionMismatch (optional, defaults to false)

A Stripe webhook endpoint is pinned to the API version that was current when it was created, and that pin only moves when someone changes it in the Stripe dashboard. It therefore drifts independently of the Stripe.net version this package ships with.

When the two are on different release trains, EventUtility.ConstructEvent throws. Leave this false — the event is processed anyway and the mismatch is logged as a warning. Setting it to true restores Stripe.net's strict behaviour, which rejects the event outright; only do that if you would rather lose the event than risk deserialising a payload shape your handlers were not written against.

Keep the endpoint's API version in the Stripe dashboard aligned with the release train this package expects. Watch for Stripe webhook API version drift warnings — they mean the two have diverged.

3. Endpoints

Get Products

• GET /api/v{version}/stripe/product
• Returns a list of Stripe products and prices.

Create Hosted Checkout Session

• POST /api/v{version}/stripe/checkout
• Request body: CheckoutRequest
• Returns a Stripe Checkout session URL.

Create Embedded Payment Intent

• POST /api/v{version}/stripe/initialize-payment
• Request body: PaymentIntentRequest
• Returns a Stripe PaymentIntent client secret.

Stripe Webhook

• POST /api/v{version}/stripe/webhook
• Receives Stripe webhook events for payment updates and notifications.

4. Example: Creating a Checkout Session

POST /api/v1/stripe/checkout
Content-Type: application/json

{
  "idempotencyKey": "b1a7c8e2-1234-4c9a-8e2b-1234567890ab",
  "items": [
    { "priceId": "price_1N...", "quantity": 1 }
  ],
  "paymentMethodTypes": ["card"],
  "consumerReference": "user@example.com",
  "additionalMetadata": { "orderId": "12345" }
}

5. Webhook Security

Set your Stripe webhook secret in configuration. The webhook endpoint validates incoming requests using the Stripe-Signature header.

6. Ignored Events

A Stripe account receives webhooks for every payment on it, not only the ones this library created. Events that need no action from us are recorded as ignored rather than failed: they are logged at Information, and written to PaymentWebhookLog with Status = Ignored (4), an IgnoredReason explaining why, and ProcessedAtUtc as the actioned timestamp. Nothing is logged at Error.

An event is ignored when:

• its PaymentRecordId metadata does not resolve to a payment record in this database — this is how instances sharing one Stripe account avoid claiming each other's payments;
• it carries neither PaymentRecordId nor ConsumerReference metadata, so nothing identifies it as ours;
• its ConsumerReference matches no payment record; or
• no handler is registered for that Stripe event type.

Origin is decided by PaymentRecordId, a GUID this library mints and persists before the client sees anything. Note this is a correlation check, not a security control — the Stripe-Signature validation above remains the security boundary.

Ignored events are kept so they can be reviewed. To pull them for a period — this query uses the IX_PaymentWebhookLog_Status_ProcessedAtUtc index:

SELECT Id, ProcessedAtUtc, ReceivedAtUtc, EventId, EventType, IgnoredReason
FROM PaymentGateway.PaymentWebhookLog
WHERE Status = 4                      -- Ignored
  AND ProcessedAtUtc >= @fromUtc      -- start of day / week / month
  AND ProcessedAtUtc <  @toUtc
ORDER BY ProcessedAtUtc DESC;

Payload holds the raw Stripe event and carries personal data. If you surface these for review, reference Id and IgnoredReason rather than copying payload contents.

Applying the migration that adds these columns is required when upgrading to 4.1.0.

🧩 Getting Started Example

// Example: Minimal API integration
var builder = WebApplication.CreateBuilder(args);
builder.Services.Configure<StripeOptions>(builder.Configuration.GetSection("Stripe"));

var app = builder.Build();
app.AddStripeHostedCheckoutEndpoints();
app.Run();

🛠️ Requirements

• .NET 8.0 or later
• Stripe account and API keys

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Run tests with dotnet test
4. Submit a pull request

📜 License

© 2025 Synetec Limited. All rights reserved.