Developer
HomeGet startedAPI docs
Support
Log in
Sign up

Zettle glossary

A

  • Access token
    A JSON web token (JWT) that an app uses to access data of a Zettle merchant (account owner). The token is opaque and specifies the permissions authorised by the Zettle merchant. The token lifetime is 7200 seconds (2 hours). A new access token can be fetched with an API key or a refresh token.
  • Account balance
    The amount of money present in a financial repository at any given moment. A Zettle merchant account has two depositories: A preliminary account and liquid account. The Zettle Finance API can be used for fetching the balance in the preliminary and liquid accounts for a merchant.
  • Acquiring bank
    Also known as acquirer. A financial institution that authenticates the cardholder and authorises the transaction. It makes sure that the card is valid and the card has sufficient funds to complete the transaction.
  • API key
    Also known as an assertion. An API key is in the form of a JSON web token (JWT) assertion and is used to retrieve an access token. The API key is created by a Zettle merchant (account owner) from my.zettle.com. It contains merchant identity and specifies permissions of access for authentication and authorisation in the assertion grant authorisation flow for self-hosted apps.
  • Assertion grant
    An authorisation flow based on the OAuth framework. In the flow, a JSON web token (JWT) assertion is used in exchange for an access token with the Zettle authorisation server. The JWT assertion is used as an API key. See API key.
  • Authorisation code
    Short-lived temporary code that the authorisation server sends to the user (app). The app then sends the authorisation code back to the authorisation server, along with the client secret, in exchange for an access token. See Client secret.
  • Authorisation code grant
    Authorisation method based on the OAuth framework. Authorisation in multiple steps, where the account owner (merchant), the app, and the authorisation server interact and exchange proof to provide an access token. See Partner-hosted app.

C

  • Client ID
    Used to identify the app with the authorisation server. Generated in the Developer Portal when creating (registering) an app.
  • Client secret
    Secret password used to privately share data. Generated in the Developer Portal when creating (registering) an app.
  • Custom amount sale
    Type of product attribute in the Purchase API. Indicates that the item sold was not in the product library, and a custom amount was entered in the app for the item, at the time of purchase.

E

  • ETag
    The ETag (entity tag) is an HTTP response header used for identifying a specific version of a resource. ETags are often used to speed up requests by ensuring that data stored in a cache is up to date. The Zettle Product Library and Inventory services use ETags to avoid synchronization conflicts when integrating with external systems.
  • Event payload
    An event is an action triggered for example by a system or a user. The payload field is the response body from APIs such as Purchase. The field contains event information sent to the receiving endpoint. There are several events for synchronising for example purchase, product library, and inventory data. See Subscription.
  • Exchange
    Instead of returning a payment, a seller can use an exchange with different goods than what was in the original sale, to refund a buyer.
  • Extra amount tipping flow
    This flow prompts customers with a question before entering the tip amount. This tipping flow can be used when taking card payments using the Zettle SDK. See Total amount tipping flow.

G

  • Gift Card
    Prepaid stored-value money certificate. Typically issued by a merchant to be used as payment method for purchases at a particular store. When using the Purchase API, a gift card can be a payment method for a purchase. A gift card can also be a product type available in the product library. The Zettle Gift Card API is used to programmatically fetch details for a gift card.

I

  • Inventory balance
    The sum of all product items available at a specific location. The inventory balance for the store location type is usually the most important for integrations. See Location.
  • Issuing bank
    Also known as issuer. A bank or financial institution that offers payment cards. For example, credit and debit cards.

L

  • Liquid account
    A Zettle merchant account. It’s used to hold funds that are ready to be paid out to merchants. After a transaction happens, the funds are recorded in the preliminary account while Zettle is checking whether the funds should be paid out. After that, the funds will be moved to and recorded in the liquid account while waiting to be paid out. See Preliminary account.
  • Location
    The Inventory service keeps track of inventory balances by moving products between locations. These are created automatically when tracking is enabled for a product. A location can be a physical "Store", or virtual like "Sold", "Bin" (discarded products), or "Supplier" (for stock replenishment).
  • Low stock threshold
    This is the minimum amount of inventory a merchant wants to have on hand. You can set the low stock threshold value through the Inventory API to help merchants manage their inventory.

M

  • Minor currency unit
    Also known as minor unit. The smallest unit of a currency. For example, for two-decimal currencies like US dollars, 199 with currency USD means $1.99 at Zettle. For zero-decimal currencies like Japanese Yen, 1095 with currency JPY means ¥1095 at Zettle.

P

  • Partial return
    Goods that is part of an original sale is being returned. In such a case, an amount is normally resolved and refunded from the original payment. See Refund.
  • Partner-hosted app
    App type owned by the partner integrator that built the app. Uses the code grant authorisation method. Previously named public app. See Self-hosted app.
  • Payment
    Corresponds to money being exchanged between seller and buyer as part of a sale. Can also be a “return of sale”, in which case payment is often referred to as refund.
  • Payout
    The action to deposit the account balance amount to a merchant's bank account or PayPal Wallet. Payout is done at a scheduled time that varies depending on country. See Account balance.
  • Preliminary account
    A Zettle merchant account. It’s used to hold funds that are being checked by Zettle. After a transaction happens, the funds are recorded in the preliminary account while Zettle is checking whether the funds should be paid out. After that, the funds will be moved to and recorded in the liquid account while waiting to be paid out. See Liquid account.
  • Purchase
    The acquisition of an item or service that is typically paid for through an exchange of money or other asset.

R

  • Redirect URI
    A URL that starts with https and includes a redirect URI. This directs app users (Zettle merchants) back to an app, after they have authorised access to their merchant data. Example: someapp://zettlelogin. Sometimes referred to as callback URL. Only URIs registered with the app in the Developer Portal are allowed.
  • Refresh token
    Used in exchange for a new access token in an authorisation code grant flow, when the current access token has expired. A refresh token has a lifetime of 180 days See Access token.
  • Refund
    Money being exchanged as the result of a returned sale. Items or services from the sale are being returned, and money is transferred from the seller back to the buyer.
  • Return
    When a customer sends an item back to your store or warehouse. Customers must usually return an item before they get a refund.

S

  • Sale
    A business event between a seller and a buyer. Normally means giving out some goods or services to a buyer, who in turn promises to somehow fund the seller.
  • Scope
    The granular permissions an app needs to access or perform actions on a merchant’s data. Part of the authorisation process. For example, the Inventory API typically needs READ:PRODUCT and WRITE:PRODUCT access to a merchant's product library data.
  • SDK app
    App type used for adding in-person payment functionality to other apps. Also referred to as in-app payment.
  • Self-hosted app
    App type owned by individual merchants. Uses the assertion grant (API key) authorisation method. Previously named private app. See Partner-hosted app.
  • SKU
    A stock keeping unit (SKU) is a unique code for identifying and tracking products in the inventory or stock.
  • Stock level
    The number of products a merchant needs to have at hand to fulfill customer orders and delivery expectations. Inventory management helps maintain the stock level as low as possible, and at the same time make products available when required.
  • Subscription
    By subscribing to specific events, information updates can be shared between systems. Using the Pusher API, a POST request with a payload field is sent when an event of a subscription is triggered. There are several events for synchronising for example purchase, product library, and inventory data. See Event payload.

T

  • Tipping rate limit
    Prevents entering of incorrect tipping amount in the Zettle card reader. Validation against the limit ensures that the tipping amount is not too high, for example if a customer enters their pin code by mistake. The validation also ensures that the tipping amount entered is higher than the total amount.
  • Total amount tipping flow
    This lets customers enter the total amount, including tip, directly. This tipping flow can be used when taking card payments using the Zettle SDK. See Extra amount tipping flow.
  • Tracking
    The Inventory service provides tracking of items in the product library. Tracking is applied to products for inventory balance calculations. This lets a merchant know how many items are available for selling, and if stock replenishment is needed. If tracking is enabled for a product, sales through the POS system are automatically tracked, and the inventory is updated accordingly.
  • Transaction
    An instance of buying or selling something. When a merchant takes a payment with Zettle, a payment transaction is recorded.

V

  • VAT
    Value-added tax.
  • Void
    If a payout or a transaction is made void, it means that they failed and therefore are not processed.

W

  • Webhooks
    HTTP callbacks that receive notification messages for events. By subscribing to these events, information updates can be shared between systems. The Zettle Pusher API uses webhooks for notifications about for example purchase, product, and inventory updates. See Subscription.