Fetch account transactions

Use the Finance API to fetch transactions or transactions of certain types from a merchant's liquid account during a specific period.

Prerequisites

  • Make sure that authorisation is set up with the following OAuth scope using OAuth API:
    • READ:FINANCE

Fetch transactions during a specific period

When fetching transactions from a merchant's Zettle account during a specific period, set pagination to avoid a big dataset in a response. The transactions should be fetched from the merchant's liquid account.
  1. Send a request where you set limit as the number of transactions to fetch and offset as 0.
    GET /v2/accounts/{accountTypeGroup}/transactions?start={start_time}&end={end_time}&limit={limit_value}&offset={offset_value}
    
    Example: The following example fetches the latest three transactions from the merchant's liquid account from 1 January, 2020 to 5 July, 2020.
    Request
    GET /v2/accounts/liquid/transactions?start=2020-01-01T00:00:00-00:00&end=2020-07-06T00:00:00-00:00&limit=3&offset=0
    
    Response
    1
    {
    2
    "data": [
    3
    {
    4
    "timestamp": "2020-07-04T20:16:44.309+00:00",
    5
    "amount": 381,
    6
    "originatorTransactionType": "PAYMENT_FEE",
    7
    "originatingTransactionUuid": "30cef6e2-be09-11ea-a8e4-bce028663c34"
    8
    },
    9
    {
    10
    "timestamp": "2020-07-04T20:16:44.309+00:00",
    11
    "amount": -20610,
    12
    "originatorTransactionType": "PAYMENT",
    13
    "originatingTransactionUuid": "30cef6e2-be09-11ea-a8e4-bce028663c34"
    14
    },
    15
    {
    16
    "timestamp": "2020-06-27T23:52:18.327+00:00",
    17
    "amount": 649, // Positive in case of refund
    18
    "originatorTransactionType": "PAYMENT_FEE",
    19
    "originatingTransactionUuid": "690c99ea-b6ef-11ea-9730-7ef7aeff642d"
    20
    }
    21
    ]
    22
    }
  2. Send another request where you keep limit the same as in step 1 and increment offset with the value of limit .
    GET /v2/accounts/{accountTypeGroup}/transactions?start={start_time}&end={end_time}&limit={limit_value}&offset={offset_value}
    
    Example: The following example fetches the next three transactions from the merchant's liquid account from 1 January, 2020 to 5 July, 2020.
    Request
    GET /v2/accounts/liquid/transactions?start=2020-01-01T00:00:00-00:00&end=2020-07-06T00:00:00-00:00&limit=3&offset=3
    
    Response
    1
    {
    2
    "data": [
    3
    {
    4
    "timestamp": "2020-06-27T23:52:18.327+00:00",
    5
    "amount": -35100, // Negative in case of refund
    6
    "originatorTransactionType": "PAYMENT",
    7
    "originatingTransactionUuid": "690c99ea-b6ef-11ea-9730-7ef7aeff642d"
    8
    },
    9
    {
    10
    "timestamp": "2020-06-26T19:51:38.161+00:00",
    11
    "amount": -649,
    12
    "originatorTransactionType": "PAYMENT_FEE",
    13
    "originatingTransactionUuid": "45f51ed4-b7bf-11ea-90de-435a3f6e4738"
    14
    },
    15
    {
    16
    "timestamp": "2020-06-26T19:51:38.161+00:00",
    17
    "amount": 35100,
    18
    "originatorTransactionType": "PAYMENT",
    19
    "originatingTransactionUuid": "45f51ed4-b7bf-11ea-90de-435a3f6e4738"
    20
    }
    21
    ]
    22
    }
  3. Repeat step 2 until the response is empty or it contains fewer transactions than the limit .
    Example: The following example shows that last two transactions are fetched from the merchant's liquid account from 1 January, 2020 to 5 July, 2020.
    Request
    GET /v2/accounts/liquid/transactions?start=2020-01-01T00:00:00-00:00&end=2020-07-06T00:00:00-00:00&limit=3&offset=30
    
    Response
    1
    {
    2
    "data": [
    3
    {
    4
    "timestamp": "2020-01-02T15:16:43.945+00:00",
    5
    "amount": -8867,
    6
    "originatorTransactionType": "PAYMENT_FEE",
    7
    "originatingTransactionUuid": "7428bda0-2d50-11ea-9132-999363d04928"
    8
    },
    9
    {
    10
    "timestamp": "2020-01-02T15:16:43.945+00:00",
    11
    "amount": 479300,
    12
    "originatorTransactionType": "PAYMENT",
    13
    "originatingTransactionUuid": "7428bda0-2d50-11ea-9132-999363d04928"
    14
    }
    15
    ]
    16
    }

Fetch transactions of certain types during a specific period

You can fetch transactions of certain types from a merchant's Zettle account during a specific period. For example, you can fetch all payments. The transactions should be fetched from the merchant's liquid account.
Send a request where you specify transaction types as you need. See supported transaction types in Finance API reference V2.
GET /v2/accounts/liquid/transactions?start={start_date}&end={end_date}&includeTransactionType={includeTransactionType}

Fetch card payment fee

Example: The following example fetches all payments and associated payment fees from the merchant's liquid account. The transactions are fetched from 1 January, 2020 to 31 December, 2020.
Request
GET /v2/accounts/liquid/transactions?start=2020-01-01T00:00:00-00:00&end=2021-01-01T00:00:00-00:00&includeTransactionType=PAYMENT&includeTransactionType=PAYMENT_FEE
Response
1
{
2
"data": [
3
{
4
"timestamp": "2020-11-21T04:00:15.704+00:00",
5
"amount": -8867,
6
"originatorTransactionType": "PAYMENT_FEE",
7
"originatingTransactionUuid": "6820265b-953e-43a7-bb65-abac1ef104bf"
8
},
9
{
10
"timestamp": "2020-11-21T04:00:15.697+00:00",
11
"amount": 479300,
12
"originatorTransactionType": "PAYMENT",
13
"originatingTransactionUuid": "6820265b-953e-43a7-bb65-abac1ef104bf"
14
},
15
...
16
]
17
}

Fetch transactions for payout

Example: The following example fetches all the transactions that are are included in the payout from the merchant's liquid account. The transactions are fetched from 6 September, 2020 to 10 September, 2020.
Request
GET /v2/accounts/liquid/transactions?start=2020-09-06T00:00:00-00:00&end=2020-09-11T00:00:00-00:00&includeTransactionType=PAYOUT
Response
1
{
2
"data": [
3
{
4
"timestamp": "2020-09-10T09:27:28.590+00:00",
5
"amount": -7925,
6
"originatorTransactionType": "PAYOUT",
7
"originatingTransactionUuid": "d8550d7a-f347-11ea-9612-3bce5300b9a9"
8
},
9
{
10
"timestamp": "2020-09-07T09:27:33.871+00:00",
11
"amount": -5925,
12
"originatorTransactionType": "PAYOUT",
13
"originatingTransactionUuid": "5c3db780-f0ec-11ea-8341-8d3f8a575c00"
14
}
15
...
16
]
17
}