OAuth API overview

The OAuth API handles merchants authentication and authorisation of external integrators. It also issues access tokens used by authorised clients to call Zettle APIs. The OAuth API implements the OAuth 2.0 protocol.

Note: When building your integration, authentication and authorisation must be set up before calling Zettle APIs or SDKs.

System overview showing API and SDK data exchange through the authorisation service provided by the OAuth API.

Get started

Register on the Zettle Developer Portal to create credentials for the app you are building, and learn more about different types of integrations. See Get started for more information.

Explore the sections listed in the following to get an understanding of how to work with the OAuth API.

Understand how authentication and authorisation work

Using the OAuth API, your integration will have authorised access to API calls to your users' Zettle merchant data.

Authentication: Verifies that users are valid Zettle merchants.
Authorisation: Provides the requested access to Zettle merchant data for an integration.

The OAuth API supports the following authentication and authorisation flows:

Code grant with PKCE

Instead of using a fixed client secret, the PKCE creates and includes a code challenge for every authorisation request. This is exchanged for access tokens and refresh tokens with the Zettle authorisation server.

Note: It is strongly recommended that you use this approach, unless you have a solid reason not to. This is the default approach for your app code as per the OAuth 2.1 standard. This is a mandatory flow to be used for:

For Single-page apps(SPA), where they cannot store the client secret since all the source code is available publicly.
Native/mobile apps, where the client secret can be revealed by decompiling the app.

PKCE helps to mitigate security risks associated with OAuth 2.0. Specifically, PKCE helps to prevent authorisation code interception attacks. This approach ensures that the client that originally initiated the authorisation request is the same client that exchanges the authorisation code for an access token, and not a malicious actor that intercepted the authorisation code.

It is recommended that you use this flow even if you have a confidential client like a backend service or any other server side artifact that you build for your integrations.

Code grant

A client secret is exchanged for access tokens and refresh tokens with the Zettle authorisation server. The refresh token is exchanged for a new access token with the server.

Note: If you are using this flow, it is recommended that you change to the Code grant flow with PKCE described above to ensure that you are protected against several attacks.

Assertion grant

Using an API key in the format of a JSON web token (JWT). The API key is exchanged for access tokens with Zettle authorisation server.

Understanding the OAuth API

Explore the OAuth API reference to learn more:

Create app credentials

Before building an integrating with Zettle, you need app credentials to set up the authentication and authorisation for the integration.

For an app hosted by merchants individually, see create credentials for a self-hosted app.
For an app hosted by you as an integrator, create credentials for a partner-hosted app.
For an app used for taking payments, see create credentials for an SDK app.

Set up authentication and authorisation

When you have the app credentials, you can set up authentication and authorisation for the app.

Authorisation code grant with PKCE
This flow should be used by all apps by default since it provides protection against several attacks.
Authorisation code grant
This flow is most often used by a partner-hosted app that is hosted by you as an integrator.
Authorisation assertion grant
This flow is most often used by a self-hosted app that is hosted by merchants individually.

Manage apps and users

With the OAuth API, you can also work with the following:

Identify users
Disconnect app from user
Include access token and tracking identifiers in API requests
Note: Currently, there is no tracking available for integrations with Zettle. However, if you plan to implement tracking on your own, you can include a tracking identifier in API requests.