-
Notifications
You must be signed in to change notification settings - Fork 29
/
api-reference-v2.yaml
304 lines (301 loc) · 15.4 KB
/
api-reference-v2.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
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. A cash advance is a type of financing that is offered to merchants based on their sales history. The advance is paid back with monthly down payments. | 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. The payout money is returned to the merchant's liquid account. | LIQUID |
| FROZEN_FUNDS | The money that is frozen to cover a chargeback. When the issuing bank initiates a chargeback, the money will be removed from the merchant's liquid account and marked as frozen to cover the chargeback. If the chargeback is later revoked, the money will be returned to the merchant's liquid account with a new and positive transaction of the same type. It effectively makes the initial FROZEN_FUNDS transaction void. | LIQUID |
| INVOICE_PAYMENT | An invoice payment. If an invoice is paid through a card payment, the payment type is PAYMENT.| LIQUID, PRELIMINARY |
| INVOICE_PAYMENT_FEE | An invoice payment fee. If an invoice is paid through a card payment, the payment fee type is PAYMENT_FEE. | LIQUID, PRELIMINARY |
| PAYMENT | A payment where Zettle handles the funds. This includes any type of payment, such as card payments and other alternative payment methods. In the case of a refund, a transaction of the same type will occur but with the inverted amount. Contains a reference to the payment in the Purchase API. | LIQUID, PRELIMINARY |
| PAYMENT_FEE | The fee for a payment where Zettle handles the funds. The amount is positive in case of a refund. Contains a reference to the payment fee in the Purchase API. | LIQUID, PRELIMINARY |
| PAYMENT_PAYOUT | A payment payout with a negative amount is a transfer of money for a single payment from merchant's liquid account to PayPal Wallet. A payment payout with a positive amount is a transfer of money for a refund from PayPal Wallet to the merchant's liquid account. | LIQUID |
| PAYOUT | A payout can be positive or negative. If the account balance is paid out from the merchant’s liquid account to the merchant’s bank account or to PayPal Wallet for PayPal users, the payout is negative. If the merchant’s configuration has a minimum account balance, the payout is the liquid account balance minus the minimum account balance. For example, if the account balance is £147 and the minimum account balance is £47, the payout is £100. For PayPal users, if a refund happens, a payout will be made from PayPal Wallet to the liquid account. In this case, the amount is positive. | 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. You must specify limit with any integer greater
than 0. To avoid a big dataset in a response, use limit and offset together to set response pagination.
For example, to return only three transactions at a time from a collection of transactions for a specific
period, set limit as 3 and offset as 0 in the first request. Then set limit as 3 and increment offset with
3 in the second request and repeat the request until all transactions are fetched.
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. You must specify offset with
any integer greater than or equal to 0. Use limit and offset together to set pagination on the response to
avoid returning a big dataset.
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. It's not the timestamp
when a card transaction or a purchase was made. For example, transactions in the merchant's
liquid account may take effect hours after card transactions or purchases take place.
example: "2022-03-01T12:42:10"
amount:
type: string
description: >
The amount of money of a transaction in the currency's smallest unit. For example,
300 with currency GBP is £3. Depending on the transaction and the transaction type, the amount
can be negative. One example for this is the PAYMENT transaction type in the case of a refund.
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. A payout is a deposit made to a merchant's
bank account or a PayPal Wallet for PayPal users. If the merchant's configuration has a minimum account balance,
then the payout will deposit the account balance minus the minimum account balance.
parameters:
- name: at
in: query
description: >
Used to fetch payouts at a certain point in time. The time is specified in UTC. If this parameter is used,
any transaction after that time will be ignored. If not, the account balance 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.
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
nextPayoutAmount:
description: >
The amount of money to be paid out to the merchant in the currency's smallest unit. For
example, 300 with currency GBP is £3.
type: integer
example: 2000
discountRemaining:
description: >
The amount of discounts that remain in merchant's vouchers in the currency's smallest unit.
The vouchers are offered by Zettle. For example, a merchant has a voucher worthy £100 from a
Zettle marketing campaign. For a transaction of £200, Zettle will subtract £2 as transaction fee
on the voucher. Then the merchant will have a remaining discount of £98, which would be
represented as 9800 in the response.
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