How integrations work

To integrate with Zettle, you can build a partner-hosted, self-hosted, or SDK app. Regardless of the app type, to make the integration work, the app needs the following:

Authentication and authorisation

Authentication means to identify your app users as valid Zettle merchants. They will need to have a valid Zettle merchant account.

Note: Before their accounts are activated, they will go through a process of confirming their identities. This process may take some time.

Authorisation means your app users will authorise the app to access their Zettle merchant account data.

If you have set up authentication and authorisation for your app already, check the example for taking payments.

OAuth flow

Authentication and authorisation for APIs and SDKs is implemented with OAuth 2.0 standard.

These are different ways to authenticate and authorise:

  • Assertion grant (API key)

    Used by self-hosted apps. An API key is a JSON web token (JWT) assertion. The API key is used to exchange access tokens with your authorisation server.

    For how to set up the OAuth flow, see Set up the authorisation assertion grant flow.

  • Code grant

    Used by partner-hosted apps. A client secret is used to exchange access token and refresh token with your authorisation server for the first time. After that, the refresh token is used to exchange for a new access token with the server.

    For how to set up the OAuth flow, see Set up the authorisation code grant flow.

  • Proof key for code exchange (PKCE)

    Used by SDK apps. Instead of using a fixed client secret, the PKCE creates and includes a code challenge for every authorisation request to exchange access token and refresh tokens with your authorisation server.

    For how to set up the OAuth flow, see user guide Set up the authorisation code grant with PKCE flow.

Note: If you decide to use the default Zettle UI for SDK apps, you don't need to set up the OAuth flow.

Access to Zettle merchant data

Access to Zettle merchant data is defined by OAuth scopes. Each API and SDK require a specific set of OAuth scopes. For example, calling the Purchase API requires OAuth scope READ:PURCHASE that indicates read-only access to purchase data. See more about required OAuth scopes for APIs and SDKs.

When you set up the OAuth flow for authentication and authorisation, you will need to specify the OAuth scopes for your app. After the app is authorised by your app users, it will gain access to Zettle merchant data that is specified in the OAuth flow.

Synchronising updates

You can use webhooks to get notifications triggered by certain events, like purchases or product updates. See Pusher API.

Managing apps

After your app is created in the Dashboard on Zettle Developer Portal, you can change app descriptions like app name in the Dashboard.

Note: Currently, an app cannot be deleted after it's created.

After a merchant is identified as a valid Zettle merchant in an OAuth flow, the app is connected with the merchant's Zettle account. For any connected app, when the merchant logs in to my.zettle.com, they can find the app under Connected apps.

Related information