SumUp 0.0.21

<div align="center">

SumUp .NET SDK

</div>

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.

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