SumUp .NET SDK

IMPORTANT: This SDK is under development. We might still introduce minor breaking changes before reaching v1.

The .NET SDK for the SumUp API.

Getting Started

dotnet add package SumUp --prerelease

See examples/Basic, examples/CardReaderCheckout, examples/OAuth2, and examples/Events for runnable projects.

Supported .NET Versions

We target every currently supported .NET release line. Continuous Integration runs restore/build/test on .NET 8.x, 9.x, and 10.x to ensure the SDK works across all supported versions.

Authenticate by exporting an access token (or by assigning SumUpClientOptions.AccessToken directly):

export SUMUP_ACCESS_TOKEN="my-token"

Then call the API:

using System;
using SumUp;

using var client = new SumUpClient();
var response = await client.Checkouts.ListAsync();

foreach (var checkout in response.Data ?? Array.Empty<CheckoutSuccess>())
{
    Console.WriteLine($"Checkout {checkout.Id}: {checkout.Amount} {checkout.Currency}");
}

Usage

Creating a Checkout

using System;
using SumUp;

using var client = new SumUpClient();

var merchantCode = "your-merchant-code";

var checkoutReference = $"checkout-{Guid.NewGuid():N}";

var checkoutResponse = await client.Checkouts.CreateAsync(new CheckoutCreateRequest
{
    Amount = 10.00f,
    Currency = Currency.Eur,
    CheckoutReference = checkoutReference,
    MerchantCode = merchantCode,
    Description = "Test payment",
    RedirectUrl = "https://example.com/success",
    ReturnUrl = "https://example.com/webhook",
});

Console.WriteLine($"Checkout ID: {checkoutResponse.Data?.Id}");
Console.WriteLine($"Checkout Reference: {checkoutResponse.Data?.CheckoutReference}");

Creating a Reader Checkout

using System;
using SumUp;

using var client = new SumUpClient();

var readerCheckout = await client.Readers.CreateCheckoutAsync(
    merchantCode: "your-merchant-code",
    readerId: "your-reader-id",
    body: new CreateReaderCheckoutRequest
    {
        Description = "Coffee purchase",
        ReturnUrl = "https://example.com/webhook",
        TotalAmount = new CreateReaderCheckoutRequestTotalAmount
        {
            Currency = "EUR",
            MinorUnit = 2,
            Value = 1000, // €10.00
        },
    });

Console.WriteLine($"Reader checkout created: {readerCheckout.Data?.Data?.ClientTransactionId}");

Handling errors

Catch ApiException to inspect an unsuccessful API response. Problem responses provide typed details:

using SumUp.Http;

try
{
    await client.Checkouts.GetAsync("your-checkout-id");
}
catch (ApiException error)
{
    if (error.Problem is { } problem)
        Console.WriteLine($"{problem.Type}: {problem.Detail}");
}

StatusCode, ResponseBody, and Headers provide the HTTP status, original response text, and headers.

Handling events

Create a handler with your endpoint's signing secret and a fallback for unregistered event types:

using var client = new SumUpClient();
var events = client.CreateEventsHandler(secret, (notification, _) =>
{
    Console.WriteLine($"Unhandled event {notification.Id}: {notification.Type}");
    return Task.CompletedTask;
});

events.OnMemberUpdated(async (notification, cancellationToken) =>
{
    var member = await notification.FetchObjectAsync(cancellationToken: cancellationToken);
    Console.WriteLine($"Member updated: {member?.Id}");
});

await events.HandleAsync(rawBody, signatureHeader, cancellationToken);

Pass the original request bytes and the X-SumUp-Webhook-Signature header. The handler verifies the signature and its five-minute delivery timestamp window before invoking a callback. Acknowledge delivery after HandleAsync succeeds, and use event IDs to deduplicate processing. FetchObjectAsync retrieves the resource's current state; deleted resources may no longer be available.

Notifications inherit the generated EventValue model. Use notification.Type with constants such as EventType.MembersUpdated, and notification.ObjectValue for the generated resource reference. Event and resource type names preserve unknown values in their Value property.

For manual dispatch, use client.ParseEventNotification(rawBody, signatureHeader, secret) and match the returned event type. See the ASP.NET Core example for a complete HTTP endpoint.

Examples

• examples/Basic – lists recent checkouts to sanity check your API token.
• examples/CardReaderCheckout – lists the merchant’s paired readers and creates a €10 checkout on the first available device.
• examples/OAuth2 – starts a local OAuth2 Authorization Code flow with PKCE, exchanges the callback code for an access token, and fetches merchant information using the returned merchant_code.
• examples/Events – runs a minimal ASP.NET Core endpoint with signature verification, typed event callbacks, and resource fetching.

To run the card reader example:

export SUMUP_ACCESS_TOKEN="your_api_key"
export SUMUP_MERCHANT_CODE="your_merchant_code"
# Optional: set a specific reader, otherwise the first paired reader is chosen
# export SUMUP_READER_ID="your_reader_id"
dotnet run --project examples/CardReaderCheckout

To run the OAuth2 example:

export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"
export REDIRECT_URI="http://localhost:8080/callback"
dotnet run --project examples/OAuth2

To run the events example:

export SUMUP_ACCESS_TOKEN="your_api_key"
export SUMUP_EVENT_SECRET="whsec_..."
dotnet run --project examples/Events