Authorization

Overview

All requests to SumUp API must be made over HTTPS and must be authorized.

SumUp supports two kinds of authorization. One is via API keys allowing the app to authenticate and authorize on behalf of the Merchant and access the SumUp API with full set of permissions. This is the easiest approach and accommodates most use cases.

The other approach is via OAuth 2.0, which allows the app to request access on behalf of third parties. This is useful for building advanced integrations to be used by multiple merchants.

Integration via API Keys

SumUp uses API keys to authenticate and authorize the API requests. API Keys are short static tokens passed in the Authorization header.

curl https://api.sumup.com/v0.1/me -H "Authorization: Bearer $SUMUP_API_KEY"

The intended purpose of API keys is to authorize on behalf of a single merchant to whom the API key belongs.

Caution

Do not share your secret API keys in publicly accessible places such as GitHub repositories, client-side code, etc. Your API keys carry full permissions to the entire SumUp API, so make sure to keep them secure. Should you decide to integrate third-parties with the API key, you are responsible for ensuring the security of such integration.

Create API Key

1. Log in to https://me.sumup.com.

2. Expand your profile and open Settings.

3. Go to For Developers > Toolkit.

4. Select API Keys.

   If you didn't create a key before, this page only shows the SumUp Public Key. If you did, your existing API Keys can be found here.

   Do not use the public key in your integration.

5. Select Create and give the key a meaningful name. Your key is now created and granted permissions to access SumUp APIs.

6. When prompted, copy the key (you can also download it). SumUp does not store the key for security reasons. Integrators are responsible for handling the key securely in accordance with best industry practices.

   • Ideally, do not share the key with third parties. If you do, ensure they handle it securely.
   • Do not add the key to source-controlled repository or client-side code.
   • Monitor key usage.
   • Rotate the key on regular basis.

Affiliate Keys

Affiliate Keys are not part of authorization mechanisms as such, but they are required for card-present integrations. For more information, see Affiliate Keys.

Integration via OAuth 2.0

OAuth 2.0 is the recommended approach for building advanced integrations, where multiple different merchants or their employees want to use SumUp. SumUp conforms to the OAuth 2.0 protocol, providing an authorization server and exposing the following endpoints as defined by the industry:

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

OAuth 2.0 is an industry-standard authorization protocol that allows for control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows the app to request API access on behalf of other users after they grant you the permission.

SumUp supports two standard OAuth 2.0 authorization flows:

• The authorization code flow to request permissions from other users.
• The client credentials flow to authenticate as yourself.

Caution

For security reasons, SumUp manually verifies the following scope grants:

• payments - required to process payments.
• payment_instruments - required to store customer data and tokenize cards.

Contact us to request those scopes to be granted to your app.

SumUp does not recommend direct OAuth 2.0 integration and does not expose detailed authorization endpoint documentation for that reason. Please use a library that handles OAuth 2.0 protocol. We highly recommend that you use one of the existing reputable implementations.

Authorization Code Flow

This flow works as specified by RFC 6749 Authorization Code Grant, enabling applications to request permission from a SumUp merchant to act on their behalf. The requested scopes define what your application is allowed to do.

1. To initiate the flow, your application redirects a user to the SumUp authorization server with the https://api.sumup.com/authorize endpoint.

2. The request triggers an authorization prompt describing which application is requesting authorization from the user.

   Caution

   If the user denies and clicks the Cancel button on the request, the authorization server will not generate an authorization code and will instead return an error parameter with an access_denied value instead.

3. Once the user accepts your authorization request, the authorization server redirects the user back to your application by using the registered URI you specified in the redirect_uri at the initial GET request. The response will return the code parameter, which is mandatory for retrieving an access token.

4. To retrieve the access token, the app makes a request to the https://api.sumup.com/token endpoint with a Content-Type: application/x-www-form-urlencoded header.

   The app receives the standard response, containing access_token, refresh_token, token_type, and expires_in.

   {
     "access_token": "565e2d19cef68203170ddadb952141326d14e03f4ccbd46daa079c26c910a864",
     "refresh_token": "d180031bfe9bac36c336e5746637810272546865e9c9586012f462a56f3fe9af",
     "token_type": "Bearer",
     "expires_in": 3600
   }

The access_token can now be used in the Authorization header with Bearer scheme to authorize calls to SumUp services. The app can use the refresh_token to get a new access_token when it expires without the user’s interaction (see Refresh token flow below).

Refresh Token Flow

To refresh the access token, send a request to the https://api.sumup.com/token endpoint with the refresh token you've received when completing the Authorization code flow, as the OAuth 2.0 protocol dictates. Access tokens can expire for many reasons, such as if the user changes their password or revokes the app access.

In the response, the app receives a new access_token that is valid for expires_in seconds and a new refresh_token. Make sure to store the new refresh_token for successive refreshes.

Caution

By default, refresh tokens are valid for a period of 6 months. After your refresh_token expires, the app must follow the Authorization code flow again to obtain a valid access token and a new refresh token. A new refresh token will also be issued when a valid refresh token is used within 30 days prior to its expiration. The new refresh token will be valid for another 6 months. The old refresh token remains valid until its expiration date, giving you a grace period to propagate the new token across your integration.

Note that refresh tokens can be invalidated due to factors other than expiration, such as password change, scope changes, etc. Failed attempt to refresh a token should be handled gracefully by triggering a new login and obtaining fresh set of access and refresh token.

Authorization Scopes

Authorization scopes define what an application is allowed to do on a merchant's behalf. A required set of scopes may be passed as a space-separated list in the authorization request. When scopes are omitted, the default ones are granted. If additional scopes are required, a new access_token has to be collected via the Authorization code flow.

Scope name	Default	Access Level	Description
transactions.history	yes	merchant	Allows to view the transactions and transaction history for a specific merchant user's account.
user.app-settings	yes	merchant	Allows to view and modify the SumUp mobile application settings for a specific merchant user's account.
user.profile_readonly	yes	merchant	Allows to view the profile details for a specific merchant user's account.
user.profile	no	merchant	Allows to modify the profile details of a specific merchant user's account.
user.subaccounts	no	merchant	Allows to view and modify the profile details of a sub-account created for a specific merchant user's account. Sub-accounts are user accounts for employees of a merchant and can be granted different permissions by the holder of the main merchant user's account.
user.payout-settings	no	merchant	Allows to view and modify the payout settings for a specific merchant user's account.
products	no	merchant	Allows to view and modify the product store for a specific merchant user's account. This includes the products, shelves, prices, and VAT rates available in the merchant's product store.
restricted payments	no	feature	Allows to make payments by creating and processing payment checkouts. Requires verification by SumUp before it can be granted.
restricted payment_instruments	no	feature	Allows to save customers and tokenize their payment cards for a specific merchant user's account. Requires verification by SumUp before it can be granted.

Restricted scopes must be enabled by SumUp for your application. To do that, contact us.

Client Credentials Flow

This flow works as specified by RFC 6749 Client Credentials Grant

In the Client Credentials flow, your application requests an access token without requesting authorization from a merchant user. As a result, when you use this flow, your application is not authorized to access any data that is associated with a merchant user's account, such as transactions or saved customers and tokenized payment cards. In other words, you can only process payments for merchant accounts with an access token obtained via this grant flow.

To request an access token, the app needs to make a request to the https://api.sumup.com/token endpoint as defined in the OAuth 2.0 Client Credentials protocol. This flow does not grant a Refresh Token.

What's Next?

Check the following resources to build your integration:

• OAuth 2.0 App Registration Guide
• iOS SDK Guide
• Android SDK Guide
• PHP SDK Guide
• React Native SDK
• Cloud API for the Solo Card Reader