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.
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:
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.
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.
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.
Understanding the OAuth API
Explore the OAuth API reference to learn more:
- Authorisation assertion grant
- Authorisation code grant
- Authorisation code grant with PKCE
- Get user information
- Disconnect app from user
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.
This flow is most often used by a self-hosted app that is hosted by merchants individually.
This flow is most often used by a partner-hosted app that is hosted by you as an integrator.
This flow is most often used by an SDK payment app.
Manage apps and users
With the OAuth API, you can also work with the following:
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.