PayBridge 1.0.0

PayBridge

Official .NET SDK for the Payment Aggregator Central API.

Use this package to create and manage payment intents, confirm or capture payments, issue refunds, manage stores, read store transactions, and validate merchant webhook payloads.

Installation

Install from NuGet:

dotnet add package PayBridge --version 1.0.0

Package Manager Console:

Install-Package PayBridge -Version 1.0.0

Requirements

• .NET 8.0 or any platform compatible with .NET Standard 2.1
• A Payment Aggregator API key for protected payment and store operations

Store registration does not require an API key. The registration response returns the store API key, and that key is used for the next SDK calls.

You do not need to configure BaseUrl; the SDK uses the hosted Payment Aggregator API by default.

Configure With Dependency Injection

For ASP.NET Core or any app using IServiceCollection, register the SDK once at startup. ApiKey is optional if the app only needs to register a store first:

using PaymentAggregator.Sdk.Extensions;

builder.Services.AddPaymentAggregatorClient(options =>
{
    options.ApiKey = builder.Configuration["PaymentAggregator:ApiKey"] ?? string.Empty;
    options.Timeout = TimeSpan.FromSeconds(30);
});

If you only need the default hosted API and will set the key later, you can register without options:

builder.Services.AddPaymentAggregatorClient();

Add configuration to appsettings.json:

{
  "PaymentAggregator": {
    "ApiKey": "your-store-api-key"
  }
}

Then inject the SDK services where needed:

using PaymentAggregator.Sdk.Models.Requests;
using PaymentAggregator.Sdk.Services;

public sealed class CheckoutService
{
    private readonly IPaymentsService _payments;

    public CheckoutService(IPaymentsService payments)
    {
        _payments = payments;
    }

    public async Task<Guid> CreatePaymentAsync(Guid storeId, CancellationToken ct = default)
    {
        var payment = await _payments.CreateIntentAsync(new CreatePaymentIntentRequest
        {
            StoreId = storeId.ToString(),
            OrderId = "ORDER-1001",
            AmountMinor = 49900,
            Currency = "INR",
            ProviderCode = "razorpay",
            Description = "Checkout order ORDER-1001",
            ReturnUrl = "https://merchant.example.com/payment/success",
            CancelUrl = "https://merchant.example.com/payment/cancel",
            Metadata = new
            {
                CustomerId = "CUST-1001"
            }
        }, ct);

        return payment.PaymentId;
    }
}

Register a Store First

POST /api/stores is public. You do not need an API key to register a store.

using PaymentAggregator.Sdk;
using PaymentAggregator.Sdk.Models.Requests;

var client = new PaymentAggregatorClient();

var store = await client.Stores.RegisterAsync(new RegisterStoreRequest
{
    Name = "Demo Store",
    WebhookUrl = "https://merchant.example.com/webhooks/payment-aggregator"
});

var storeId = store.Id;
var apiKey = store.ApiKey;

client.SetApiKey(apiKey);

After SetApiKey, the same client can call protected endpoints:

var gateways = await client.Stores.GetGatewaysAsync(storeId);

Regenerate a Store API Key

Use the current store API key to request a replacement key:

client.SetApiKey(currentApiKey);

var regenerated = await client.Stores.RegenerateApiKeyAsync(storeId);
var newApiKey = regenerated.ApiKey;

client.SetApiKey(newApiKey);

After regeneration, the old API key is no longer valid. Store the new key securely.

Configure Directly

For console apps, workers, or small integrations, create the client directly:

using PaymentAggregator.Sdk;
using PaymentAggregator.Sdk.Models.Requests;

var client = new PaymentAggregatorClient(options =>
{
    options.ApiKey = "your-store-api-key";
});

var payment = await client.Payments.CreateIntentAsync(new CreatePaymentIntentRequest
{
    StoreId = "2ed4ce99-6a35-4bb0-8bcf-5f3504c7899b",
    OrderId = "ORDER-1001",
    AmountMinor = 49900,
    Currency = "INR",
    ProviderCode = "razorpay"
});

ProviderCode accepts provider names or numeric provider code strings. The SDK serializes them to the enum value expected by the API:

ProviderCode = "payu";      // sends 12
ProviderCode = "12";        // sends 12
ProviderCode = "razorpay";  // sends 3

Payment Operations

Create a payment intent:

var payment = await client.Payments.CreateIntentAsync(new CreatePaymentIntentRequest
{
    StoreId = storeId.ToString(),
    OrderId = "ORDER-1001",
    AmountMinor = 49900,
    Currency = "INR",
    ProviderCode = "razorpay",
    ReturnUrl = "https://merchant.example.com/success",
    CancelUrl = "https://merchant.example.com/cancel"
});

Confirm a payment:

var confirmed = await client.Payments.ConfirmAsync(payment.PaymentId, new ConfirmPaymentRequest
{
    ProviderSpecific = new Dictionary<string, string>
    {
        ["payment_method"] = "card"
    }
});

Capture a payment:

var captured = await client.Payments.CaptureAsync(payment.PaymentId, new CapturePaymentRequest
{
    AmountMinor = 49900
});

Refund a payment:

var refund = await client.Payments.RefundAsync(payment.PaymentId, new RefundPaymentRequest
{
    AmountMinor = 49900,
    Reason = "Customer requested refund"
});

Get payment status:

var latest = await client.Payments.GetAsync(payment.PaymentId);

Store Operations

Register a store:

var store = await client.Stores.RegisterAsync(new RegisterStoreRequest
{
    Name = "Demo Store",
    WebhookUrl = "https://merchant.example.com/webhooks/payment-aggregator"
});

Get store details:

var storeDetails = await client.Stores.GetByIdAsync(store.Id);

Get enabled gateways for a store:

var gateways = await client.Stores.GetGatewaysAsync(store.Id);

List store transactions:

var transactions = await client.Stores.GetTransactionsAsync(store.Id, new GetTransactionsRequest
{
    Status = "succeeded",
    Currency = "INR",
    PageNumber = 1,
    PageSize = 20
});

Update webhook URL:

await client.Stores.UpdateWebhookUrl(store.Id, new UpdateWebhookRequest
{
    WebhookUrl = "https://merchant.example.com/webhooks/payment-aggregator"
});

Webhook Validation

Use IWebhooksService to verify that webhook payloads came from Payment Aggregator.

using PaymentAggregator.Sdk.Services;

app.MapPost("/webhooks/payment-aggregator", async (
    HttpRequest request,
    IWebhooksService webhooks,
    IConfiguration configuration) =>
{
    using var reader = new StreamReader(request.Body);
    var rawBody = await reader.ReadToEndAsync();

    var signature = request.Headers["X-Signature"].ToString();
    var secret = configuration["PaymentAggregator:WebhookSecret"]!;

    if (!webhooks.ValidateSignature(rawBody, signature, secret))
    {
        return Results.Unauthorized();
    }

    var webhookEvent = webhooks.ParseEvent(rawBody);
    if (webhookEvent is null)
    {
        return Results.BadRequest();
    }

    // Handle webhookEvent.EventType and webhookEvent.Status here.
    return Results.Ok();
});

Configuration Options

PaymentAggregatorClientOptions supports:

API Surface

The SDK exposes:

• PaymentAggregatorClient.Payments
• PaymentAggregatorClient.Stores
• PaymentAggregatorClient.Webhooks
• IPaymentsService
• IStoresService
• IWebhooksService

IStoresService includes RegenerateApiKeyAsync(storeId) for rotating a store API key.

Finding This Package on NuGet

Search for the package by ID:

PayBridge

Useful NuGet search queries:

PayBridge
PayBridge sdk
paybridge payment aggregator
paybridge dotnet
payment aggregator sdk dotnet
payment gateway orchestration dotnet
multi-gateway payment sdk
razorpay paypal stripe sdk
payu cashfree telr sdk
adyen mollie checkout sdk
tag:paybridge
tag:payment-aggregator
tag:payment-gateway
tag:payment-orchestration
tag:multi-gateway
id:PayBridge
packageid:PayBridge

The package is tagged across the following categories to make it easy to find:

NuGet search uses package metadata such as package ID, title, tags, author, description, summary, owner, and version. The package metadata is maintained in PaymentAggregator.Sdk.csproj.

Error Handling

SDK calls may throw:

• PaymentAggregatorException for API or transport failures
• PaymentAggregatorValidationException for validation failures
• standard .NET exceptions such as ArgumentException when required options are missing

Example:

using PaymentAggregator.Sdk.Exceptions;

try
{
    var payment = await client.Payments.GetAsync(paymentId);
}
catch (PaymentAggregatorValidationException ex)
{
    // Handle validation errors.
}
catch (PaymentAggregatorException ex)
{
    // Handle API errors.
}

Supported Providers

Provider routing depends on your Payment Aggregator server configuration. Common provider codes include:

• stripe
• paypal
• razorpay
• payu
• cashfree
• paytabs
• telr
• mollie
• checkout
• adyen
• square
• worldpay

Pack and Publish

Build a .nupkg:

dotnet pack src/PaymentAggregator.Sdk/PaymentAggregator.Sdk.csproj -c Release -o ./nupkgs

Push to NuGet:

dotnet nuget push ./nupkgs/PayBridge.1.0.0.nupkg --api-key YOUR_NUGET_API_KEY --source https://api.nuget.org/v3/index.json

NuGet displays this README because the project includes PackageReadmeFile metadata.