# Wiki source code of Invoice Service

Last modified by Fredrik Köhler on 2018/12/07 12:59

#### Export

#### Office Formats

Export as PDF Export as ODT Export as RTF

#### Other Formats

Select the pages to export:

select all / none

Export as HTML
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