OAuth API reference

The OAuth API provides the authorisation service for integrations with Zettle to handle authentication and authorisation of Zettle merchants to get access to their Zettle merchant account data.

It implements the OAuth 2.0 protocol.

https://oauth.zettle.com

Not applicable

Using authorisation assertion grant, authentication and authorisation is done with a JSON web token (JWT) assertion to request an access token from the authorisation server.

Ask your app users to create an API key (assertion) and share it with you for the following purposes:

• They authenticate as valid Zettle merchants by logging into my.zettle.com with their Zettle merchant accounts.
• They authorise requested access to their Zettle merchant account data for the app by creating an API key.

To retrieve the first access token, use the API key (assertion) and client ID from your app users.

An access token expires in 7200 seconds (2 hours). After it's expired, use the same API key and client ID to retrieve a new access token.

Note: The API key may be revoked by your app users at my.zettle.com. When the request fails, check whether the API key is still valid.

Copy
1
POST /token

Copy
1
{
2
     grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
3
     client_id={client_ID}&
4
     assertion={API_key}
5
   }

See example Retrieve an access token (assertion grant).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
grant_type	string	object	required	Always set to urn:ietf:params:oauth:grant-type:jwt-bearer to indicate an API key (assertion) is used to exchange for an access token. A JSON web token (JWT) assertion is used as an API key.
client_id	string	object	required	An app credential that you get after creating credentials for a self-hosted app at my.zettle.com.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when a parameter in the request has an invalid value. The API key may be revoked by your app users at my.zettle.com.

Click to hide response attributes.

Name	Type	Description
access_token	string	The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_in	string	Remaining lifetime of an access token in seconds.

Using authorisation code grant, authentication and authorisation is done with a temporary authorisation code to exchange for an access token from the authorisation server.

In a browser, show your app users a login page where they authenticate themselves as valid Zettle merchants by logging into their Zettle merchant accounts. Then they will be asked to authorise your app access to their Zettle merchant data. They will see the app requested access on the login page.

Copy
1
GET /authorize?response_type=code&
2
    scope={oauth_scope}&
3
    client_id={client_ID}&
4
    redirect_uri={redirect_uri}&
5
    state={state_value}

After your users authenticate themselves as valid Zettle merchants by logging to their Zettle merchant accounts, the users will be shown with requested access and an Approve button.

After they press the button, the users will be redirected to the app with an authorisation code.

https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678

See example Ask app users to authenticate and authorise (code grant).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
response_type	string	query	required	Always set to code to indicate an authorisation code is returned as the response.
scope	string	query	required	Space-separated list of oauth scopes for requesting permissions to your users' Zettle merchant account data. For example, the list of scope READ:PRODUCT%20WRITE:PRODUCT means that your app requests to have a read and write access to your app users' Zettle product libraries.
client_id	string	query	required	An app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal.
redirect_uri	string	query	required	A URL that starts with https and includes a redirect URI to direct your app users back to your app, after they authorise it to access their Zettle merchant data. For example, https://awesomeapp.com.
state	string	query	required	A transparent session key to be included in the redirect. For example, abc123678-222. Make sure to apply URL encoding when providing complex data structures.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when the operation contains invalid parameters.
405 Method Not Allowed	Returned when the operation is not allowed.

After your app gets authorised access to user' Zettle merchant account data, an authorisation code is returned. Use that code and your app credentials to retrieve the first access and refresh tokens.

Copy
1
POST /token

Copy
1
{
2
     grant_type=authorization_code&
3
     redirect_uri={redirect_uri}&
4
     code={authorization_code}&
5
     client_secret={client_secret}&
6
     client_id={client_ID}
7
   }

See example Retrieve the first access and refresh tokens (code grant).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
grant_type	string	object	required	Always set to authorization_code to indicate an authorisation code is used to exchange for an access token.
redirect_uri	string	object	required	A URL that includes a redirect URI to direct your app users back to your app, after they authorise it to access their Zettle merchant data. For example, https://awesomeapp.com.
code	string	object	required	An authorisation code that is returned, after your user authenticates themselves as a valid Zettle merchants and then authorises your app access to their Zettle merchant data. For example, ccf62ef9-99b2-4e9d-dba3-9c3f3c532992.
client_secret	string	object	required	An app credential that you get after creating credentials for a partner-hosted on Zettle Developer Portal.
client_id	string	object	required	An app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when a parameter in the request has an invalid value.

Click to hide response attributes.

Name	Type	Description
access_token	string	The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_in	string	Remaining lifetime of an access token in seconds.
refresh_token	string	A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days.

An access token has a lifetime of 7200 seconds (2 hours). After an access token expires, generate a new access token from the refresh token.

Copy
1
POST /token

Copy
1
{
2
     grant_type=refresh_token&
3
     refresh_token={Previously returned refresh token}&
4
     client_secret={client_secret}&
5
     client_id={client_ID}
6
   }

See example Generate a new access token from the refresh token (code grant).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
grant_type	string	object	required	Always set to refresh_token to indicate a refresh token is used to exchange for an access token.
refresh_token	string	object	required	The refresh token that is retrieved previously.
client_secret	string	object	required	An app credential that you get after creating credentials for a partner-hosted on Zettle Developer Portal.
client_id	string	object	required	An app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when a parameter in the request has an invalid value.

Click to hide response attributes.

Name	Type	Description
access_token	string	The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_in	string	Remaining lifetime of an access token in seconds.
refresh_token	string	A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days. A refresh token is generated everytime a new access token is generated with the last generated refresh token. Use the new refresh token to exchange for the next access token.

Using authorisation code grant with Proof key for code exchange (PKCE), authentication and authorisation is done with PKCE to exchange for an access token from the authorisation server.

In a browser, show your app users a login page where they authenticate themselves as valid Zettle merchants by logging into their Zettle merchant accounts. Then they will be asked to authorise your app access to their Zettle merchant data. They will see the app requested access on the login page.

Copy
1
GET /authorize?response_type=code&
2
    scope={oauth_scope}&
3
    client_id={client_ID}&
4
    redirect_uri={redirect_uri}&
5
    state={state_value}&
6
    code_challenge={code_challenge}&
7
    code_challenge_method={code_challenge_method}

After your users authenticate themselves as valid Zettle merchants by logging to their Zettle merchant accounts, the users will be shown with requested access and an Approve button.

After they press the button, the users will be redirected to the app with an authorisation code.

https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678

See example Ask app users to authenticate and authorise (PKCE).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
response_type	string	query	required	Always set to code to indicate an authorisation code is returned as the response.
scope	string	query	required	Space-separated list of oauth scopes for requesting permissions to your users' Zettle merchant account data. For example, the list of scope READ:PRODUCT%20WRITE:PRODUCT means that your app requests to have a read and write access to your app users' Zettle product libraries.
client_id	string	query	required	An app credential that you get after creating credentials for an SDK app on Zettle Developer Portal.
redirect_uri	string	query	required	A URL that includes a redirect URI to direct your app users back to your app, after they authorise it to access their Zettle merchant data. For example, awesomeapp://zettlelogin.
state	string	query	required	A transparent session key to be included in the redirect. For example, abc123678-222. Make sure to apply URL encoding when providing complex data structures.
code_challenge	string	query	required	A code verifier that is encoded with encoding method Base64-URL-encoding or SHA256. A code verifier is a random string between 43 and 128 characters long. The random string is cryptographically created using the characters A-Z, a-z, 0-9, and the punctuation characters -._~ (hyphen, period, underscore, and tilde).
code_challenge_method	string	query	required	The encoding method that is used to encode a code verifier to create a code challenge. It can be either Base64-URL-encoding and SHA256.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when the operation contains invalid parameters.
405 Method Not Allowed	Returned when the operation is not allowed.

After your app gets authorised access to user' Zettle merchant account data, an authorisation code is returned. Use that code and your app credentials to retrieve the first access and refresh tokens.

Copy
1
POST /token

Copy
1
{
2
     grant_type=authorization_code&
3
     code={authorization_code}&
4
     code_verifier={code_verifier}&
5
     client_id={client_ID}
6
   }

See example Retrieve the first access and refresh tokens (PKCE).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
grant_type	string	object	required	Always set to authorization_code to indicate an authorisation code is used to exchange for an access token.
code	string	object	required	An authorisation code that is returned, after your user authenticates themselves as a valid Zettle merchants and then authorises your app access to their Zettle merchant data. For example, ccf62ef9-99b2-4e9d-dba3-9c3f3c532992.
client_verifier	string	object	required	The random string that is encoded to create a code challenge. It's between 43 and 128 characters long.
client_id	string	object	required	An app credential that you get after creating credentials for an SDK app on Zettle Developer Portal.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when a parameter in the request has an invalid value.

Click to hide response attributes.

Name	Type	Description
access_token	string	The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_in	string	Remaining lifetime of an access token in seconds.
refresh_token	string	A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days.

An access token has a lifetime of 7200 seconds (2 hours). After an access token expires, generate a new access token from the refresh token.

Copy
1
POST /token

Copy
1
{
2
     grant_type=refresh_token&
3
     refresh_token={Previously returned refresh token}&
4
     client_id={client_ID}
5
   }

See example Generate a new access token from the refresh token (PKCE).

Parameters

Click to hide request parameters.

Name	Type	In	Required/Optional	Description
grant_type	string	object	required	Always set to refresh_token to indicate a refresh token is used to exchange for an access token.
refresh_token	string	object	required	The refresh token that is retrieved previously.
client_id	string	object	required	An app credential that you get after creating credentials for an SDK app on Zettle Developer Portal.

Responses

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
400 Bad Request	Returned when a parameter in the request has an invalid value.

Click to hide response attributes.

Name	Type	Description
access_token	string	The access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_in	string	Remaining lifetime of an access token in seconds.
refresh_token	string	A refresh token that is used to exchange for the next access token, when it's expired. A refresh token has a lifetime of 180 days. A refresh token is generated everytime a new access token is generated with the last generated refresh token. Use the new refresh token to exchange for the next access token.

Fetches information about a user's organisation.

Copy
1
GET users/self

See example Get user information.

None

Click to hide HTTP status codes.

Status code	Description
200 OK	Returned when the operation is successful.
404 Not found	Returned when the request is invalid.

Click to hide response attributes.

Name	Type	Description
uuid	string	Unique identifier for the user.
organizationUuid	string	Unique identifier for the user's organization.

Remove a Zettle merchant from your app by disconnecting them from the app. This can be useful to clean up registered webhooks and remove access.

Copy
1
DELETE application-connections/self

See example Remove app from user.

None

Click to hide HTTP status codes.

Status code	Description
204 No Content	Returned when the operation is successful.
404 Not found	Returned when the request is invalid.

The following example retrieves an access token using the assertion grant flow. The response value expires_in is the remaining lifetime of the access token in seconds. The access token is valid for 7200 seconds.

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=6adde977-c34d-4de1-99b2-f6ed3e65431a&assertion=eyJraWQiOiIwIiwidHlwIjoiSl...y9V15QKjn4ZgKRumYb_ikw" https://oauth.zettle.com/token

Response

Copy
1
{
2
    "access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",
3
    "expires_in": 7200
4
}

The following example asks users of an app with a redirect URI to www.example.com to authenticate themselves as valid Zettle merchants and authorise the app with read and write access to their product library.

https://oauth.zettle.com/authorize?response_type=code&scope=READ:PRODUC
T%20WRITE:PRODUCT&client_id=6adde977-c34d-4de1-99b2-
f6ed3e65431a&redirect_uri=https%3A%2F%2Fwww.example.com%2Fzettle%2Fretu
rn&state=abc123678

The following example shows that the users are redirected to the app with URL ww.example.com and an authorisation code 4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678.

https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678

The following example retrieves access token and refresh token using the authorisation code. The access token is valid for 7200 seconds and the refresh token is valid for 180 days.

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&client_secret=7356b8a1-75ac-4336-970b-bef63cd219c1&client_id=c55de605-48b6-42ef-b69e-cd9d14ded15a" https://oauth.zettle.com/token

Response

Copy
1
{
2
    "access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",
3
    "refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",
4
    "expires_in": 7200
5
}

The following example retrieves a new access token using the refresh token. The access token is valid for 7200 seconds.

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=IZSEC90590831-93a5-4289-ee37-a17824c0fea1&client_secret=IZSECe8b27fdb-faea-46e1-a886-6eded9f84f72&client_id=6adde977-c34d-4de1-99b2-f6ed3e65431a" https://oauth.zettle.com/token

Response

Copy
1
{
2
    "access_token": "eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q",
3
    "refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",
4
    "expires_in": 7200
5
}

The following example initiating URL asks the merchant to authorise the app with read and write access to the merchant's payments and user information.

 https://oauth.zettle.com/authorize?response_type=code&scope=WRITE:PAYMENT%20READ:PAYMENT%20READ:CUSTOMER%20READ:USERINFO&client_id={client_ID}&redirect_uri={redirect_uri}&state=8787&code_challenge={code_challenge}&code_challenge_method=S256

The following example shows that the users are redirected to the app with URL ww.example.com and an authorisation code 4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678.

https://www.example.com/get?code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&state=abc123678

The following example retrieves access token and refresh token using the authorisation code. The access token is valid for 7200 seconds and the refresh token is valid for 180 days.

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=authorization_code&code=4fa87ba8cc7f30e91ad2ab1ad21c1b3e&code_verifier=ab190879772...012988&client_id=c55de605-48b6-42ef-b69e-cd9d14ded15a" https://oauth.zettle.com/token

Response

Copy
1
{
2
    "access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",
3
    "refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",
4
    "expires_in": 7200
5
}

The following example retrieves a new access token using the refresh token. The access token is valid for 7200 seconds.

Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=refresh_token&refresh_token=IZSEC90590831-93a5-4289-ee37-a17824c0fea1&client_id=6adde977-c34d-4de1-99b2-f6ed3e65431a" https://oauth.zettle.com/token

Response

Copy
1
{
2
    "access_token": "eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q",
3
    "refresh_token": "IZSEC07b0edfc-f557-4e52-a995-384288e2351e",
4
    "expires_in": 7200
5
}

The following example gets information about an app user.

Request

GET users/self HTTP/1.1
Host: oauth.zettle.com
Authorization: Bearer eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q

Response

Copy
1
{
2
    "uuid": "de305d54-75b4-431b-adb2-eb6b9e546014",
3
    "organizationUuid": "ab305d54-75b4-431b-adb2-eb6b9e546013"
4
}

The following example removes the connection between the app and a user.

Request

DELETE application-connections/self HTTP/1.1
Host: oauth.zettle.com
Authorization: Bearer eyJraWQiOiIxN...R5Y6FDNTva7esJ5Q

Response

Copy
1
204 No content

• Set up authorisation assertion grant
• Set up authorisation code grant
• Set up authorisation code grant with PKCE
• Disconnect app from user