Zettle accounts API
The accounts API from Zettle — 2 operation(s) for accounts.
OpenAPI Specification
openapi: 3.0.3
info:
title: Finance accounts API
description: 'The Finance API is used to fetch finance-related information that is processed through Zettle. The information includes account balance, all the transactions processed through Zettle, and payout.
'
version: '2.0'
servers:
- url: https://finance.izettle.com/v2
description: Production
tags:
- name: accounts
paths:
/accounts/{accountTypeGroup}/balance:
get:
tags:
- accounts
operationId: getBalance
summary: Get account balance
description: Returns the balance in a merchant's preliminary or liquid account at a specific time.
parameters:
- $ref: '#/components/parameters/accountTypeGroupParam'
- name: at
in: query
description: 'Used to fetch account balance at a certain point in time. The time is specified in UTC. If this parameter is used, any transaction after that point will be ignored. If not, the balance of all transactions at the current point in time is returned.
'
required: false
schema:
type: string
format: YYYY-MM-DDThh:mm:ss
example: '2022-03-01T12:42:10'
default: NOW()
responses:
'200':
description: 'Returns when the operation is successful. The account balance in the currency''s smallest unit. For example, 300 with currency GBP is £3.
'
content:
application/json:
schema:
type: object
properties:
totalBalance:
type: integer
description: 'The account balance in the currency''s smallest unit. For example, 300 with currency GBP is £3. It can be negative when refunds are greater than sales.
'
example: 300
currencyId:
description: The currency of the account. For example, GBP.
type: string
example: GBP
'400':
description: Returns when a required parameter is missing or in a wrong format in the request
'401':
description: "Returns when one of the following occurs:\n - The authentication information is missing in the request.\n - The authentication token has expired.\n - The authentication token is invalid.\n"
'403':
description: Returns when the scope being used in the request is incorrect.
security:
- ZettleOauth:
- READ:FINANCE
/accounts/{accountTypeGroup}/transactions:
get:
tags:
- accounts
operationId: getAccountTransactions
summary: Get account transactions
description: 'Returns all transactions or transactions of certain types from a merchant''s preliminary or liquid account during a specific period.
'
parameters:
- $ref: '#/components/parameters/accountTypeGroupParam'
- name: start
in: query
description: 'The start time in UTC (inclusive) from when the transactions will be fetched.
'
required: true
schema:
type: string
format: YYYY-MM-DDThh:mm:ss
example: '2022-03-01T12:42:10'
- name: end
in: query
description: 'The end time in UTC (exclusive) before when the transactions will be fetched.
'
required: true
schema:
type: string
format: YYYY-MM-DDThh:mm:ss
example: '2022-03-01T12:42:10'
- name: includeTransactionType
in: query
description: "Specifies the transaction types to fetch. Multiple transaction types can be specified. Available transaction types are:\n | Transaction type | Description | Applicable for account type |\n |-------------------------|-------------|-----------------------------|\n | ADJUSTMENT | A bookkeeping adjustment | LIQUID, PRELIMINARY |\n | ADVANCE | The cash advance given by Zettle to a merchant in the liquid account. | LIQUID |\n | ADVANCE_DOWNPAYMENT | A down payment on a previously paid out cash advance in the liquid account. | LIQUID |\n | ADVANCE_FEE_DOWNPAYMENT | The netting of a cash advance fee in the liquid account. | LIQUID |\n | CASHBACK | Money given to a merchant to retroactively adjust the card payment fee rate. | LIQUID |\n | FAILED_PAYOUT | A previous payout transaction failed and was made void. | LIQUID |\n | FROZEN_FUNDS | The money that is frozen to cover a chargeback. | LIQUID |\n | INVOICE_PAYMENT | An invoice payment. | LIQUID, PRELIMINARY |\n | INVOICE_PAYMENT_FEE | An invoice payment fee. | LIQUID, PRELIMINARY |\n | PAYMENT | A payment where Zettle handles the funds. | LIQUID, PRELIMINARY |\n | PAYMENT_FEE | The fee for a payment where Zettle handles the funds. | LIQUID, PRELIMINARY |\n | PAYMENT_PAYOUT | A payment payout transfer. | LIQUID |\n | PAYOUT | A payout to the merchant's bank account or PayPal Wallet. | LIQUID |\n"
required: false
schema:
type: array
items:
type: string
enum:
- ADJUSTMENT
- ADVANCE
- ADVANCE_DOWNPAYMENT
- ADVANCE_FEE_DOWNPAYMENT
- CASHBACK
- FAILED_PAYOUT
- FROZEN_FUNDS
- INVOICE_PAYMENT
- INVOICE_PAYMENT_FEE
- PAYMENT
- PAYMENT_FEE
- PAYMENT_PAYOUT
- PAYOUT
- name: limit
in: query
description: 'The maximum number of transactions to return in a response.
'
required: false
schema:
type: integer
default: 10000
example: 1000
- name: offset
in: query
description: 'The number of transactions to skip before beginning to return in a response.
'
required: false
schema:
type: integer
default: 0
example: 3
responses:
'200':
description: Returns when the operation is successful.
content:
application/json:
schema:
type: array
items:
type: object
properties:
timestamp:
type: string
description: The time when a transaction is made in the merchant's Zettle account.
example: '2022-03-01T12:42:10'
amount:
type: string
description: 'The amount of money of a transaction in the currency''s smallest unit.
'
example: 300
originatorTransactionType:
type: string
description: The transaction type.
example: PAYOUT
originatorTransactionUuid:
type: string
description: The identifier of the originating transaction as UUID version 1.
example: 5e8673e4-a52f-11ec-b909-0242ac120002
'400':
description: Returns when a required parameter is missing or in a wrong format in the request.
'401':
description: "Returns when one of the following occurs:\n - The authentication information is missing in the request.\n - The authentication token has expired.\n - The authentication token is invalid.\n"
'403':
description: Returns when the scope being used in the request is incorrect.
security:
- ZettleOauth:
- READ:FINANCE
components:
parameters:
accountTypeGroupParam:
name: accountTypeGroup
in: path
description: "The type of a merchant's Zettle account. You can use one of the following account types:\n - PRELIMINARY account where transactions are to be confirmed.\n - LIQUID account where transactions are to be paid out to the merchant.\n"
required: true
schema:
type: string
enum:
- PRELIMINARY
- LIQUID
securitySchemes:
ZettleOauth:
type: oauth2
description: For more information, see the [OAuth API documentation](https://developer.zettle.com/docs/api/oauth/overview).
flows:
authorizationCode:
authorizationUrl: https://oauth.zettle.com/authorize
tokenUrl: https://oauth.zettle.com/token
scopes:
READ:FINANCE: Access to read finance data