Purchase API interactions

The Purchase API provides read-only information about purchases made through Zettle. This information is then available for consumption by other services. Updates on accounts, gift cards, and inventory are examples of instances that use the purchase information. The purchase information can be received by subscribing to specific events using Pusher API. See Pusher API overview for more details.

Information transfer in the payment purchase flow.

Merchants who take payments with Zettle have a Zettle account that processes transactions for payments. The account handles different status of transactions. After a merchant takes a payment with Zettle, the payment transaction is recorded and confirmed, and the payout is prepared. The payment happens before the actual purchase, most often immediately. However, due to different reasons, some delay might occur between the two.

The following describes how purchase information is used by other instances. See Purchase concept and Purchase API reference for specific details about the purchase information.

Finance API interactions

The Finance API is used for fetching finance-related information processed through Zettle. The information includes account balance, transactions processed through Zettle, and payout. This also includes payment types which are part of the Purchase API information, whereas transactions represent the Finance API side.

In the Purchase API, payments include the payment type and the payment UUID, which are used by the Finance API to link to a transaction.

1
"payments": [
2
{
3
"uuid": "592b82f2-3ee4-11eb-9f71-a3ad065a16fc",
4
"amount": 70000,
5
"type": "IZETTLE_CARD",
6
"attributes": {
7
}
8
}
9
],

The Finance API records transactions from payment types in the Purchase API. For example, every purchase made with a card is displayed as IZETTLE_CARD in the Purchase API, and CARD_PAYMENT and CARD_PAYMENT_FEE in the Finance API. They are linked through the originatingTransactionUuiD (Finance API), and the payment UUID (Purchase API).

The following payment types are available in the Purchase API:

  • IZETTLE_CARD
  • IZETTLE_CARD_ONLINE
  • IZETTLE_CASH
  • IZETTLE_INVOICE
  • MOBILE_PAY
  • SWISH
  • VIPPS
  • STORE_CREDIT
  • GIFTCARD
  • PAYPAL
  • KLARNA

Not all of these payment types are supported by the Finance API. IZETTLE_CARD (payment/refund), IZETTLE_CARD_ONLINE , PAYPAL, and KLARNAare supported, and can be linked to transaction types.

See Fetch purchase information for card transactions for more information.

For refunds, IZETTLE_CARD is the paymen t type used in the Purchase API, and CARD_REFUND and CARD_PAYMENT_FEE_REFUND are the corresponding transaction types in the Finance API. In the refund case, there will be a new purchase entry created with a negative amount. In the Finance API, CARD_REFUND will be referring to the new purchase, instead of the original one.

Some payment types in the Purchase API involve transaction of funds that do not go through Zettle: IZETTLE_CASH , SWISH, VIPPS, MOBILE_PAY, GIFTCARD, and STORE_CREDIT. These transactions will not show up in the Finance API.

Linking of the IZETTLE_INVOICE payment type to transactions in the Finance API depends on how the invoice is paid. A merchant can issue an invoice, but it doesn't guarantee that the buyer will pay it through the payment option provided by Zettle. For example, a merchant can issue the invoice to the buyer. The buyer can then use a payment method like Swish or cash, to pay the invoice.

In Sweden for example, buyers get the option to pay a Zettle invoice through bank transfer. In this case, the payment will be dispersed to the merchant through an INVOICE_PAYMENT transaction in the Finance API. It is currently not possible to map an INVOICE_PAYMENT in the Finance API with a purchase.

In countries where invoices can not be paid with bank transfer, buyers will have the option to pay online with a card. If the invoice is paid this way, it will be dispersed to the merchant as IZETTLE_CARD or IZETTLE_CARD_ONLINE in the Purchase API, and CARD_PAYMENT in the Finance API, instead of an INVOICE_PAYMENT.

Gift Card API interactions

A gift card can be used to pay for a purchase, partially or entirely. A gift card can also be a product in the product library, and sold in the POS system. The Gift Card API provides extra information about purchases made through Zettle using gift cards.

  • The GIFTCARD payment type represents a payment made with a gift card (certificate/voucher) issued by a merchant.
  • In the Purchase API response, the product attribute type is an enumeration which has a GIFTCARD value indicating that a product is a gift card.

See Gift Card API for more details.

Note: Fetching transactions for payments made with gift cards is currently not supported.

Inventory API interactions

When a product is sold, it is moved from the STORE location to the SOLD location. The information in the Purchase API contains details about location movements through the fromLocationUuid and toLocationUuuid parameters, for the product sold.

Triggering events

Examples:

For Finance API interactions, you can monitor purchases by subscribing to the PurchaseCreated event.

To monitor inventory balance updates, you can subscribe to the InventoryBalanceChanged event.

See Pusher API overview for more details.