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.
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.
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
GIFTCARD
PAYPAL
KLARNA
Not all of these payment types are supported by the Finance API. IZETTLE_CARD
(payment/refund), IZETTLE_CARD_ONLINE
, PAYPAL
, and KLARNA
are 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
, and GIFTCARD
. 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
.
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 aGIFTCARD
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.
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.
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.