Wiki source code of Invoice Service

Last modified by Fredrik Köhler on 2018/12/07 12:59
Show last authors
1 {{error}}
2 **Disclaimer:** The Invoice Service documentation is incomplete. Please beware that the information given here is subject to change at any time, that information might be missing and even be incorrect. Use with caution!
3 {{/error}}
4
5 = Introduction =
6
7 PayEx CUSIN is a file format for customers to send customer and invoice information to PayEx. The documentation targets technical system integrators and developers implementing PayEx Invoice Service.
8
9 Invoice Service includes
10
11 * Invoicing
12 * Accounts Receivable
13 * Distribution
14 * Collection
15
16 Supporting the following features
17
18 * Accounting
19 * Reports & statistics
20 * PayEx 360 (web based interface)
21 * PayEx Connect (API)
22
23 = What you need before you get started =
24
25 * sFTP Client
26 * Agreement that includes PayEx Invoice Service (CUSIN)
27 * Obtained credentials from PayEx
28 * Basic understanding of file name convention and file format limitations
29
30 To get a grasp of what we expect of your implementation when you are finished, we recommend that you take a peek at the following diagram before you get started.
31
32 {{plantuml}}
33 @startuml
34 skinparam sequence{
35 ArrowColor #2DA944
36 ActorFontColor #333333
37 ActorFontStyle bold
38 ActorFontSize 15
39 ActorBackgroundColor #fefefe
40 ActorBorderColor #2DA944
41 LifeLineBorderColor #999999
42 LifeLineBackgroundColor #dddddd
43 ParticipantBorderColor #2DA944
44 ParticipantBackgroundColor #ffffff
45 ParticipantFontColor #333333
46 ParticipantFontStyle bold
47 }
48 skinparam Roundcorner 10
49 skinparam Shadowing false
50 skinparam ActivityBorderColor #123123
51 skinparam NoteBackgroundColor white
52 skinparam NoteBorderColor #999999
53 skinparam NoteFontColor #333333
54 skinparam sequenceDividerBackgroundColor white
55 skinparam sequenceDividerBorderColor #999999
56 skinparam sequenceDividerFontStyle bold
57 skinparam sequenceDividerFontSize 15
58 '//Sequence start//'
59 |||
60 Consumer->Customer: Purchase service/product: payment method Invoice
61 |||
62 Activate Consumer
63 ==Step1 CreateCUSINfile==
64 Activate Customer
65 Activate PayEx
66 Customer->PayEx: Create <Cusin>
67 PayEx->Customer: Receive <Receipt>
68 PayEx->Customer: Receive <Errorlog>
69 Deactivate Customer
70 PayEx->Consumer: Distribute <Invoice>]
71 |||
72 Deactivate Consumer
73 hnote over Customer: Invoice gets closed or continues in claim process
74 |||
75 == Step 2: Response Files==
76 PayEx->Customer: Receive <Bill Journal>
77 Activate Customer
78 PayEx->Customer: Receive <Customer Journal>
79 |||
80 ==Step 3: Accounting and Disbursement==
81 PayEx->Customer: Receive <Accounting Detail>
82 PayEx->Customer: Receive <SIE4>]
83 PayEx->Customer: Receive <Balance Report>
84 Deactivate PayEx
85 Deactivate Customer
86 |||
87 '//Sequence end//'
88 @enduml
89 {{/plantuml}}
90
91 = What you should do, step by step =
92
93 Below is an example provided in .XML
94
95 Note that the example is for a basic usage of the file format. It is provided to help understanding the file format and give the implementation a head start. For more extensive usage of the file format, head over to the [[API reference>>Sandbox.Invoice Service.Reference.WebHome]].
96
97 If you encounter any problem with the implementation, please visit the troubleshooting section.
98
99 == Step 1 Create CUSIN file ==
100
101 === Create file ===
102
103 Create a file with extension .XML and UTF-8 encoding. Name it according to the filename convention.
104 Add a row on root level with XML declaration, with XML-version 1.0 and UTF-8 encoding.
105
106 {{code language="xml"}}
107 <︖xml version="1.0" encoding="utf-8"︖>
108 {{/code}}
109
110 You can read more about this [[here>>Sandbox.Invoice Service.File Reference.WebHome]].
111
112 === Add CUSIN Header ===
113
114 Add a CUSIN Header at root level with the following attributes.
115
116 * XSD version
117 * Createion date and time
118 * Company number
119 * Company name
120
121 {{code language="xml"}}
122 <︖xml version="1.0" encoding="utf-8"︖>
123 <CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
124 </CUSIN>
125 {{/code}}
126
127 You can read more about this [[here>>Sandbox.Invoice Service.Reference.WebHome]].
128
129 === Distribution Date ===
130
131 Set your distribution date.
132
133 Add a child element {{code}}DistributionDate{{/code}}. This can be set to a date (in the future) of your choosing or you can leave it up to us.
134 In this example we have set the value to{{code}}AsSoonAsPossible{{/code}}.
135
136 {{code language="xml"}}
137 <︖xml version="1.0" encoding="utf-8"︖>
138 <CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
139 <DistributionDate>
140 <AsSoonAsPossible />
141 </DistributionDate>
142 </CUSIN>
143 {{/code}}
144
145 You can read more about this [[here>>Sandbox.Invoice Service.Reference.WebHome]].
146
147 === CUSINInfo ===
148
149 Define CUSINInfo per customer.
150
151 In order to define the CUSINInfo per customer you need to do add the following child elements:
152 Add {{code}}CustomerNo{{/code}}, {{code}}CustomerInfo{{/code}} and {{code}}Invoices{{/code}} to the {{code}}CUSINInfo{{/code}} parent.
153
154 {{code language="xml"}}
155 <︖xml version="1.0" encoding="utf-8"︖>
156 <CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
157 <DistributionDate>
158 <AsSoonAsPossible />
159 </DistributionDate>
160 <CUSINInfo>
161 <CustomerNo>1</CustomerNo>
162 <CustomerInfo/>
163 <Invoices/>
164 </CUSINInfo>
165 </CUSIN>
166 {{/code}}
167
168 You can read more about this [[here>>doc:Sandbox.Invoice Service.Reference.WebHome]].
169
170 We will go into more details related to {{code}}CustomerInfo{{/code}} element and {{code}}Invoices{{/code}} element in the coming steps.
171
172 === Customer info ===
173
174 In order to define the CustomerInfo per customer you need to do add the following child elements:
175 Add {{code}}Name{{/code}}, {{code}}RegNo{{/code}}, {{code}}DistributionAddressInfo{{/code}}, {{code}}PaymentInfo{{/code}} and {{code}}DistributionInfo{{/code}} to the {{code}}CustomerInfo{{/code}} parent.
176
177 {{code language="xml"}}
178 <︖xml version="1.0" encoding="utf-8"︖>
179 <CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
180 <DistributionDate>
181 <AsSoonAsPossible />
182 </DistributionDate>
183 <CUSINInfo>
184 <CustomerNo>1</CustomerNo>
185 <CustomerInfo>
186 <Name>Firstname Lastname</Name>
187 <RegNo CountryCode="SE">400513-0564</RegNo>
188 <DistributionAddressInfo>
189 <Addresses>
190 <Address AddressType="LegalAddress">
191 <Addressee>Firstname Lastname</Addressee>
192 <StreetAddress>Street 2</StreetAddress>
193 <ZipCode>12345</ZipCode>
194 <City>Big city</City>
195 <CoAddress>CoAdress</CoAddress>
196 <CountryCode>SE</CountryCode>
197 </Address>
198 <Address AddressType="BillingAddress">
199 <Addressee>Firstname Lastname</Addressee>
200 <StreetAddress>Another street 10</StreetAddress>
201 <ZipCode>53214</ZipCode>
202 <City>Big city</City>
203 <CoAddress>CoAdress</CoAddress>
204 <CountryCode>SE</CountryCode>
205 </Address>
206 </Addresses>
207 <E-MailAddress>test@test.com</E-MailAddress>
208 </DistributionAddressInfo>
209 <PaymentInfo>
210 <Set>
211 <PaymentRules>
212 <PaymentRule Rule="UseBGAGSE">
213 <Value>1</Value>
214 </PaymentRule>
215 </PaymentRules>
216 </Set>
217 </PaymentInfo>
218 <DistributionInfo>
219 <Set>
220 <BillTypes>
221 <BillType DistributionBillType="I_Invoice">
222 <DistributionType>PostalService</DistributionType>
223 </BillType>
224 </BillTypes>
225 </Set>
226 </DistributionInfo>
227 </CustomerInfo>
228 <Invoices/>
229 </CUSINInfo>
230 </CUSIN>
231 {{/code}}
232
233 You can read more about this [[here>>doc:Sandbox.Invoice Service.Reference.WebHome]].
234
235 === Invoices ===
236
237 In order to define the Invoice(s) per customer you need to do add the following child elements:
238 Add {{code}}InvoiceNo{{/code}}, {{code}}InvoiceDate{{/code}}, {{code}}Amount{{/code}} and {{code}}DistributionInfo{{/code}} to the {{code}}Invoices{{/code}} parent.
239
240 {{code language="xml"}}
241
242 <︖xml version="1.0" encoding="utf-8"︖>
243 <CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
244 <DistributionDate>
245 <AsSoonAsPossible />
246 </DistributionDate>
247 <CUSINInfo>
248 <CustomerNo>1</CustomerNo>
249 <CustomerInfo>
250 <Name>Firstname Lastname</Name>
251 <RegNo CountryCode="SE">400513-0564</RegNo>
252 <DistributionAddressInfo>
253 <Addresses>
254 <Address AddressType="LegalAddress">
255 <Addressee>Firstname Lastname</Addressee>
256 <StreetAddress>Street 2</StreetAddress>
257 <ZipCode>12345</ZipCode>
258 <City>Big city</City>
259 <CoAddress>CoAdress</CoAddress>
260 <CountryCode>SE</CountryCode>
261 </Address>
262 <Address AddressType="BillingAddress">
263 <Addressee>Firstname Lastname</Addressee>
264 <StreetAddress>Another street 10</StreetAddress>
265 <ZipCode>53214</ZipCode>
266 <City>Big city</City>
267 <CoAddress>CoAdress</CoAddress>
268 <CountryCode>SE</CountryCode>
269 </Address>
270 </Addresses>
271 <E-MailAddress>test@test.com</E-MailAddress>
272 </DistributionAddressInfo>
273 <PaymentInfo>
274 <Set>
275 <PaymentRules>
276 <PaymentRule Rule="UseBGAGSE">
277 <Value>1</Value>
278 </PaymentRule>
279 </PaymentRules>
280 </Set>
281 </PaymentInfo>
282 <DistributionInfo>
283 <Set>
284 <BillTypes>
285 <BillType DistributionBillType="I_Invoice">
286 <DistributionType>PostalService</DistributionType>
287 </BillType>
288 </BillTypes>
289 </Set>
290 </DistributionInfo>
291 </CustomerInfo>
292 <Invoices>
293 <InvoiceWithDistribution>
294 <InvoiceNo>3210</InvoiceNo>
295 <InvoiceDate>2017-12-07</InvoiceDate>
296 <Amount Currency="SEK">
297 <AmountExclVat>1000.00</AmountExclVat>
298 <VatAmount>250.00</VatAmount>
299 </Amount>
300 <DistributionInfo>
301 <InvoicePrintInfo>
302 <InvoicePrintBlocks>
303 <StandardPrintBlock>
304 <BasePrintBlock>
305 <SubOrderBlocks>
306 <SubOrderBlock TableType="A7">
307 <ColumnHeadLine>
308 <Columns>
309 <Column ColumnNo="1">
310 <Text>Article</Text>
311 </Column>
312 <Column ColumnNo="2">
313 <Text>Description</Text>
314 </Column>
315 <Column ColumnNo="3">
316 <Text>Quantity</Text>
317 </Column>
318 <Column ColumnNo="4">
319 <Text>Unit</Text>
320 </Column>
321 <Column ColumnNo="5">
322 <Text>Unit Price</Text>
323 </Column>
324 <Column ColumnNo="6">
325 <Text>Discount</Text>
326 </Column>
327 <Column ColumnNo="7">
328 <Text>Amount</Text>
329 </Column>
330 </Columns>
331 </ColumnHeadLine>
332 <Rows>
333 <Row>
334 <Columns>
335 <Column ColumnNo="1">
336 <Text>231</Text>
337 </Column>
338 <Column ColumnNo="2">
339 <Text>Monthly fee</Text>
340 </Column>
341 <Column ColumnNo="3">
342 <Text>1.00</Text>
343 </Column>
344 <Column ColumnNo="4">
345 <Text></Text>
346 </Column>
347 <Column ColumnNo="5">
348 <Text>1000,00</Text>
349 </Column>
350 <Column ColumnNo="6">
351 <Text></Text>
352 </Column>
353 <Column ColumnNo="7">
354 <Text>1000,00</Text>
355 </Column>
356 </Columns>
357 </Row>
358 <Row>
359 <Columns>
360 <Column ColumnNo="1">
361 <Text> </Text>
362 </Column>
363 </Columns>
364 </Row>
365 </Rows>
366 </SubOrderBlock>
367 <SubOrderBlock TableType="A3">
368 <Rows>
369 <Row>
370 <Columns>
371 <Column ColumnNo="2">
372 <Text>Amount excl. VAT</Text>
373 </Column>
374 <Column ColumnNo="3">
375 <Text>1000,00</Text>
376 </Column>
377 </Columns>
378 </Row>
379 <Row>
380 <Columns>
381 <Column ColumnNo="2">
382 <Text>VAT</Text>
383 </Column>
384 <Column ColumnNo="3">
385 <Text>250,00</Text>
386 </Column>
387 </Columns>
388 </Row>
389 <Row>
390 <Columns>
391 <Column ColumnNo="2">
392 <Text>VAT 25%</Text>
393 </Column>
394 <Column ColumnNo="3">
395 <Text>250,00 (1000,00)</Text>
396 </Column>
397 </Columns>
398 </Row>
399 </Rows>
400 </SubOrderBlock>
401 </SubOrderBlocks>
402 </BasePrintBlock>
403 </StandardPrintBlock>
404 </InvoicePrintBlocks>
405 </InvoicePrintInfo>
406 </DistributionInfo>
407 </InvoiceWithDistribution>
408 </Invoices>
409 </CUSINInfo>
410 </CUSIN>
411
412 {{/code}}
413
414 You can read more about this [[here>>doc:Sandbox.Invoice Service.Reference.WebHome]].
415
416 **Validation**
417
418 The XML-file must be validated with the lastest XML Schema Definition (XSD).
419 The XSD-file is found [[here>>attach:CUSIN_[2.0].xsd]].
420
421 **Transfer the file**
422
423 === Transfer the file ===
424
425 When you have transferred the file via FTP you'll get a receipt and an errorlog if something went wrong.
426
427 **Receipt**
428 When Cusin is processed, a receipt will be created showing numbers of processed customers, numbers of processed invoices and total amount.
429
430 * [[Record Description>>attach:FileResponse[1.0].pdf]]
431 * [[Example file>>attach:ARRCP01_10_20161213152316_0[CUSIN_10_20161212232200_0017.XML].XML]]
432 * [[XSD>>attach:ARRCP_[1.0].xsd]]
433
434 **Errorlog**
435 If errors occur during processing of the Cusin-file an errorlog will be created. Errors may refer to insufficient customer information, invoice information or format errors.
436
437 * [[Example file>>attach:ERRCUSIN_10_20161213152315_0[CUSIN_10_20161212232200_0017.XML].XML]]
438 * [[XSD>>attach:FileResponse[1.0].xsd]]
439
440 == Step 2: Response Files ==
441
442 === Bill Journal ===
443
444 Bill Journal is the format used to notify changes in invoice status, i.e. claim level, invoice status (closed), complaint, respite, etc.
445
446 * [[Record Description>>attach:BillJournal_[1.0].pdf]]
447 * [[Example file>>attach:BillJournal_10_20161213112138_1.XML]]
448 * [[XSD>>attach:BillJournal_[1.0].xsd]]
449
450 === Customer Journal ===
451
452 Customer Journal is the format used to notify changes in customer information, i.e. new legal address, activation/cancellation of consent, customer status "deceased", etc
453
454 * [[Record Description>>attach:CustomerJournal_1.0.pdf]]
455 * [[Example file>>attach:CustomerJournal_10_20161213112046_0.XML]]
456 * [[XSD>>attach:CustomerJournal_[1.0].xsd]]
457
458 == Step 3: Accounting and Disbursement ==
459
460 === Accounting Detail ===
461
462 Bookkeeping data is produced on two levels. Files are exported from PayEx on a daily schedule.
463
464 **Accounting Detai**l describes the accounting records on a transaction level. Includes invoice number, book account, amount, value date, etc.
465
466 * [[Record Description>>attach:Item_Description_ARAccountingDetail_1.1.pdf]]
467 * [[Example file>>attach:ARAccountingDetail_12345_20170419095509_122.xml]]
468 * [[XSD>>attach:ARAccountingDetail_[1.1].xsd]]
469
470 **SIE4** describes the accounting records on an aggregated level. Includes total amounts per book account.
471
472 * [[Record Description (SE)>>attach:SIE_filformat_ver_4B_SVENSKA.pdf]]
473 * [[Record Description (EN)>>attach:SIE_filformat_ver_4B_ENGLISH.pdf]]
474 * [[Example file>>attach:SIE4I_10_20161214093949_0[SEK_Claimant_BAS 2000].SI]]
475
476 === Balance Report ===
477
478 Balance Report (Client Asset Disbursement) includes:
479
480 * Summary and specification of total amount to be paid out
481 * Each record of "Client asset disbursement" in the Balance Report is equal to the total amount of Accounting Detail for the specified period.
482 * Fees deducted from amount to be paid out, or (when applicable) fees to be invoiced separatly.
483
484 **PayEx fees deducted from amount to be paid out**
485
486 * [[Example file>>attach:Test R1000-0001_0.pdf]]
487
488 **PayEx fees invoiced separatly**
489
490 * [[Example file>>attach:Test R1000-0001_2.pdf]]
491
492 === PayEx Connect API ===
493
494 PayEx Connect is a Web Service system that enables integrated access to PayEx services in a controlled and secure manner.
495 Access to this services requires explicit permissions on a company level and on a method level.
496
497 Manual Common describes the prerequisites needed before you start to integrate a system with PayEx Connect.
498
499 [[Manual Sample Service>>attach:Main.Invoicing.Invoice Service.Reference.WebHome@PayExConnect_Manual_SampleService.pdf]] describes web methods used in sample scenarios.
500
501 [[External Services>>attach:Main.Invoicing.Invoice Service.Reference.WebHome@PayExConnect_Manual_PxR_ExternalServices.pdf]] describes Invoice Services covering the following methods:
502
503 * Get Invoice Information
504 * Get Invoice document in the format of PDF
505 * Get Customer Information