Wiki source code of 4. Invoice

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