OAuth 2.0

Integration via OAuth 2.0

OAuth 2.0 lets your application request permission to act on behalf of other SumUp merchants or their employees. It follows the industry-standard OAuth 2.0 protocol and is the right choice for multi-merchant integrations or when you cannot rely on a single merchant-owned API key.

SumUp exposes two OAuth 2.0 endpoints:

https://api.sumup.com/authorize
https://api.sumup.com/token

SumUp supports two OAuth 2.0 flows:

The authorization code flow when an end user grants your application access.
The client credentials flow when your application authenticates as itself.

Authorization flows

Choose the flow that matches how your application obtains access while keeping scope verification requirements in mind.

Authorization Code Flow

This flow implements the RFC 6749 Authorization Code Grant. It lets a SumUp merchant review the permissions you request and authorize your application accordingly. The requested scopes determine the allowed actions.

Redirect the user to https://api.sumup.com/authorize with the required parameters.
SumUp shows an authorization prompt describing your application and the scopes requested.

If the user denies the request, SumUp sends an error response to your redirect URI and does not issue an authorization code.
After the user approves, SumUp redirects to your Redirect URI with an authorization code and the original state.
Your application exchanges the authorization code for tokens by calling the token endpoint described below.
Use the access_token in the Authorization: Bearer header when calling SumUp APIs.

Exchange the authorization code

Send the following request to https://api.sumup.com/token:

1
curl https://api.sumup.com/token \
2
  -X POST \
3
  -H "Content-Type: application/x-www-form-urlencoded" \
4
  -d "grant_type=authorization_code&code={AUTHORIZATION_CODE}&redirect_uri={REDIRECT_URI}" \
5
  -u "{CLIENT_ID}:{CLIENT_SECRET}"

The response contains an access token, refresh token, and metadata such as token lifetime and granted scopes.

1
{
2
  "access_token": "{ACCESS_TOKEN}",
3
  "token_type": "Bearer",
4
  "expires_in": 3599,
5
  "refresh_token": "{REFRESH_TOKEN}",
6
  "scope": "payments customers payment_instruments"
7
}

Refresh the access token

Access tokens expire, for example when a user changes their password or revokes access. Use the refresh token to request a new access token from https://api.sumup.com/token as defined by OAuth 2.0.

Refresh tokens are valid for six months. If you use a refresh token within 30 days of its expiration, SumUp issues a new token that remains valid for another six months. The previous token keeps working until it expires, giving you time to rotate it across your systems.

Authorization Scopes

Scopes restrict what your application may do on behalf of the merchant. Request only the scopes you need. When you omit scopes, SumUp grants the defaults listed below. To obtain additional scopes later, repeat the authorization code flow.

Scope name	Default	Access Level	Description
transactions.history	yes	merchant	View transactions and transaction history for the merchant user.
user.app-settings	yes	merchant	View and modify SumUp mobile app settings for the merchant user.
user.profile_readonly	yes	merchant	View profile details of the merchant user.
user.profile	no	merchant	Modify profile details of the merchant user.
user.subaccounts	no	merchant	View and modify sub-account profiles for the merchant user.
user.payout-settings	no	merchant	View and modify payout settings for the merchant user.
products	no	merchant	View and modify products, shelves, prices, and VAT rates in the merchant’s product store.
`restricted` payments	no	feature	Create and process payment checkouts. Requires manual verification by SumUp.
`restricted` payment_instruments	no	feature	Save customers and tokenize their payment cards. Requires manual verification by SumUp.

Restricted scopes must be enabled by SumUp for your application. Contact us to request them.

Client Credentials Flow

The client credentials flow follows RFC 6749 Client Credentials Grant. It issues an access token without involving a merchant user. Because no user is associated with the token, the flow does not allow access to merchant-specific data such as transactions or stored customers. You can still process payments for merchants linked to your application.

Request an access token from https://api.sumup.com/token using the client credentials grant parameters. This flow does not return a refresh token.

Register an OAuth application

To integrate an external application with SumUp, register an OAuth application and generate client credentials. These credentials let you complete the OAuth flows in this guide and obtain access tokens for protected SumUp resources.

Steps

This section walks through the registration process:

Log in to your account
Create an OAuth application
Generate the client credentials
Access the client credentials

Before you begin

Have the following ready before you register the application:

A SumUp merchant account with completed account details. Reach out through the contact form if you need a test account.
Your application name.
One or more redirect URIs. SumUp redirects users to these URIs after authentication and sends the authorization codes you exchange for tokens in the authorization code flow.

1. Log in to your account

2. Create an OAuth application

Navigate to the OAuth Apps page to create or manage OAuth applications.

Select Create application at the bottom right to define your application.

Describe your application, provide its homepage, and select Register application to continue.

You can edit the registered application by selecting it. The edit page lets you update details and add optional information such as a logo, terms and conditions, and privacy policy URLs.

You can also select the scopes your application requires. Each scope includes a short description of the access it grants.

3. Generate the client credentials

On the OAuth Apps page, open your application and choose Create client secret.

Provide the following details:

Name	Required	Description
Client name	Yes	A descriptive name for your client application.
Application type	Yes	The type of your client application. Options: Web, Android, iOS, Other.
Authorized redirect URL	Yes	Redirect URL to register for your client application. Specify multiple URLs by separating them with commas.
Authorized JavaScript Origin	No	Origin URI for browser-based web applications. SumUp enables CORS for registered origins.

Select Save to generate the credentials. The Client secrets section lists each credential with its name, application type, and client ID.

4. Access the client credentials

After creation, credentials appear in the Client credentials section of your OAuth application (see screenshot).

Use the download button to receive a JSON file with the full credential details, for example:

1
{
2
  "id": "CCCFAXYD",
3
  "name": "SA web client",
4
  "client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
5
  "client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
6
  "application_type": "web",
7
  "redirect_uris": ["https://sample-app.example.com/callback"]
8
}

Result

You have registered at least one OAuth application and have downloaded its client credentials. Proceed with the OAuth 2.0 flows to obtain access tokens. Use them to accept payments with a customer-entered card or with stored payment data in recurring scenarios.