Skip to content
Paylera

.NET suite: getting started

The Paylera .NET suite is two packages on NuGet:

PackageLayer
Paylera.SdkTyped HTTP client (.NET 8+).
Paylera.AspNetCoreDI + MapPayleraRelay + MapPayleraWebhooks.

You can use the typed client by itself for server-side jobs (Blazor Server, background workers, console tools); add the ASP.NET Core package on top when you also want the browser-safe relay or the inbound webhook receiver.

Install

Terminal window
dotnet add package Paylera.Sdk
dotnet add package Paylera.AspNetCore   # only for ASP.NET Core apps

Both packages target net8.0. The same code compiles unchanged against net9.0 and net10.0.

Token convention

The SDK auto-routes to the right Paylera environment based on the token prefix — no separate BaseUrl to remember:

Token prefixEffective BaseUrl
pl_live_*https://api.paylera.dev
pl_test_*https://api.test.paylera.dev

For self-hosted Paylera or local-stack tests, override explicitly:

opts.BaseUrl = new Uri("https://paylera.acme.internal");

Standalone client

The smallest possible call:

using Paylera.Sdk;


using var client = new PayleraClient("pl_test_abcdef0123456789");


var plans = await client.Api.ListPlansAsync(
    product_id: null,
    code:       null,
    status:     PlanStatus.Active,
    limit:      25,
    cursor:     null,
    sort:       null);

PayleraClient is a thin facade that owns an internal HttpClient with the auth handler, retry handler, and problem-details handler pre-wired. Construct it once and reuse it; it is thread-safe.

DI registration

In an ASP.NET Core or generic-host app, use the DI extension instead of the standalone constructor:

using Paylera.Sdk;


builder.Services.AddPaylera(opts =>
{
    opts.ApiToken   = builder.Configuration["Paylera:ApiToken"];
    opts.ApiVersion = "2026-05-01";
});

Inject IPayleraClient directly:

public sealed class CheckoutService
{
    private readonly IPayleraClient _paylera;


    public CheckoutService(IPayleraClient paylera) => _paylera = paylera;


    public Task<CheckResponse> CheckAsync(Guid subId, string featureCode, CancellationToken ct)
        => _paylera.CheckEntitlementAsync(new CheckRequest
        {
            Subscription_id = subId,
            Feature_code    = featureCode,
            Required_usage  = "1",
        }, cancellationToken: ct);
}

The DI pipeline registers IPayleraClient via IHttpClientFactory, so it picks up your host’s existing logging, metrics, and DNS-rotation behaviour for free.

Add the ASP.NET Core relay

To expose the browser-safe relay for @paylera/react (or any browser-side Paylera SDK) to call:

using Paylera.AspNetCore;


builder.Services.AddPaylera(opts =>
{
    opts.ApiToken          = builder.Configuration["Paylera:ApiToken"];
    opts.IdentifyCustomer  = ctx => new PayleraCustomerIdentity
    {
        CustomerId = ctx.User.FindFirstValue("paylera_customer_id"),
        Email      = ctx.User.FindFirstValue(ClaimTypes.Email),
        Name       = ctx.User.Identity?.Name,
    };
    opts.AutoCreateCustomer = true;
    opts.Csrf.Enabled       = true;
});


app.MapPayleraRelay("/api/paylera").RequireAuthorization();

AddPaylera from Paylera.AspNetCore is a superset of AddPaylera from Paylera.Sdk — it transparently registers both surfaces, so IPayleraClient is still injectable for server-side calls that don’t want the relay shape.

See aspnetcore for the full set of relay routes, CSRF behaviour, customer auto-create, and webhook receiver.

Examples

Two runnable example apps live in examples/dotnet/:

  • examples/dotnet/AspNetCoreMinimalApi/ — minimal-API host with JWT auth, the relay enabled, and a bundled SPA-style HTML page that exercises every relay route.
  • examples/dotnet/BlazorServer/ — Blazor Server app that drives a pricing page off ListPlansAsync and an entitlement gate off CheckEntitlementAsync — no relay needed because the runtime is server-side.

Both reference the workspace SDK packages via <ProjectReference>; the references flip to <PackageReference> at v1 split-time.

Next steps