# OAuth 2.0

import { Aside, Steps } from '@astrojs/starlight/components';
import Image from '@components/content/Image.astro';

OAuth 2.0 lets your application request permission to act on behalf of other SumUp users and access their merchant accounts. It follows the industry-standard OAuth 2.0 protocol and is the right choice for integrations where your application needs delegated access to a merchant’s data or needs to perform actions on their behalf.

If you are building a multi-tenant integration, marketplace, SaaS platform, or any app that connects to multiple merchants, you should use OAuth 2.0.

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](#authorization-code-flow) when an end user grants your application access.
- The [client credentials flow](#client-credentials-flow) when your application authenticates as itself.

<Aside>

SumUp strongly recommends that you rely on [reputable existing libraries](https://oauth.net/code/) when implementing OAuth 2.0 authorization.

</Aside>

## 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](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1). It lets a SumUp user review the permissions you request and authorize your application accordingly. The [requested scopes](#authorization-scopes) determine the allowed actions.

Use this flow when your application has a backend that can keep the client secret confidential. The flow separates user authorization from token issuance, so your application never sends the user's credentials to your own systems.

<Steps>

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

   <Aside type="caution">
   If the user denies the request, SumUp sends an error response to your redirect URI and does not issue an authorization code.
   </Aside>

3. After the user approves, SumUp redirects to your **Redirect URI** with an authorization code and the original `state`.
4. Your application verifies the returned `state` and exchanges the authorization code for tokens by calling the token endpoint described below.
5. Use the `access_token` in the `Authorization: Bearer` header when calling SumUp APIs.

</Steps>

When building this flow:

- Register the exact redirect URIs your application uses and send the same `redirect_uri` value in the authorization request and token exchange.
- Always send a `state` value and verify that the callback returns the same value before exchanging the code.
- Treat the authorization code as short-lived and single-use. Exchange it immediately from your backend and never reuse it.

Example authorization request:

```http
GET /authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope=payments%20customers%20payment_instruments&state={STATE} HTTP/1.1
Host: api.sumup.com
```

### Exchange the Authorization Code

After the user is redirected back to your application, read the `code` and `state` query parameters from the callback URL. If the `state` matches the value your application originally sent, exchange the authorization code at `https://api.sumup.com/token`:

```http
POST /token HTTP/1.1
Host: api.sumup.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={AUTHORIZATION_CODE}
&redirect_uri={REDIRECT_URI}
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
```

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

```json
{
  "access_token": "{ACCESS_TOKEN}",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "{REFRESH_TOKEN}",
  "scope": "payments customers payment_instruments"
}
```

### Refresh the Access Token

Access tokens are short-lived. Use the `expires_in` value to track when the current access token is expected to expire. You can refresh shortly before expiry, or you can wait until an API request fails because the access token is no longer valid. In both cases, request a new token from `https://api.sumup.com/token` using the OAuth 2.0 refresh token grant:

```http
POST /token HTTP/1.1
Host: api.sumup.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={REFRESH_TOKEN}
&client_id={CLIENT_ID}
&client_secret={CLIENT_SECRET}
```

Your integration should still handle cases where an API request fails because the access token became invalid earlier than expected, for example after revocation or other account changes.

The token endpoint responds with a new access token and may also return a new refresh token:

```json
{
  "access_token": "{NEW_ACCESS_TOKEN}",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "{NEW_REFRESH_TOKEN}"
}
```

Handle refresh tokens according to standard OAuth 2.0 practices:

- Store refresh tokens securely because they are long-lived credentials.
- After a successful refresh, persist and use the latest `refresh_token` returned by the token endpoint. If the response does not include a new `refresh_token`, continue using the one you already have.
- If refresh fails with an OAuth error such as `invalid_grant`, treat the refresh token as no longer usable and restart the authorization code flow.
- When refresh fails, do not keep retrying with the same invalid refresh token. Ask the user to authorize again.

## 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. |
| `payments`*             | no      | feature      | Create and process payment checkouts. Requires manual verification by SumUp.              |
| `payment_instruments`*  | no      | feature      | Save customers and tokenize their payment cards. Requires manual verification by SumUp.   |

<Aside type="caution">

*SumUp manually verifies requests for the following scopes:

- `payments` – required to create and process payments.
- `payment_instruments` – required to store customer data and tokenize cards.

[Contact us](/contact) to request those scopes for your application.

</Aside>

## Client Credentials Flow

The client credentials flow follows [RFC 6749 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4). 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.

### Before You Begin

1. Prepare a SumUp merchant account with completed [account details](https://me.sumup.com/account).
2. Choose your application name.
3. Prepare 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](#authorization-code-flow).

### Steps

<Steps>

1. Log in to [your SumUp account](https://me.sumup.com/login). Once logged in, **Account** appears in place of the **Log in** button at the top right.

2. Navigate to the [OAuth apps page](https://me.sumup.com/settings/oauth2-applications) to create or manage OAuth applications.

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

   <Image alt="Create OAuth App screen" src="/img/guides/create-oauth-apps.png" width="80%" />

   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. On the [OAuth apps page](https://me.sumup.com/settings/oauth2-applications), open your application and choose **Create client secret**.

   <Image alt="Create new OAuth App credentials form" src="/img/guides/client-credentials-form.png" width="80%" />

   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.

   <Aside type="note">

   You can register as many client credentials as you need. Repeat this step to create additional ones.

   </Aside>

4. After creation, credentials appear in the **Client credentials** section of your OAuth application.

   <Image alt="OAuth client credentials section" src="/img/guides/client-credentials-list.png" width="80%" />

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

   ```json
   {
     "id": "CCCFAXYD",
     "name": "SA web client",
     "client_id": "fOcmczrYtYMJ7Li5GjMLLcUeC9dN",
     "client_secret": "717bd571b54297494cd7a79b491e8f2c1da6189c4cc2d3481380e8366eef539c",
     "application_type": "web",
     "redirect_uris": ["https://sample-app.example.com/callback"]
   }
   ```

   <Aside type="note">

   Store client secrets securely and never expose them publicly. If you suspect a secret was compromised, [contact us](/contact) immediately.

   </Aside>

</Steps>

### Result

You have registered at least one OAuth application and have downloaded its client credentials. Proceed with the [OAuth 2.0 flows](#authorization-flows) to obtain access tokens. Use them to accept payments with a [customer-entered card](/online-payments/guides/single-payment/) or with stored payment data in recurring scenarios.

## What's Next?

- [Review your OAuth application scopes](#authorization-scopes)
- [iOS SDK Guide](/terminal-payments/sdks/ios-sdk/)
- [Android SDK Guide](https://github.com/sumup/sumup-android-sdk)
- [PHP SDK Guide](/online-payments/sdks/php/)
- [React Native SDK](/online-payments/sdks/react-native/)
- [Cloud API for the Solo Card Reader](/terminal-payments/cloud-api/)