Missing endpoints: OAuth authorization, merchant profile, and Apple Pay session

[fbognini]

Description

The SDK is missing support for endpoints:

Method	Endpoint	Description
POST	/token	OAuth 2.0 token exchange (obtain/refresh access tokens)
GET	/v0.1/me	Retrieve merchant profile (merchant code, account status)
PUT	/v0.1/checkouts/{checkoutId}/apple-pay-session	Create an Apple Pay session for a checkout

Use cases

• /token: Required for the full OAuth 2.0 authorization code flow to obtain access tokens on behalf of merchants.
• /v0.1/me: Needed to validate API credentials and retrieve the merchant_code required by other API calls (e.g. creating checkouts).
• /v0.1/checkouts/{id}/apple-pay-session: Required to support Apple Pay payments through SumUp checkouts.

[matoous]

Hi!

/token

For OAuth 2.0 flows, please consider relying on one of the libraries for example from: https://oauth.net/code/dotnet/. We have on purpose removed these from the SDK to make sure that integrations rely on battle-tested libraries that provide helpers for implementing OAuth 2.0 securely and can handle token refresh out of the box. You should be able to for example use:

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = "SumUp";
})
.AddCookie()
.AddOAuth("SumUp", options =>
{
    options.ClientId = "YOUR_CLIENT_ID";
    options.ClientSecret = "YOUR_CLIENT_SECRET";

    options.CallbackPath = "/login/callback";

    options.AuthorizationEndpoint = "https://api.sumup.com/authorize";
    options.TokenEndpoint = "https://api.sumup.com/token";

    options.UsePkce = true;
    options.SaveTokens = true;

    options.Scope.Add("user.profile");
});

...

/v0.1/me

We no longer support /v0.1/me as it implies that the token is always bound to a single merchant account. That's no longer the case as we are getting closer to allowing users to own and be members of multiple merchant accounts. You can use the List memberships endpoint right after user's login to retrieve the list of merchants they are member of.

/v0.1/checkouts/{checkoutId}/apple-pay-session

I will raise this one with the online payments team, thanks for reporting.

---

Hope this answers your questions, please let me know if anything else needs clarification.

[fbognini]

Hi @matoous
Thanks for the detailed response!

/token

I appreciate the reasoning behind relying on established OAuth 2.0 libraries, but I'd like to share a concern about the suggested approach.

The proposed solution using AddOAuth("SumUp", ...) is designed to authenticate a user through SumUp, essentially treating SumUp as an identity provider. However, in many real-world scenarios, the application itself is not the entity being authenticated.

Consider a SaaS platform (e.g., a payment orchestrator or a POS system): a merchant connects their SumUp account to enable payments. The platform needs to obtain and manage tokens on behalf of each merchant programmatically - typically through a backend service, not through a browser-based login flow. The checkout page served to end customers should certainly not require OAuth authentication against SumUp.

In this scenario, the application needs to:

1. Exchange an authorization code for an access token (received via redirect after merchant onboarding)
2. Persist and refresh tokens per merchant
3. Use those tokens server-side to create checkouts and process payments

This is a machine-to-machine concern, not a user session concern. ASP.NET's AddOAuth middleware ties token lifecycle to a user's authentication session and cookies, which doesn't map well to this use case.

I obviously don't expect this to change the current direction, but I'd suggest considering this multi-merchant SaaS use case when evaluating whether a lightweight token exchange method belongs in the SDK.

/v0.1/me

That makes sense, thanks! I'll open a separate issue regarding the List memberships endpoint, as I've encountered a serialization bug with enum query parameters there.

That said, the /v0.1/me response included a details_submitted field that was very useful to determine whether the merchant had completed their profile setup. With the new APIs, I'm not sure how to obtain equivalent information. Specifically, I need to know:

1. Has the merchant completed onboarding? (i.e., all required details have been submitted)
2. Can the merchant start accepting payments? (i.e., their account is fully verified and active)

Is there a recommended endpoint or field in the current API to retrieve this status?

[matoous]

@fbognini thanks for elaborating, appreciate the details.

Regarding the use-case for /token that you mentioned. We are working on App Installations (similar to e.g. GitHub), that's in progress and should address scenarios where the 3rd party application (client) needs to maintain access to the merchant account even without user presence. Let me do some more reading on OAuth libraries for C# / .NET. It might make sense to include this in the SDK, my only worry is forcing specific dependencies onto developers. We have tried so far to keep all our SDKs as lean as possible to make them agnostic to library choices on the integration side.

Regarding /v0.1/me, details_submitted reflects Has the merchant completed onboarding?. In that regard, there's indeed no better alternative at the moment. For Can the merchant start accepting payments? we don't currently have an API that would provide this information. We are aware of these gaps as they were requested a few times already, unfortunately, the underlying APIs that handle this on our side are undergoing major rework and are no quite in a state where we would feel comfortable exposing them for integrations.

Let me bring that up with the team that owns this part and get back to you regarding what the plans going forward are.

[matoous]

Hi @fbognini, I have added a small OAuth 2.0 example in: #90. We are currently working on App Installations (similar to GitHub Apps). If that would be of interest to you I can let you know as soon as we have a first version and we can enrol you for testing.

Regarding /v0.1/checkouts/{checkoutId}/apple-pay-session, this is in progress. I am waiting on a review from the payments team. Will include it in the SDK / docs afterwards.

[matoous]

Apple Pay Session endpoint added in v0.0.14.