openapi: "3.0.3" info: title: Finance 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 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: - The authentication information is missing in the request. - The authentication token has expired. - The authentication token is invalid. "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: | Transaction type | Description | Applicable for account type | |-------------------------|-------------|-----------------------------| | ADJUSTMENT | A bookkeeping adjustment | LIQUID, PRELIMINARY | | ADVANCE | The cash advance given by Zettle to a merchant in the liquid account. | LIQUID | | ADVANCE_DOWNPAYMENT | A down payment on a previously paid out cash advance in the liquid account. | LIQUID | | ADVANCE_FEE_DOWNPAYMENT | The netting of a cash advance fee in the liquid account. | LIQUID | | CASHBACK | Money given to a merchant to retroactively adjust the card payment fee rate. | LIQUID | | FAILED_PAYOUT | A previous payout transaction failed and was made void. | LIQUID | | FROZEN_FUNDS | The money that is frozen to cover a chargeback. | LIQUID | | INVOICE_PAYMENT | An invoice payment. | LIQUID, PRELIMINARY | | INVOICE_PAYMENT_FEE | An invoice payment fee. | LIQUID, PRELIMINARY | | PAYMENT | A payment where Zettle handles the funds. | LIQUID, PRELIMINARY | | PAYMENT_FEE | The fee for a payment where Zettle handles the funds. | LIQUID, PRELIMINARY | | PAYMENT_PAYOUT | A payment payout transfer. | LIQUID | | PAYOUT | A payout to the merchant's bank account or PayPal Wallet. | LIQUID | 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: - The authentication information is missing in the request. - The authentication token has expired. - The authentication token is invalid. "403": description: Returns when the scope being used in the request is incorrect. security: - ZettleOauth: - READ:FINANCE /payout-info: get: tags: - payout operationId: getPayoutInfo summary: Get payout info description: > Returns payout related information from a merchant's liquid account. parameters: - name: at in: query description: > Used to fetch payouts at a certain point in time. The time is specified in UTC. 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. content: application/json: schema: type: object properties: totalBalance: type: integer description: > The account balance in the currency's smallest unit. example: 300 currencyId: description: The currency of the account. For example, GBP. type: string example: GBP nextPayoutAmount: description: > The amount of money to be paid out to the merchant in the currency's smallest unit. type: integer example: 2000 discountRemaining: description: > The amount of discounts that remain in merchant's vouchers in the currency's smallest unit. type: integer example: 9800 periodicity: description: > The period between each payout that is set by the merchant. It can be DAILY, WEEKLY or MONTHLY. type: string example: DAILY "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: - The authentication information is missing in the request. - The authentication token has expired. - The authentication token is invalid. "403": description: Returns when the scope being used in the request is incorrect. security: - ZettleOauth: - READ:FINANCE components: 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 parameters: accountTypeGroupParam: name: accountTypeGroup in: path description: > The type of a merchant's Zettle account. You can use one of the following account types: - PRELIMINARY account where transactions are to be confirmed. - LIQUID account where transactions are to be paid out to the merchant. required: true schema: type: string enum: - PRELIMINARY - LIQUID