Changes for page 4. Invoice

Last modified by David Persson on 2024/11/05 09:38
From empty
To version 183.1
edited by David Persson
on 2024/11/04 13:20
Change comment: There is no comment for this version

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +4. Invoice
Parent
... ... @@ -1,0 +1,1 @@
1 +developer:Main.Invoicing.invoice-service.invoice-service-apis.Technical reference.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +xwiki:XWiki.dap
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Tags
... ... @@ -1,0 +1,1 @@
1 +px-custom-page-content
Content
... ... @@ -1,0 +1,1079 @@
1 +(% class="jumbotron" %)
2 +(((
3 +(% class="container" %)
4 +(((
5 +Integrate to **PayEx Invoice API **
6 +)))
7 +)))
8 +
9 +(% id="HRoutesegments" %)
10 +== Introduction ==
11 +
12 +(% class="lead" %)
13 +This api is used to retrieve information related to the customer's invoices.
14 +
15 +[[image:1670584338716-116.png||height="815" width="406"]]
16 +
17 +
18 +PayEx supports HTTP headers for tracking that are used for troubleshooting purposes, implement according to [[specification>>https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/invoice-service/Technical%20reference/API/security/#HHTTPHeaders]]
19 +
20 +Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below
21 +
22 +The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
23 +//lf-api.payex.com/ledger/**{Subdomain}**/v1/**{LedgerNumber}**/resource1/**{resource1Id}**/resource2/**{resource2Id}**/resource3/**{resource3Id}**//
24 +
25 +(% class="table-bordered table-striped" %)
26 +|=(% style="width: 604px;" %)Route segment|=(% style="width: 2790px;" %)Description
27 +|(% style="width:604px" %)Subdomain|(% style="width:2790px" %)In this part of the API it will be invoice
28 +|(% style="width:604px" %)LedgerNumber|(% style="width:2790px" %)The ledger identifier/number at PayEx
29 +|(% style="width:604px" %)resource1Id|(% style="width:2790px" %)Identifier of resource1
30 +|(% style="width:604px" %)resource2Id|(% style="width:2790px" %)identifier of resource2, subresource to resource1
31 +|(% style="width:604px" %)resource3Id|(% style="width:2790px" %)identifier of resource3, subresource to resource2
32 +
33 +(% class="wikigeneratedid" %)
34 +Routes that occurs in examples of this documentation will use the following identifiers
35 +
36 +(% class="table-bordered table-striped" %)
37 +|=(% style="width: 330px;" %)Resource|=(% style="width: 1517px;" %)Identifier
38 +|(% style="width:330px" %)LedgerNumber|(% style="width:1517px" %)XXX
39 +|(% style="width:330px" %)Invoices|(% style="width:1517px" %)NNN (invoiceNo)
40 +|(% style="width:330px" %)Documents|(% style="width:1517px" %)YYY (type)
41 +
42 +== Implementation Guidelines ==
43 +
44 +To ensure optimal experience for end users, it is essential to follow these usage guidelines:
45 +
46 +* **Fetch only the invoice list initially: **Your initial API call should retrieve only the [[invoice list>>doc:||anchor="HInvoicelist"]], which provides sufficient information to display an overview of each customer’s invoices, both open and closed invoices.
47 +* **Request detailed invoice information only when necessary:** Make requests for individual [[invoice details>>doc:||anchor="HGetspecificinvoice"]] only when the end user explicitly chooses to view details for a specific invoice. Alternatively, if needed, you may limit the initial requests to retrieve the invoice list, including requests for details of only the open invoices, which typically amount to only 1-2
48 +* **Avoid frequent polling:** The API is not designed for regular polling of accounts receivable events (e.g., periodically checking the status of all invoices across all customers to see if any have been paid). Automated status checks, such as hourly polling, are unsupported and will degrade performance
49 +
50 +These guidelines apply to both front-end applications, such as web portals, and backend processes using the API. It is crucial to incorporate these requirements into your design to prevent excessive API calls and ensure a high-quality user experience.
51 +
52 +(% class="box infomessage" %)
53 +(((
54 +//If you have specific requirements that may deviate from these guidelines, please contact us to discuss potential options that could meet your needs.//
55 +)))
56 +
57 +== Invoice ==
58 +
59 +The **invoice **resource is located under **ledger/invoice/v1/ **api**. **This resource is used to get general information about existing invoices and its current state. Creation of new invoices is done through other resource.
60 +
61 +
62 +==== Get specific invoice ====
63 +
64 +==== ====
65 +
66 +{{code language="http" title="**Request**"}}
67 +GET /ledger/invoice/v1/XXX/invoices/NNN HTTP/1.1
68 +Host: -
69 +Authorization: Bearer <Token>
70 +Content-Type: application/json
71 +{{/code}}
72 +
73 +
74 +{{code language="http" title="**Response**"}}
75 +HTTP/1.1 200 OK
76 +Content-Type: application/json
77 +
78 +{
79 + "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
80 + "created" : "2019-05-06T00:00:00",
81 + "invoiceNo" : "12345",
82 + "externalInvoiceId" : "987654321",
83 + "status" : "pending|open|closed",
84 + "claimLevel" : "Invoice|RestReminder|Reminder|SecondReminder|CollectionClaim|DebtCollection",
85 + "currentDebt" : 463.42,
86 + "originalAmount" : 354.10,
87 + "currency" : "sek",
88 + "invoiceDate" : "2018-10-01T00:00:00",
89 + "dueDate" : "2018-10-01T00:00:00",
90 + "seller" : {
91 + "name" : "testshop",
92 + "number" : "12345"
93 + },
94 + "debt" : {
95 + "capital" : 354.10,
96 + "remiderFee" : 20.00,
97 + "collectionFee" : 80.00,
98 + "penaltyInterest" : 8.00,
99 + "calculatedPenaltyInterest" : 1.32
100 + },
101 + "penaltyInterestRate": 15.00,
102 + "bankPayment": {
103 + "bankAccountNo": "123",
104 + "bankAccountType": "BGSE",
105 + "bic": "123456",
106 + "iban": "SE12345678945631",
107 + "paymentReference": "54867165675646"
108 + },
109 + "customer" : "/ledger/customer/v1/customers/XYZABC",
110 + "transactions" : "/ledger/invoice/v1/XXX/invoices/12345/transactions",
111 + "activePaymentOrders": "/ledger/invoice/v1/XXX/invoices/NNN/active-payment-orders",
112 + "journal" : "/ledger/invoice/v1/XXX/invoices/12345/journal",
113 + "documents": "/ledger/invoice/v1/XXX/invoices/NNN/documents",
114 + "operations": [
115 + {
116 + "rel": "generate-invoice-portal-link",
117 + "method": "POST",
118 + "href": "/ledger/invoice/v1/XXX/invoices/NNN/generate-invoice-portal-link"
119 + },
120 + {
121 + "rel": "transfer-to-account",
122 + "method": "POST",
123 + "href": "/ledger/invoice/v1/XXX/invoices/NNN/transfer-to-account"
124 + }
125 + ],
126 +}
127 +{{/code}}
128 +
129 +==== Invoice list ====
130 +
131 +The **List Resource** offers an overview of each invoice on a specified customer with key details like InvoiceNo, status, amount, and due date. While it provides less information than a detailed invoice request, it includes the most important attributes for display purposes. Use this resource to minimize API calls and fetch detailed data only when needed.
132 +
133 +Use the querystring parameter "customerNo" to list invoices for a specific customer.
134 +
135 +
136 +{{code language="http" title="**Request**"}}
137 +GET /ledger/invoice/v1/XXX/invoices?customerNo=XYZABC HTTP/1.1
138 +Host: -
139 +Authorization: Bearer <Token>
140 +Content-Type: application/json
141 +{{/code}}
142 +
143 +
144 +{{code language="http" title="**Response**"}}
145 +HTTP/1.1 200 OK
146 +Content-Type: application/json
147 +
148 +{
149 + "items": [
150 + {
151 + "@id" : "/ledger/invoice/v1/XXX/invoices/12345",
152 + "invoiceNo" : "12345",
153 + "status" : "pending",
154 + "claimLevel" : "Invoice",
155 + "originalAmount" : 354.10,
156 + "currency" : "sek",
157 + "invoiceDate" : "2021-09-15T00:00:00",
158 + "dueDate" : "2021-10-01T00:00:00",
159 + "customerNo" : "XYZABC"
160 + },
161 + {
162 + "@id" : "/ledger/invoice/v1/XXX/invoices/987654",
163 + "invoiceNo" : "987654",
164 + "status" : "open",
165 + "claimLevel" : "Invoice",
166 + "originalAmount" : 122.00,
167 + "currency" : "sek",
168 + "invoiceDate" : "2021-09-15T00:00:00",
169 + "dueDate" : "2020-10-01T00:00:00",
170 + "customerNo" : "XYZABC"
171 + },
172 + {
173 + "@id" : "/ledger/invoice/v1/XXX/invoices/456321",
174 + "invoiceNo" : "456321",
175 + "status" : "closed",
176 + "claimLevel" : "Invoice",
177 + "originalAmount" : 846.50,
178 + "currency" : "sek",
179 + "invoiceDate" : "2021-09-15T00:00:00",
180 + "dueDate" : "2020-08-01T00:00:00",
181 + "customerNo" : "XYZABC"
182 + }
183 + ]
184 +}
185 +{{/code}}
186 +
187 +(% id="HAccountresourceproperties" %)
188 +==== Invoice resource properties ====
189 +
190 +
191 +(% class="table-bordered table-striped" %)
192 +|=Property|=Data type|=(% style="width: 117px;" %)Format|=Description
193 +|@id |string|(% style="width:117px" %)Maxlength: |Uri of the specific account
194 +|created|date|(% style="width:117px" %) |Date when the invoice was created in the system
195 +|invoiceNo|string|(% style="width:117px" %)Maxlength: 50|The identifier of the account
196 +|externalInvoiceId|string|(% style="width:117px" %)Maxlength: 50|External identifier of the invoice
197 +|status|string|(% style="width:117px" %)Maxlength: 25|Status of the invoice(((
198 +* **Pending**: the invoice has not been created yet, awaiting transactions
199 +* **Open**: the invoice is open and active
200 +* **Closed**: the invoice has been closed
201 +)))
202 +|claimLevel|string|Maxlength: 25|Current claim level of the invoice.(((
203 +* **Invoice:** This is the first state the invoice get when it is created, it will have this state until due date is passed (and possibly later depending on companys claim process configuration)
204 +* **RestReminder:** Reminder to pay remaining fees of the invoice (all capital has been payed) has been created/sent
205 +* **Reminder:** First reminder to pay invoice that has been past due date has been creted/sent
206 +* **SecondReminder:** Second reminder to pay invoice has been created/sent
207 +* **CollectionClaim:** Debt collection claim has been created/sent to the customer
208 +* **DebtCollection:** The invoice has been exported to other system for further handling of collection claims
209 +)))
210 +|currentDebt|decimal| |Total current debt of all balances (including capital / interest / fees, etc.). This value can be either positive or negative. (**positive value means it is a debt**)
211 +|originalAmount|decimal|(% style="width:117px" %) |The original debt amount stated on the invoice.
212 +|currency|string|(% style="width:117px" %)[[ISO 4217>>https://sv.wikipedia.org/wiki/ISO_4217]]|Currency of the invoice
213 +|invoiceDate|date|(% style="width:117px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Date when the invoice was created (printed on the invoice document)
214 +|dueDate|date|(% style="width:117px" %)[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Duedate of the invoice. This value does not exist for credit invoices
215 +|seller.name|string|(% style="width:117px" %) |Name of the seller related to the invoice
216 +|seller.number|string|(% style="width:117px" %) |The identifier of the seller
217 +|debt|object|(% style="width:117px" %) |Current debt of the invoices separated in the different debt types
218 +| debt.capital|decimal|(% style="width:117px" %) |This value only exists if there is any capital amount
219 +| debt.reminderFee|decimal|(% style="width:117px" %) |This value only exists if there is any reminder fee //(also includes businessRemiderFee)//
220 +| debt.collectionFee|decimal|(% style="width:117px" %) |This value only exists if there is any collection fee
221 +| debt.penaltyInterest|decimal|(% style="width:117px" %) |This value only exists if there is any penalty interest
222 +| debt.calculatedPenaltyInterest|decimal|(% style="width:117px" %) |Todays pending calculated penalty interest. Will be valid if a payment is made today.
223 +This value only exists if there is any calculated penalty interest.
224 +|penaltyInterestRate|decimal|(% style="width:117px" %)Percentage|yearly penalty interestrate (optional)
225 +|bankPayment|object|(% style="width:117px" %) |optional. This object is only visible if the invoice is ready to be paid. Does not exists for invoices with status "closed", or for creditinvoices
226 +| bankPayment.bankAccountNo|string|(% style="width:117px" %)Maxlength: 15|bankaccount for payment
227 +| bankPayment.bankAccountType|string|(% style="width:117px" %)Maxlength: 10|BankAccountTypes:(((
228 +* BKSE (swedish bank account)
229 +* PKSE (swedish plusgiro)
230 +* BGSE (swedish bankgiro)
231 +* PGSE (swedish plusgiro OCR)
232 +* BKNO (norwegian bank account)
233 +* BKDK (danish bank account)
234 +)))
235 +| bankPayment.bic|string|(% style="width:117px" %)Maxlength: 11|Bank Identifier Code (BIC)
236 +| bankPayment.iban|string|(% style="width:117px" %)Maxlength: 34|International Bank Account Number (IBAN)
237 +| bankPayment.paymentReference|string|(% style="width:117px" %)Maxlength: 50|(((
238 +reference to specify on the payment
239 +)))
240 +|customer|string|(% style="width:117px" %)Uri|Uri to the customer resource related to the invoice
241 +|transactions|string|(% style="width:117px" %)Uri|List all transactions that has occured on the invoice
242 +|activePaymentOrders|string|(% style="width:117px" %)Uri|View scheduled payment orders
243 +|journal|string|(% style="width:117px" %)Uri|Lists events that has occured on the invoice
244 +|documents|string|(% style="width:117px" %)Uri|View the actual invoice document (and other related documents), how it has been distributed etc.
245 +
246 +(% id="HDocuments" %)
247 +== Documents ==
248 +
249 +The documents resources contains basic info of each invoice, reminder, letters etc. that has been produced related to the invoice. It also includes a url to download the actual document.
250 +
251 +
252 +(% id="HListallbillsofanaccount" %)
253 +==== List all documents of an invoice ====
254 +
255 +{{code language="http" title="**Request**"}}
256 +GET /ledger/invoice/v1/XXX/invoices/NNN/documents HTTP/1.1
257 +Host: -
258 +Authorization: Bearer <Token>
259 +Content-Type: application/json
260 +
261 +{{/code}}
262 +
263 +
264 +{{code language="http" title="**Response**"}}
265 +HTTP/1.1 200 OK
266 +Content-Type: application/json
267 +
268 +{
269 + "@id": "/ledger/invoice/v1/501/invoices/NNN/documents",
270 + "items" : [
271 + {
272 + "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/852147",
273 + "date": "2018-11-15T00:00:00",
274 + "type" : "invoice",
275 + "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
276 + "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/852147/document"
277 + },
278 + {
279 + "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123654",
280 + "date": "2018-11-15T00:00:00",
281 + "type" : "reminder",
282 + "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
283 + "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123654/document"
284 + }
285 + ]
286 +}
287 +{{/code}}
288 +
289 +(% id="H-1" %)
290 +==== ====
291 +
292 +(% id="HGetspecificbill" %)
293 +==== Get specific document ====
294 +
295 +{{code language="http" title="**Request**"}}
296 +GET /ledger/invoice/v1/XXX/invoices/NNN/documents/YYY HTTP/1.1
297 +Host: -
298 +Authorization: Bearer <Token>
299 +Content-Type: application/json
300 +
301 +{{/code}}
302 +
303 +
304 +{{code language="http" title="**Response**"}}
305 +HTTP/1.1 200 OK
306 +Content-Type: application/json
307 +
308 +{
309 + "@id": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123645",
310 + "date": "2018-11-15T00:00:00",
311 + "type" : "reminder",
312 + "distributionMethod" : "NotDistributed|Postal|Kivra|EInvoice|EMail",
313 + "document": "/ledger/invoice/v1/XXX/invoices/NNN/documents/123645/document"
314 +}
315 +{{/code}}
316 +
317 +(% id="HBillresourceproperties" %)
318 +==== Document resource properties ====
319 +
320 +(% class="table-bordered table-striped" %)
321 +|=Property|=Data type|=Format|=Description
322 +|@id|string|Uri|
323 +|date|date|[[ISO 8601>>url:http://en.wikipedia.org/wiki/ISO_8601||rel="noreferrer" title="ISO8601 on Wikipedia"]]|Date when the document was created
324 +|type|string| |(((
325 +Currently available types of document
326 +
327 +* **Invoice **- the actual invoice
328 +* **Reminder **- reminder of the invoice
329 +* **RestReminder **- reminder of rest amounts
330 +* **Collection **- Collection claim of the invoice
331 +* **CreditInvoice**
332 +* **BillAttachmentTypeName**
333 +** **SA **(summary)
334 +** **SSA **(Consolidated Summary)
335 +** **SP **(Specification)
336 +)))
337 +|distributionMethod|string| |(((
338 +* **NotDistributed **- the letter has been created but not distributed
339 +* **Postal **- Distributed through usual post
340 +* **Kivra **- Digitally distributed through Kivra
341 +* **EInvoice **- Digitally distributed through EInvoice
342 +* **EMail **- Digitally distributed through email
343 +)))
344 +|document|string|Uri|Uri to download the actual document, usually pdf (content type in response).
345 +
346 +== Transactions ==
347 +
348 +This resource lists all transactions that has occured on the invoice. The resource does not support "GET" on individual transactions, only listing of all transactions.
349 +Property "typeName" is ment to be displayed directly "as is" in a customer portal, it is translated to a readable text in the language configured on the current company.
350 +
351 +
352 +(% id="HListallbillsofanaccount" %)
353 +==== List all transactions that has occured on an invoice ====
354 +
355 +
356 +{{code language="http" title="**Request**"}}
357 +GET /ledger/invoice/v1/XXX/invoices/NNN/transactions HTTP/1.1
358 +Host: -
359 +Authorization: Bearer <Token>
360 +Content-Type: application/json
361 +
362 +{{/code}}
363 +
364 +
365 +{{code language="http" title="**Response**"}}
366 +HTTP/1.1 200 OK
367 +Content-Type: application/json
368 +
369 +{
370 + "@id": "/ledger/invoice/v1/501/invoices/NNN/transactions",
371 + "items" : [
372 + {
373 + "type": "disbursement",
374 + "typeName": "Utbetalningsuppdrag skapat",
375 + "reference": "",
376 + "amount": 50.00,
377 + "date": "2019-11-09T00:00:00"
378 + },
379 + {
380 + "type": "payment",
381 + "typeName": "Betalning",
382 + "reference": "",
383 + "amount": -100.00,
384 + "date": "2019-11-09T00:00:00"
385 + },
386 + {
387 + "type": "credit",
388 + "typeName": "Kreditering",
389 + "reference": "",
390 + "amount": -100.00,
391 + "date": "2019-11-02T00:00:00",
392 + "cause" : {
393 + "type": "bankruptcy",
394 + "typeName": "Konkurs"
395 + }
396 + },
397 + {
398 + "type": "credit",
399 + "typeName": "Kreditering",
400 + "reference": "korrigering dröjsmålsränta",
401 + "amount": -00.85,
402 + "date": "2019-11-02T00:00:00",
403 + "cause" : {
404 + "type": "remission",
405 + "typeName": "Efterskänkes"
406 + }
407 + },
408 + {
409 + "type": "credit",
410 + "typeName": "Kreditering",
411 + "reference": "reglering mot kreditfaktura NNN",
412 + "amount": -100.00,
413 + "date": "2019-11-02T00:00:00",
414 + },
415 + {
416 + "type": "collectionFee",
417 + "typeName": "Inkassoavgift",
418 + "reference": "",
419 + "amount": 180.00,
420 + "date": "2019-11-02T00:00:00",
421 + },
422 + {
423 + "type": "reminderFee",
424 + "typeName": "Påminnelseavgift",
425 + "reference": "",
426 + "amount": 30.00,
427 + "date": "2019-11-02T00:00:00",
428 + },
429 + {
430 + "type": "interest",
431 + "typeName": "ränta",
432 + "reference": "",
433 + "amount": 2.00,
434 + "date": "2019-11-02T00:00:00",
435 + },
436 + {
437 + "type": "invoice",
438 + "typeName": "Faktura",
439 + "reference": "butiksnamn, Orderref. 345",
440 + "amount": 200.00,
441 + "date": "2020-10-09T00:00:00"
442 + }
443 + ]
444 +}
445 +{{/code}}
446 +
447 +(% id="H-1" %)
448 +==== ====
449 +
450 +(% id="HGetspecificbill" %)
451 +==== Transaction resource properties ====
452 +
453 +(% class="table-bordered table-striped" %)
454 +|=(% style="width: 405px;" %)Property|=(% style="width: 129px;" %)Data type|=(% style="width: 1236px;" %)Description
455 +|(% style="width:405px" %)@id|(% style="width:129px" %)string|(% style="width:1236px" %)
456 +|(% style="width:405px" %)type|(% style="width:129px" %)string|(% style="width:1236px" %)Type of transaction
457 +|(% style="width:405px" %)typeName|(% style="width:129px" %)string|(% style="width:1236px" %)(((
458 +The type of transaction in form of a readable translated text (the local language of the current company)
459 +
460 +The following types can occur on a invoice
461 +
462 +* Invoice //(the transaction that is the basis for the invoice)//
463 +* CreditInvoice// (the transaction that is the basis for the credit invoice)//
464 +* Credit// (credited amount)//
465 +* Interest
466 +* Payment
467 +* Disbursement //(If, for example, a surplus occur on the invoice, it can be paid out)//
468 +* DisbursementReturned //(amount that failed to be paid out for any reason is returned on the invoice)//
469 +* InvoiceFee
470 +* ReminderFee
471 +* CollectionFee
472 +* BadDebt// (BadCapital is an expected loss that may be reclaimed if debt monitoring results in a payment from the customer)//
473 +* Converted //(only available by agreement with PayEx)//
474 +)))
475 +|(% style="width:405px" %)reference|(% style="width:129px" %)string|(% style="width:1236px" %)Transaction reference
476 +|(% style="width:405px" %)amount|(% style="width:129px" %)decimal|(% style="width:1236px" %)Amount ot the transaction
477 +|(% style="width:405px" %)date|(% style="width:129px" %)date|(% style="width:1236px" %)Date when the transaction occured
478 +|(% style="width:405px" %)cause|(% style="width:129px" %)object|(% style="width:1236px" %)This object is available when there is a specific cause to why the transaction has occured
479 +|(% style="width:405px" %) cause.type|(% style="width:129px" %)string|(% style="width:1236px" %)Type of cause to why the transaction has occured
480 +|(% style="width:405px" %) cause.typeName|(% style="width:129px" %)string|(% style="width:1236px" %)The type of cause in form of a readable translated text (in the local language of the current company)
481 +
482 +== Active payment orders ==
483 +
484 +This resource corresponds to an active / scheduled payment order placed against the specific account, the end-customer will be debited at the given executeDate.
485 +
486 +(% id="HGetactivepaymentordersforanaccount" %)
487 +====
488 +Get active payment orders for an account ====
489 +
490 +
491 +{{code language="http" title="**Request**"}}
492 +GET /ledger/invoice/v1/XXX/invoices/NNN/active-payment-orders/ HTTP/1.1
493 +Host: -
494 +Authorization: Bearer <Token>
495 +Content-Type: application/json
496 +{{/code}}
497 +
498 +
499 +{{code language="http" title="**Response**"}}
500 +HTTP/1.1 200 OK
501 +Content-Type: application/json
502 +
503 +{
504 + "operations": null,
505 + "items": [
506 + {
507 + "paymentMethod": "autogiro",
508 + "executeDate": "2020-02-15",
509 + "amount": 200.00
510 + }
511 + ]
512 +}
513 +{{/code}}
514 +
515 +(% id="H-2" %)
516 +==== ====
517 +
518 +(% id="HActive-payment-ordersresourceproperties" %)
519 +==== Active-payment-orders resource properties ====
520 +
521 +(% class="table-bordered table-striped" %)
522 +|=Property|=Data type|=Description
523 +|paymentMethod|string|paymentMethods:(((
524 +* autogiro
525 +)))
526 +|executeDate|Date|(((
527 +The date when the customers bankaccount will be charged
528 +)))
529 +|amount|decimal|The amount that will be withdrawn from the bankaccount
530 +
531 +(% id="HJournal" %)
532 +== Journal ==
533 +
534 +This resource lists all events that has occured on the invoice, in a sorted timeline.
535 +
536 +(% id="HGetactivepaymentordersforanaccount" %)
537 +====
538 +Get journal entries for the invoice ====
539 +
540 +
541 +{{code language="http" title="**Request**"}}
542 +GET /ledger/invoice/v1/XXX/invoices/NNN/journal/ HTTP/1.1
543 +Host: -
544 +Authorization: Bearer <Token>
545 +Content-Type: application/json
546 +{{/code}}
547 +
548 +
549 +{{code language="http" title="**Response**"}}
550 +HTTP/1.1 200 OK
551 +Content-Type: application/json
552 +
553 +{
554 + "operations": null,
555 + "items": [
556 + {
557 + "type": "ComplaintReceived",
558 + "date" : "2020-09-01T00:00:00",
559 + "description" : ""
560 + },
561 + {
562 + "type": "SecondReminderSent",
563 + "date" : "2020-09-01T00:00:00",
564 + "description" : ""
565 + },
566 + {
567 + "type": "ReminderSent",
568 + "date" : "2020-09-01T00:00:00",
569 + "description" : ""
570 + }
571 + ],
572 + "view": {
573 + "@id": "/ledger/invoice/v1/XXX/invoices/NNN/journal?$top=2&$skip=0",
574 + "next": "/ledger/invoice/v1/XXX/invoices/NNN/journal?$top=2&$skip=2"
575 + }
576 +}
577 +{{/code}}
578 +
579 +(% id="H-2" %)
580 +==== ====
581 +
582 +(% id="HActive-payment-ordersresourceproperties" %)
583 +==== Journal resource properties ====
584 +
585 +(% class="table-bordered table-striped" %)
586 +|=Property|=Data type|=Description
587 +|type|string|type:(((
588 +* **ReminderSent **//(an invoice reminder has been sent to the customer)//
589 +* **SecondReminderSent **//(a second invoice reminder has been sent to the customer)//
590 +* **CollectionClaimSent **//(a collection claim has been sent to the customer)//
591 +* **RestReminderSent **//(a reminder including only interest and fees has been sent to the customer)//
592 +* **DebtCollection **//(the invoice has been transferred to collection)//
593 +* **Respite// //**//(the claim is stopped for further claimprocess steps until valid to data of respite or respite is removed)//
594 +* **RespiteRemoved** //(respite has been removed fro claim)//
595 +* **Stop// //**//(the claim is stopped for further claim process steps until stop is removed)//
596 +* **StopRemoved **//(stop has been removed from claim)//
597 +* **ComplaintReceived// //**//(complaint has been registered)//
598 +* **ComplaintResolved **//(complaint has been resolved)//
599 +* **InvoiceClosed **//(status of the invoice in the accounts receivable has been set to closed)//
600 +* **PaymentOrderFailed **//(scheduled paymentorder failed to be executed)//
601 +)))
602 +|date|Date|(((
603 +The date when the journal entry occured
604 +)))
605 +|description|string|detailed description of the entry (if available)
606 +
607 +== Register direct payment ==
608 +
609 +operation for registration of direct payments against invoices
610 +
611 +{{code language="http" title="**Request**"}}
612 +POST /ledger/invoice/v1/XXX/invoices/NNN/register-direct-payment HTTP/1.1
613 +Host: -
614 +Authorization: Bearer <Token>
615 +Content-Type: application/json
616 +
617 +{
618 + "amount" : 100.00,
619 + "paymentDate" : "2021-04-27",
620 + "transactionCause" : "psp"
621 +}
622 +{{/code}}
623 +
624 +(% id="HActive-payment-ordersresourceproperties" %)
625 +==== Register-direct-payment request properties ====
626 +
627 +(% class="table-bordered table-striped" %)
628 +|=Property|=Data type|=Required|=Description
629 +|amount|decimal|Yes|The amount of the direct payment
630 +|paymentDate|Date|Yes|(((
631 +The date when the payment was made
632 +)))
633 +|transactionCause|string|No|(((
634 +* psp
635 +)))
636 +
637 +{{code language="http" title="**Response**"}}
638 +HTTP/1.1 204 NO CONTENT
639 +Content-Type: application/json
640 +
641 +{{/code}}
642 +
643 +== Settle-credit-invoice ==
644 +
645 +operation to settle an existing credit invoice towards debit invoice. This operation is only be available/valid on credit-invoices
646 +
647 +{{code language="http" title="**Request**"}}
648 +POST /ledger/invoice/v1/XXX/invoices/NNN/settle-credit-invoice HTTP/1.1
649 +Host: -
650 +Authorization: Bearer <Token>
651 +Content-Type: application/json
652 +
653 +{
654 + "debitInvoiceNo": "12345",
655 + "creditAmount": 250.00,
656 + "sendCopy": false
657 +}
658 +{{/code}}
659 +
660 +(% id="HActive-payment-ordersresourceproperties" %)
661 +==== Settle-credit-invoice request properties ====
662 +
663 +(% class="table-bordered table-striped" %)
664 +|=Property|=Data type|=Required|=Description
665 +|debitInvoiceNo|string|Yes|invoice number of the debit invoice that the credit invoice is to be settled against
666 +|creditAmount|decimal|Yes|(((
667 +Amount of the credit invoice to use
668 +)))
669 +|sendCopy|bool|No|Whether a new copy should be distributed to the end-customer with updated balances (after settlement has been executed)
670 +Default false
671 +
672 +{{code language="http" title="**Response**"}}
673 +HTTP/1.1 204 NO CONTENT
674 +Content-Type: application/json
675 +
676 +{{/code}}
677 +
678 +== Remission ==
679 +
680 +operation to allow partialy remission of the debt. Usually used if there is a small debt left on the invoice after a payment hade been done, and the remaining amount should be offered.
681 +
682 +{{code language="http" title="**Request**"}}
683 +POST /ledger/invoice/v1/XXX/invoices/NNN/remission HTTP/1.1
684 +Host: -
685 +Authorization: Bearer <Token>
686 +Content-Type: application/json
687 +
688 +{
689 + "balanceType": "CollectionFee",
690 + "amount": 12.00,
691 + "invoiceCurrentDebt": 12.00
692 +}
693 +{{/code}}
694 +
695 +(% id="HActive-payment-ordersresourceproperties" %)
696 +==== remission request properties ====
697 +
698 +(% class="table-bordered table-striped" %)
699 +|=Property|=Data type|=Required|=Description
700 +|balanceType|string|Yes|(((
701 +The balanceType to be affected
702 +
703 +* capital
704 +* reminderfee
705 +* penaltyinterest
706 +* collectionfee
707 +)))
708 +|amount|decimal|Yes|The amount of the specified balace type to exeute remission on
709 +|invoiceCurrentDebt|decimal|Yes|The amount must match the current debt (**excl. Calculated interest**) on the invoice.
710 +currentDebt - debt.calculatedPenaltyInterest
711 +
712 +{{code language="http" title="**Response**"}}
713 +HTTP/1.1 204 NO CONTENT
714 +Content-Type: application/json
715 +
716 +{{/code}}
717 +
718 +== Write-down ==
719 +
720 +operation to allow partialy or full write-down of the debt. the reason/cause of the write-down should be specified (affects accounting)
721 +
722 +{{code language="http" title="**Request**"}}
723 +POST /ledger/invoice/v1/XXX/invoices/NNN/write-down HTTP/1.1
724 +Host: -
725 +Authorization: Bearer <Token>
726 +Content-Type: application/json
727 +
728 +{
729 + "balanceType": "CollectionFee",
730 + "amount": 12.00,
731 + "cause": "deceased",
732 + "invoiceCurrentDebt": 462.10
733 +}
734 +{{/code}}
735 +
736 +(% id="HActive-payment-ordersresourceproperties" %)
737 +==== Write-down request properties ====
738 +
739 +(% class="table-bordered table-striped" %)
740 +|=Property|=Data type|=Required|=Description
741 +|balanceType|string|Yes|(((
742 +The balanceType to be affected
743 +
744 +* Capital
745 +* ReminderFee
746 +* PenaltyInterest
747 +* CollectionFee
748 +)))
749 +|amount|decimal|Yes|The amount of the specified balace type to write-down
750 +|cause|string|Yes|(((
751 +The cause of the write-down
752 +
753 +* Bankruptcy
754 +* Settlement
755 +* Deceased
756 +* Fraud
757 +* Dispute
758 +* NonDeductible
759 +* Unknown
760 +
761 +If field is null, Then defaults to "Unknown". Case-Sensitive
762 +)))
763 +|{{{invoiceCurrentDebt}}}|decimal|Yes|The amount must match the current debt (**excl. Calculated interest**) on the invoice.
764 +currentDebt - debt.calculatedPenaltyInterest
765 +
766 +{{code language="http" title="**Response**"}}
767 +HTTP/1.1 204 NO CONTENT
768 +Content-Type: application/json
769 +
770 +{{/code}}
771 +
772 +== Respite ==
773 +
774 +Resource to create or view respite
775 +
776 +Get respite
777 +
778 +{{code language="http" title="**Request**"}}
779 +GET /ledger/invoice/v1/XXX/invoices/NNN/respite HTTP/1.1
780 +Host: -
781 +Authorization: Bearer <Token>
782 +Content-Type: application/json
783 +
784 +{{/code}}
785 +
786 +{{code language="http" title="**Response**"}}
787 +HTTP/1.1 200 OK
788 +Content-Type: application/json
789 +
790 +{
791 + "validToDate": "2021-08-01",
792 + "reason": "..."
793 +}
794 +{{/code}}
795 +
796 +Create respite
797 +
798 +{{code language="http" title="**Request**"}}
799 +POST /ledger/invoice/v1/XXX/invoices/NNN/respite HTTP/1.1
800 +Host: -
801 +Authorization: Bearer <Token>
802 +Content-Type: application/json
803 +
804 +{
805 + "validToDate": "2021-08-01",
806 + "reason": "..."
807 +}
808 +{{/code}}
809 +
810 +{{code language="http" title="**Response**"}}
811 +HTTP/1.1 201 CREATED
812 +Content-Type: application/json
813 +{{/code}}
814 +
815 +(% id="HActive-payment-ordersresourceproperties" %)
816 +==== Respite request properties ====
817 +
818 +(% class="table-bordered table-striped" %)
819 +|=Property|=Data type|=Required|=Description
820 +|validToDate|Date|Yes|Respite is valid to this date
821 +|reason|string|Yes|Reason for why the respite was created.
822 +
823 +== Active-disbursement-orders ==
824 +
825 +View or create disbursement orders, only available for credit-invoices
826 +
827 +Get active-disbursement-orders
828 +
829 +{{code language="http" title="**Request**"}}
830 +GET /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
831 +Host: -
832 +Authorization: Bearer <Token>
833 +Content-Type: application/json
834 +
835 +{{/code}}
836 +
837 +{{code language="http" title="**Response**"}}
838 +HTTP/1.1 200 OK
839 +Content-Type: application/json
840 +
841 +{
842 + "items" :
843 + [
844 + {
845 + "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456789",
846 + "amount" : 10,
847 + "norwegianBankAccount" : {
848 + "accountNo" : "1234"
849 + }
850 + },
851 + {
852 + "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456788",
853 + "amount" : 10,
854 + "international" : {
855 + "iban" : "123456",
856 + "bic" : "SWED..."
857 + }
858 + },
859 + {
860 + "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456787",
861 + "amount" : 10,
862 + "swedishBankAccount" : {
863 + "accountNo" : "123",
864 + "accountType" : "BKSE | PGSE | BGSE"
865 + }
866 + },
867 + {
868 + "@id" : "../ledger/v1/501/invoices/12345/active-disbursement-orders/456786",
869 + "amount" : 10,
870 + "swedishSus" : {
871 + "nationalIdentifier": {
872 + "regNo" : "YYYYMMDD-NNNN",
873 + "countryCode" : "SE"
874 + },
875 + "address" : {
876 + "addressee" : "Kalle Axelstopp",
877 + "streetAddress" : "Axelgatan 18",
878 + "coAddress" : null,
879 + "city" : "STOCKHOLM",
880 + "zipCode" : "16872",
881 + "countryCode" : "se"
882 + }
883 + }
884 + }
885 + ]
886 +}
887 +{{/code}}
888 +
889 +Create disbursement order towards a norwegian bank account
890 +
891 +{{code language="http" title="**Request**"}}
892 +POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
893 +Host: -
894 +Authorization: Bearer <Token>
895 +Content-Type: application/json
896 +
897 +{
898 + "amount" : 10,
899 + "norwegianBankAccount" : {
900 + "accountNo" : "1234"
901 + }
902 +}
903 +{{/code}}
904 +
905 +Create disbursement order towards a international bank account (IBAN)
906 +
907 +{{code language="http" title="**Request**"}}
908 +POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
909 +Host: -
910 +Authorization: Bearer <Token>
911 +Content-Type: application/json
912 +
913 +{
914 + "amount" : 10,
915 + "international" : {
916 + "iban" : "123456",
917 + "bic" : "SWED..."
918 + }
919 +}
920 +{{/code}}
921 +
922 +Create disbursement order towards a swedish bank account
923 +
924 +{{code language="http" title="**Request**"}}
925 +POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
926 +Host: -
927 +Authorization: Bearer <Token>
928 +Content-Type: application/json
929 +
930 +{
931 + "amount" : 100,
932 + "swedishBankAccount" : {
933 + "accountNo" : "123",
934 + "accountType" : "BKSE | PGSE | BGSE"
935 + }
936 +}
937 +{{/code}}
938 +
939 +Create disbursement order using "Swedbanks lön- och utbetalningssystem (SUS)"
940 +
941 +{{code language="http" title="**Request**"}}
942 +POST /ledger/invoice/v1/XXX/invoices/NNN/active-disbursement-orders HTTP/1.1
943 +Host: -
944 +Authorization: Bearer <Token>
945 +Content-Type: application/json
946 +
947 +{
948 + "amount" : 100,
949 + "swedishSus" : {
950 + "nationalIdentifier": {
951 + "regNo" : "YYYYMMDD-NNNN",
952 + "countryCode" : "SE"
953 + },
954 + "address" : {
955 + "addressee" : "Kalle Axelstopp",
956 + "streetAddress" : "Axelgatan 18",
957 + "coAddress" : null,
958 + "city" : "STOCKHOLM",
959 + "zipCode" : "16872",
960 + "countryCode" : "se",
961 + }
962 + }
963 +}
964 +{{/code}}
965 +
966 +
967 +{{code language="http" title="**Response**"}}
968 +HTTP/1.1 201 CREATED
969 +Content-Type: application/json
970 +{{/code}}
971 +
972 +(% id="HActive-payment-ordersresourceproperties" %)
973 +==== Respite request properties ====
974 +
975 +(% class="table-bordered table-striped" %)
976 +|=Property|=Data type|=Required|=Description
977 +|amount|decimal|Yes|
978 +|__**norwegianBankAccount**__|object|No*|
979 +| accountNo|string|Yes|
980 +|__**swedishBankAccount**__|object|No*|
981 +| clearingNo|string|Yes|
982 +| accountNo|string|Yes|
983 +|__**international**__|object|No*|
984 +| iban|string|Yes|
985 +| bic|string|Yes|
986 +|__**swedishSus**__|object|No*|
987 +|**nationalIdentifier**|object|Yes|
988 +| regNo|string|Yes|
989 +| countryCode|string|Yes|
990 +|**address**|object|Yes|
991 +| addressee|string|Yes|
992 +| streetAddress|string|No|
993 +| coAddress|string|No|
994 +| city|string|Yes|
995 +| zipCode|string|Yes|
996 +| countryCode|string|Yes|
997 +| | | |
998 +
999 +//* One and only one of the specified objects can be set at each request//
1000 +
1001 +== Transfer-to-account ==
1002 +
1003 +operation transfer current capital debt on the invoice to a provided account. This will close the invoice.
1004 +
1005 +{{code language="http" title="**Request**"}}
1006 +POST /ledger/invoice/v1/XXX/invoices/NNN/transfer-to-account HTTP/1.1
1007 +Host: -
1008 +Authorization: Bearer <Token>
1009 +Content-Type: application/json
1010 +
1011 +{
1012 + "accountNo" : "123",
1013 +
1014 +}
1015 +
1016 +{{/code}}
1017 +
1018 +(% id="HActive-payment-ordersresourceproperties" %)
1019 +==== Transfer-to-account request properties ====
1020 +
1021 +(% class="table-bordered table-striped" %)
1022 +|=Property|=Data type|=Required|=Description
1023 +|accountNo|string|Yes|account number to the to transfer current capital debt into
1024 +
1025 +{{code language="http" title="**Response**"}}
1026 +HTTP/1.1 204 NO CONTENT
1027 +Content-Type: application/json
1028 +
1029 +{{/code}}
1030 +
1031 +== ==
1032 +
1033 +== Generate-invoice-portal-link ==
1034 +
1035 +Creates a new public available (no authorization needed) link to the targeted invoice. Default lifetime of a link is 120 days. Creating new links does not affect old links.
1036 +
1037 +{{code language="http" title="**Request**"}}
1038 +POST /ledger/invoice/v1/XXX/invoices/NNN/generate-invoice-portal-link HTTP/1.1
1039 +Host: -
1040 +Authorization: Bearer <Token>
1041 +Content-Type: application/json
1042 +
1043 +{
1044 +}
1045 +
1046 +{{/code}}
1047 +
1048 +(% id="HActive-payment-ordersresourceproperties" %)
1049 +==== ====
1050 +
1051 +{{code language="http" title="**Response**"}}
1052 +HTTP/1.1 200 OK
1053 +Content-Type: application/json
1054 +
1055 +{
1056 + "invoicePortalLink": "https://public-invoice-example.com/sv/XXX?token=eyJhbGciOiJSUzI1Ni..."
1057 +}
1058 +{{/code}}
1059 +
1060 +{{display reference="developer:Main.Invoicing.ledger-api-general-docs.api-section-problems.WebHome"/}}
1061 +
1062 +=== Problem types ===
1063 +
1064 +(% class="box infomessage" %)
1065 +(((
1066 +Note, each problem typecode is preceded by "ledger/invoice/v1/problems/" in this API, e.g. the error "validation" in the table below will appear as typecode "ledger/invoice/v1/problems/validation".
1067 +)))
1068 +
1069 +(% class="table-bordered table-striped" %)
1070 +|=(% style="width: 537px;" %)Problem type (code)|=(% style="width: 172px;" %)Httpstatus|=(% style="width: 796px;" %)Description
1071 +|(% style="width:537px" %)forbidden|(% style="width:172px" %)403|(% style="width:796px" %)occurs if access to method is not allowed.
1072 +|(% style="width:537px" %)customer-not-found|(% style="width:172px" %)404|(% style="width:796px" %)can occur if customernumber is part of the querystring towards invoice resource
1073 +|(% style="width:537px" %)invoice-not-found|(% style="width:172px" %)404|(% style="width:796px" %)
1074 +|(% style="width:537px" %)missing-offer|(% style="width:172px" %)409|(% style="width:796px" %)Invoice is not a candidate for **transfer-to-account**. This has nothing to do with the provided Account
1075 +|(% style="width:537px" %)missing-account-for-billing-account|(% style="width:172px" %)409|(% style="width:796px" %)No account found on the provided AccountNo, can be expected on the us of **transfer-to-account** operation
1076 +|(% style="width:537px" %)not-acceptable-for-conversion|(% style="width:172px" %)409|(% style="width:796px" %)Invoice or account was not acceptable for transfer. This could be caused a number of parameters both on the invoice and the account.
1077 +|(% style="width:537px" %)credit-check-rejected|(% style="width:172px" %)422|(% style="width:796px" %)Score does not approve the conversion
1078 +|(% style="width:537px" %)customer-mismatch|(% style="width:172px" %)422|(% style="width:796px" %)Invoice and account is on separate customers in the **transfer-to-account** request
1079 +|(% style="width:537px" %) |(% style="width:172px" %) |(% style="width:796px" %)
1602850855982-540.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1603272734121-573.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1611132614793-633.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1611132645651-800.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1615145255456-449.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1617094783353-392.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1619519632632-939.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content
1670584338716-116.png
Author
... ... @@ -1,0 +1,1 @@
1 +xwiki:XWiki.dap
Size
... ... @@ -1,0 +1,1 @@
1 +0 bytes
Content