Zettle Finance API

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