Wiki source code of Invoice Service

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

101.1	1	{{error}}
103.1	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!
101.1	3	{{/error}}
	4
2.1	5	= Introduction =
	6
25.1	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.
2.1	8
25.1	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
2.1	23	= What you need before you get started =
	24
	25	* sFTP Client
26.1	26	* Agreement that includes PayEx Invoice Service (CUSIN)
2.1	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
50.1	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
64.1	63	==Step1 CreateCUSINfile==
50.1	64	Activate Customer
	65	Activate PayEx
64.1	66	Customer->PayEx: Create <Cusin>
	67	PayEx->Customer: Receive <Receipt>
	68	PayEx->Customer: Receive <Errorlog>
50.1	69	Deactivate Customer
64.1	70	PayEx->Consumer: Distribute <Invoice>]
50.1	71	\|\|\|
	72	Deactivate Consumer
	73	hnote over Customer: Invoice gets closed or continues in claim process
	74	\|\|\|
64.1	75	== Step 2: Response Files==
	76	PayEx->Customer: Receive <Bill Journal>
50.1	77	Activate Customer
64.1	78	PayEx->Customer: Receive <Customer Journal>
50.1	79	\|\|\|
65.1	80	==Step 3: Accounting and Disbursement==
	81	PayEx->Customer: Receive <Accounting Detail>
	82	PayEx->Customer: Receive <SIE4>]
	83	PayEx->Customer: Receive <Balance Report>
50.1	84	Deactivate PayEx
	85	Deactivate Customer
	86	\|\|\|
	87	'//Sequence end//'
	88	@enduml
	89	{{/plantuml}}
2.1	90
	91	= What you should do, step by step =
	92
	93	Below is an example provided in .XML
	94
105.1	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]].
2.1	96
	97	If you encounter any problem with the implementation, please visit the troubleshooting section.
	98
41.1	99	== Step 1 Create CUSIN file ==
2.1	100
41.1	101	=== Create file ===
	102
2.1	103	Create a file with extension .XML and UTF-8 encoding. Name it according to the filename convention.
19.1	104	Add a row on root level with XML declaration, with XML-version 1.0 and UTF-8 encoding.
2.1	105
27.1	106	{{code language="xml"}}
29.1	107	<︖xml version="1.0" encoding="utf-8"︖>
27.1	108	{{/code}}
2.1	109
104.1	110	You can read more about this [[here>>Sandbox.Invoice Service.File Reference.WebHome]].
27.1	111
37.1	112	=== Add CUSIN Header ===
2.1	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
105.1	127	You can read more about this [[here>>Sandbox.Invoice Service.Reference.WebHome]].
30.1	128
38.1	129	=== Distribution Date ===
2.1	130
31.1	131	Set your distribution date.
2.1	132
20.1	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}}.
2.1	135
32.1	136	{{code language="xml"}}
	137	<︖xml version="1.0" encoding="utf-8"︖>
2.1	138	<CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
106.1	139	<DistributionDate>
	140	<AsSoonAsPossible />
	141	</DistributionDate>
32.1	142	</CUSIN>
	143	{{/code}}
2.1	144
105.1	145	You can read more about this [[here>>Sandbox.Invoice Service.Reference.WebHome]].
32.1	146
39.1	147	=== CUSINInfo ===
2.1	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">
45.1	157	<DistributionDate>
	158	<AsSoonAsPossible />
	159	</DistributionDate>
	160	<CUSINInfo>
	161	<CustomerNo>1</CustomerNo>
	162	<CustomerInfo/>
	163	<Invoices/>
	164	</CUSINInfo>
2.1	165	</CUSIN>
	166	{{/code}}
	167
105.1	168	You can read more about this [[here>>doc:Sandbox.Invoice Service.Reference.WebHome]].
34.1	169
	170	We will go into more details related to {{code}}CustomerInfo{{/code}} element and {{code}}Invoices{{/code}} element in the coming steps.
	171
40.1	172	=== Customer info ===
2.1	173
8.1	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.
3.1	176
7.1	177	{{code language="xml"}}
	178	<︖xml version="1.0" encoding="utf-8"︖>
5.1	179	<CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
16.1	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>
7.1	230	</CUSIN>
	231	{{/code}}
3.1	232
105.1	233	You can read more about this [[here>>doc:Sandbox.Invoice Service.Reference.WebHome]].
33.1	234
42.1	235	=== Invoices ===
2.1	236
12.1	237	In order to define the Invoice(s) per customer you need to do add the following child elements:
22.1	238	Add {{code}}InvoiceNo{{/code}}, {{code}}InvoiceDate{{/code}}, {{code}}Amount{{/code}} and {{code}}DistributionInfo{{/code}} to the {{code}}Invoices{{/code}} parent.
11.1	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">
15.1	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>
11.1	410	</CUSIN>
	411
	412	{{/code}}
	413
105.1	414	You can read more about this [[here>>doc:Sandbox.Invoice Service.Reference.WebHome]].
11.1	415
2.1	416	Validation
	417
	418	The XML-file must be validated with the lastest XML Schema Definition (XSD).
70.1	419	The XSD-file is found [[here>>attach:CUSIN_[2.0].xsd]].
2.1	420
	421	Transfer the file
	422
43.1	423	=== Transfer the file ===
2.1	424
48.1	425	When you have transferred the file via FTP you'll get a receipt and an errorlog if something went wrong.
	426
49.1	427	Receipt
43.1	428	When Cusin is processed, a receipt will be created showing numbers of processed customers, numbers of processed invoices and total amount.
	429
71.1	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]]
66.1	433
49.1	434	Errorlog
43.1	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
75.1	437	* [[Example file>>attach:ERRCUSIN_10_20161213152315_0[CUSIN_10_20161212232200_0017.XML].XML]]
	438	* [[XSD>>attach:FileResponse[1.0].xsd]]
72.1	439
57.1	440	== Step 2: Response Files ==
2.1	441
58.1	442	=== Bill Journal ===
2.1	443
58.1	444	Bill Journal is the format used to notify changes in invoice status, i.e. claim level, invoice status (closed), complaint, respite, etc.
	445
80.1	446	* [[Record Description>>attach:BillJournal_[1.0].pdf]]
	447	* [[Example file>>attach:BillJournal_10_20161213112138_1.XML]]
	448	* [[XSD>>attach:BillJournal_[1.0].xsd]]
58.1	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
84.1	454	* [[Record Description>>attach:CustomerJournal_1.0.pdf]]
	455	* [[Example file>>attach:CustomerJournal_10_20161213112046_0.XML]]
	456	* [[XSD>>attach:CustomerJournal_[1.0].xsd]]
58.1	457
57.1	458	== Step 3: Accounting and Disbursement ==
2.1	459
59.1	460	=== Accounting Detail ===
	461
	462	Bookkeeping data is produced on two levels. Files are exported from PayEx on a daily schedule.
	463
91.1	464	Accounting Detail describes the accounting records on a transaction level. Includes invoice number, book account, amount, value date, etc.
59.1	465
91.1	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]]
59.1	469
	470	SIE4 describes the accounting records on an aggregated level. Includes total amounts per book account.
	471
91.1	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]]
59.1	475
97.1	476	=== Balance Report ===
59.1	477
97.1	478	Balance Report (Client Asset Disbursement) includes:
59.1	479
94.1	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.
59.1	483
94.1	484	PayEx fees deducted from amount to be paid out
59.1	485
94.1	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
96.1	492	=== PayEx Connect API ===
59.1	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
100.1	499	[[Manual Sample Service>>attach:Main.Invoicing.Invoice Service.Reference.WebHome@PayExConnect_Manual_SampleService.pdf]] describes web methods used in sample scenarios.
59.1	500
100.1	501	[[External Services>>attach:Main.Invoicing.Invoice Service.Reference.WebHome@PayExConnect_Manual_PxR_ExternalServices.pdf]] describes Invoice Services covering the following methods:
98.1	502
	503	* Get Invoice Information
	504	* Get Invoice document in the format of PDF
	505	* Get Customer Information