Developer
HomeGet startedAPI docs
Support
Log in
Sign up

Fetch purchase information for transactions

Using the Finance API and the Purchase API, you can fetch purchase information for transactions. The originatingTransactionUuid of a transaction in the Finance API corresponds to the uuid of payments in the Purchase API.
The Finance API records transactions for payment types that are supported by the Purchase API except IZETTLE_CASH, SWISH, VIPPS, MOBILE_PAY, GIFTCARD, and IZETTLE_INVOICE.
All transactions for supported payment types will have the transaction type PAYMENT or PAYMENT_FEE in the Finance API.

Try out in Postman

Download Postman collection for this user guide and import it in Postman.

Prerequisites

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

Step 1: Find the transaction UUID with the Finance API

Currently, fetching purchase information is available only for transactions that are made with cards and APMs like PayPal QRC through Zettle.
Before you can find the transaction UUID, you need to specify the transactions types to fetch all transactions of a specific payment method.
  1. Fetch all transactions of one or more transaction types during a specific period from both the prelimimary account and the liquid account. Then the response will also return transactions that are still being checked by Zettle with the acquiring bank.
    GET /v2/accounts/{accountTypeGroup}/transactions?start={start}&end={end}&includeTransactionType={includeTransactionType}
    Example: The following example fetches all transactions for payments and payment fees of the merchant's Zettle liquid account from 1 June, 2020 to 31 December, 2020.
    Request
    GET /v2/accounts/liquid/transactions?start=2020-06-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": -621,
    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": 1100,
    12
                "originatorTransactionType": "PAYMENT",
    13
                "originatingTransactionUuid": "6820265b-953e-43a7-bb65-abac1ef104bf"
    14
            },
    15
            {
    16
                "timestamp": "2020-06-01T04:00:06.680+00:00",
    17
                "amount": -75,
    18
                "originatorTransactionType": "PAYMENT_FEE",
    19
                "originatingTransactionUuid": "e548933c-53fb-4a99-bbc5-c31f7861bcc3"
    20
            },
    21
            {
    22
                "timestamp": "2020-06-01T04:00:06.672+00:00",
    23
                "amount": 3000,
    24
                "originatorTransactionType": "PAYMENT",
    25
                "originatingTransactionUuid": "e548933c-53fb-4a99-bbc5-c31f7861bcc3"
    26
            }
    27
        ]
    28
    }
  2. In the response, find and save the value of originatingTransactionUuid for transactions for which you want to fetch purchase information.

Step 2: Fetch purchase information for transactions with the Purchase API

Using the value of originatingTransactionUuid of a transaction in the Finance API, you can use the Purchase API to locate the purchase information for the transaction.
  1. Fetch purchases regularly, for example every midnight, and store the data in a local database. In the request parameters, set the startDate to the last time of fetching purchases.
    GET /purchases/v2?startDate={startDate}
    Example: The following request example fetches purchase information from 19 November, 2020.
    Request
    /purchases/v2/?startDate=2020-11-19
  2. In the local database, find the purchase by iterating through each purchase's payments list and searching for a payment with the same uuid as the transaction's originatingTransactionUuid that you saved in Step 1: Find the transaction UUID with the Finance API.
    Example: In the following example response that returns purchase information from 19 November, 2020, search for 6820265b-953e-43a7-bb65-abac1ef104bf that is the value of originatingTransactionUuid of the transaction. It's the same value of uuid of the payments that belongs to the purchase with purchaseUUID1 as 2252b412-f531-405b-a073-1b3b9f2bbdd4.
    1
    {
    2
         "purchases": [
    3
             {
    4
                 "source": "POS",
    5
                 "purchaseUUID": "GV2NDCpCEeuqwlj953Nabw",
    6
                 "amount": 49950,
    7
                 "vatAmount": 9990,
    8
                 "taxAmount": 9990,
    9
                 "country": "SE",
    10
                 "currency": "SEK",
    11
                 "timestamp": "2020-11-19T08:35:04.230+00:00",
    12
                 "purchaseNumber": 12496,
    13
                 "globalPurchaseNumber": 12496,
    14
                 "userDisplayName": "iZettle DEMO SE",
    15
                 "userId": 872591,
    16
                 "organizationId": 6394297,
    17
                 "products": [
    18
                      ...
    19
                 ],
    20
                 "discounts": [
    21
                      ...
    22
                 ],
    23
                 "payments": [
    24
                     {
    25
                     "uuid": "6820265b-953e-43a7-bb65-abac1ef104bf",
    26
                     "receiverOrganization": "48eb8d8a-ae8f-4940-83e9-485d80f21aa0",
    27
                     "amount": 1100,
    28
                     "type": "KLARNA",
    29
                     "currency": "SEK",
    30
                     "country": "SE",
    31
                     ...
    32
                         }
    33
                     }
    34
                 ],
    35
                 ...
    36
             "created": "2020-11-20T08:36:56.419+00:00",
    37
             "refunded": false,
    38
             "purchaseUUID1": "2252b412-f531-405b-a073-1b3b9f2bbdd4",
    39
             "groupedVatAmounts": {
    40
                 "12.0": 1000,
    41
                 "25.0": 100
    42
             },
    43
             "refund": false
    44
             },
    45
             ...
    46
         ],
    47
         "firstPurchaseHash": "1605774904230GV2NDCpCEeuqwlj953Nabw",
    48
         "lastPurchaseHash": "1605882295421KEx7SCs8EeuzPiiU-CPahg",
    49
         "linkUrls": []
    50
     }

Related information