OAuth API reference

About OAuth API

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.

Base URL

https://oauth.zettle.com

OAuth Scope

Not applicable

Authorisation assertion grant

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 users to authenticate and authorise

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.

Retrieve an access token

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.

1
POST /token
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.
NameTypeInRequired/OptionalDescription
grant_typestringobjectrequiredAlways 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_idstringobjectrequiredAn 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 codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned 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.
NameTypeDescription
access_tokenstringThe access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_instringRemaining lifetime of an access token in seconds.

Authorisation code grant

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

Ask users to authenticate and authorise

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.

1
GET /authorize?response_type=code&
2
scope={oauth_scope}&
3
client_id={client_ID}&
4
redirect_uri={redirect_uri}&
5
state={state_value}
Zettle login page where your user will be asked to log in to their Zettle merchant account.

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.
NameTypeInRequired/OptionalDescription
response_typestringqueryrequiredAlways set to code to indicate an authorisation code is returned as the response.
scopestringqueryrequiredSpace-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_idstringqueryrequiredAn app credential that you get after creating credentials for a partner-hosted app on Zettle Developer Portal.
redirect_uristringqueryrequiredA 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, awesomeapp://zettlelogin.
statestringqueryrequiredA 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 codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned when the operation contains invalid parameters.
405 Method Not AllowedReturned when the operation is not allowed.

Retrieve the first access and refresh token

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.

1
POST /token
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.
NameTypeInRequired/OptionalDescription
grant_typestringobjectrequiredAlways set to authorization_code to indicate an authorisation code is used to exchange for an access token.
redirect_uristringobjectrequiredA 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.
codestringobjectrequiredAn 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_secretstringobjectrequiredAn app credential that you get after creating credentials for a partner-hosted on Zettle Developer Portal.
client_idstringobjectrequiredAn 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 codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned when a parameter in the request has an invalid value.
Click to hide response attributes.
NameTypeDescription
access_tokenstringThe access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_instringRemaining lifetime of an access token in seconds.
refresh_tokenstringA 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.

Generate a new access token from the refresh token

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.

1
POST /token
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.
NameTypeInRequired/OptionalDescription
grant_typestringobjectrequiredAlways set to refresh_token to indicate a refresh token is used to exchange for an access token.
refresh_tokenstringobjectrequiredThe refresh token that is retrieved previously.
client_secretstringobjectrequiredAn app credential that you get after creating credentials for a partner-hosted on Zettle Developer Portal.
client_idstringobjectrequiredAn 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 codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned when a parameter in the request has an invalid value.
Click to hide response attributes.
NameTypeDescription
access_tokenstringThe access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_instringRemaining lifetime of an access token in seconds.
refresh_tokenstringA 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.

Authorisation code grant with PKCE

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.

Ask users to authenticate and authorise

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.

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}
Zettle login page where your user will be asked to log in to their Zettle merchant account.

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.
NameTypeInRequired/OptionalDescription
response_typestringqueryrequiredAlways set to code to indicate an authorisation code is returned as the response.
scopestringqueryrequiredSpace-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_idstringqueryrequiredAn app credential that you get after creating credentials for an SDK app on Zettle Developer Portal.
redirect_uristringqueryrequiredA 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.
statestringqueryrequiredA 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_challengestringqueryrequiredA 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_methodstringqueryrequiredThe 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 codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned when the operation contains invalid parameters.
405 Method Not AllowedReturned when the operation is not allowed.

Retrieve the first access and refresh token

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.

1
POST /token
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.
NameTypeInRequired/OptionalDescription
grant_typestringobjectrequiredAlways set to authorization_code to indicate an authorisation code is used to exchange for an access token.
codestringobjectrequiredAn 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_verifierstringobjectrequiredThe random string that is encoded to create a code challenge. It's between 43 and 128 characters long.
client_idstringobjectrequiredAn app credential that you get after creating credentials for an SDK app on Zettle Developer Portal.

Responses

Click to hide HTTP status codes.
Status codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned when a parameter in the request has an invalid value.
Click to hide response attributes.
NameTypeDescription
access_tokenstringThe access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_instringRemaining lifetime of an access token in seconds.
refresh_tokenstringA 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.

Generate a new access token from the refresh token

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.

1
POST /token
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.
NameTypeInRequired/OptionalDescription
grant_typestringobjectrequiredAlways set to refresh_token to indicate a refresh token is used to exchange for an access token.
refresh_tokenstringobjectrequiredThe refresh token that is retrieved previously.
client_idstringobjectrequiredAn app credential that you get after creating credentials for an SDK app on Zettle Developer Portal.

Responses

Click to hide HTTP status codes.
Status codeDescription
200 OKReturned when the operation is successful.
400 Bad RequestReturned when a parameter in the request has an invalid value.
Click to hide response attributes.
NameTypeDescription
access_tokenstringThe access token that is exchanged with the authorisation code. An access token has a lifetime of 7200 seconds (2 hours).
expires_instringRemaining lifetime of an access token in seconds.
refresh_tokenstringA 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.

Get user information

Fetches information about a user's organisation.

1
GET users/self

See example Get user information.

Parameters

None

Responses

Click to hide HTTP status codes.
Status codeDescription
200 OKReturned when the operation is successful.
404 Not foundReturned when the request is invalid.
Click to hide response attributes.
NameTypeDescription
uuidstringUnique identifier for the user.
organizationUuidstringUnique identifier for the user's organization.

Disconnect app from user

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.

1
DELETE application-connections/self

See example Remove app from user.

Parameters

None

Responses

Click to hide HTTP status codes.
Status codeDescription
204 No ContentReturned when the operation is successful.
404 Not foundReturned when the request is invalid.

Examples

Retrieve an access token (Assertion grant)

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

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

Ask app users to authenticate and authorise (code grant)

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

Retrieve the first access and refresh token (code grant)

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

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

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

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

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

Ask app users to authenticate and authorise (PKCE)

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

Retrieve the first access and refresh token (PKCE)

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

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

Generate a new access token from the refresh token (PKCE)

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

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

Get information about a user

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

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

Remove a user from the app

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

1
204 No content