Wiki source code of Implementation Guide: Cusin

Last modified by Jonatan Östlund on 2025/02/17 15:37

41.1	1	= Introduction =
	2
	3	(% class="jumbotron" %)
	4	(((
	5	(% class="container" %)
	6	(((
43.1	7	This is a general step-for-step implementations guide that guide you through the creation of the CUSIN file that contains your invoice information.
41.1	8	)))
	9	)))
	10
	11	== Prerequisites ==
	12
43.1	13	Before you start implementing PayEx Invoice Service the following is required:
41.1	14
	15	* A sFTP Client
	16	* An agreement that includes PayEx Invoice Service (CUSIN)
	17	* Obtained credentials from PayEx
	18	* A basic understanding of [[file name convention and file format limitations>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.Cusin.WebHome\|\|anchor="HNameconvention"]]
	19
43.1	20	Pease contact us if you have any questions on how to get started.
	21
41.1	22	== Overview ==
	23
43.1	24	Before getting started, have a look at the high level sequence diagram below, which will help you getting a better understanding of the whole process and the components necessary to implement Invoice Service.
41.1	25
44.1	26	The invoice process using CUSIN is designed to operate batch-wise where multiple invoices are to be handled and sent to PayEx in a single file.
	27
43.1	28	{{plantuml}}
	29	@startuml
	30	skinparam sequence{
	31	ArrowColor #2DA944
	32	ActorFontColor #333333
	33	ActorFontStyle bold
	34	ActorFontSize 15
	35	ActorBackgroundColor #fefefe
	36	ActorBorderColor #2DA944
	37	LifeLineBorderColor #999999
	38	LifeLineBackgroundColor #dddddd
	39	ParticipantBorderColor #2DA944
	40	ParticipantBackgroundColor #ffffff
	41	ParticipantFontColor #333333
	42	ParticipantFontStyle bold
	43	}
	44	skinparam Roundcorner 10
	45	skinparam Shadowing false
	46	skinparam ActivityBorderColor #123123
	47	skinparam NoteBackgroundColor white
	48	skinparam NoteBorderColor #999999
	49	skinparam NoteFontColor #333333
	50	skinparam sequenceDividerBackgroundColor white
	51	skinparam sequenceDividerBorderColor #999999
	52	skinparam sequenceDividerFontStyle bold
	53	skinparam sequenceDividerFontSize 15
	54	'//Sequence start//'
	55	\|\|\|
	56	Customer->Company: Purchase information processed via Company's ERP
	57	\|\|\|
	58	Activate Customer
	59	==[[/xwiki/wiki/developer/view/Main/Invoicing/invoice-service/Implementation%20guide/#HInvoicing Invoicing]]==
	60	Activate Company
	61	Activate PayEx
	62	Company->PayEx: Create <Cusin>
	63	PayEx->Company: Receive <Receipt>
	64	PayEx->Company: Receive <Errorlog>
	65	Deactivate Company
	66	PayEx->Customer: Distribute <Invoice>]
	67	\|\|\|
	68	Deactivate Customer
	69	hnote over Company: Invoice gets payed/closed or continues in claim process
	70	\|\|\|
	71	==[[/xwiki/wiki/developer/view/Main/Invoicing/invoice-service/Implementation%20guide/#HReportsandAccounting Reports and Accounting]]==
	72	PayEx->Company: Receive <Bill Journal>
	73	Activate Company
	74	PayEx->Company: Receive <Customer Journal>
	75	PayEx->Company: Receive <Accounting Detail>
	76	PayEx->Company: Receive <SIE4>]
	77	PayEx->Company: Receive <Balance Report>
	78	PayEx->Company: Receive <ARAccounting (Billing only)>
	79	Deactivate PayEx
	80	Deactivate Company
	81	\|\|\|
	82	'//Sequence end//'
	83	@enduml
	84	{{/plantuml}}
41.1	85
43.1	86	(% class="wikigeneratedid" id="HWhatyoushoulddo2Cstepbystep." %)
	87	All main steps of the invoice process are described below. Please note that all XML examples below are here primarily for display purposes, to help you get an understanding of the CUSIN file format and to aid you in the implementation.
	88
	89	If you encounter any problem during implementation, don't hesitate to [[contact us>>mailto:invoice.client@payex.com]].
	90
41.1	91	== Invoicing ==
	92
43.1	93	The initial step is to create your [[CUSIN >>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.Cusin.WebHome]]file.
41.1	94
	95	=== Cusin ===
	96
43.1	97	The first thing you need to do is to create a CUSIN file with extension .XML and UTF-8 encoding. Name it according to the filename convention.
41.1	98
43.1	99	Head over to our [[technical reference section>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.Cusin.WebHome]] for a more extensive description of the file format, where you find more information of each element in the XML schema and CUSIN example file.
41.1	100
44.1	101	Please note! If there are multiple invoices to be handled at the same time: do not send one invoice per file. We strongly suggest to batch them together in one single file. This will also speed up the process of creating and distributing the invoices.
	102
43.1	103	To learn more of how to edit invoice column length and use summary rows, visit the [[Invoice columns section>>url:https://developer.payex.com/xwiki/wiki/developer/view/Main/Invoicing/invoice-service/Invoice%20columns/]].
	104
	105	(% class="wikigeneratedid" id="HTransferringfilestoPayEx" %)
	106	When you have a complete and validated CUSIN file, you are ready to transfer it to PayEx via sFTP.
	107
	108	(% class="wikigeneratedid" %)
	109	Upon reception PayEx will process the file and send you a receipt in return. If something went wrong, you will also receive an error log.
	110
41.1	111	=== Receipt ===
	112
44.1	113	When the CUSIN file, containing one or more activities - is processed a receipt will be created showing numbers of processed customers, numbers of processed invoices and total amount. A receipt is created for each file you send.
41.1	114
43.1	115	Each activity has their own set of result parameters
41.1	116
43.1	117	You can view the XSD and a detailed description [[here>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.Receipt.WebHome]].
	118
41.1	119	=== Error log ===
	120
44.1	121	If errors are encountered during file processing an errorlog will be created. Errors may refer to insufficient customer information, invoice information or format errors. An error log is created for each file you send.
41.1	122
43.1	123	The first part displays the processed item itself.
41.1	124
43.1	125	The second part of the error log displays the response item message element that gives reference back to the processed file.
	126
	127	You can view the XSD and a detailed description [[here>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.Errorlog.WebHome]].
	128
41.1	129	=== (% style="color:inherit; font-family:inherit; font-size:23px" %)Invoice generation(%%) ===
	130
43.1	131	When you have transfered your CUSIN file to PayEx and it has been processed successfully the end result will look similar to the invoice example below.
41.1	132
43.1	133	Click on the invoice image to download the full PDF invoice example. If you want to learn more about customizing your invoice, head over to our section that cover [[additional features and functions>>doc:Main.Invoicing.invoice-service.Implementation guide.Supplementary features.WebHome]].
41.1	134
47.1	135	== [[image:invoice-example.PNG]] ==
41.1	136
	137	== Reports and Accounting ==
	138
43.1	139	You get response files from PayEx in the from of Bill and Customer Journal.
41.1	140
	141	=== Bill Journal ===
	142
43.1	143	Bill Journal is the format used to notify changes in invoice status. Entries could relate to events such as a new claim process level, invoices getting closed and newly registered complaints and respites.
41.1	144
43.1	145	You find the Bill Journal technical reference [[here>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.BillJournal.WebHome\|\|anchor="HBillJournal"]].
41.1	146
	147	=== Customer Journal ===
	148
43.1	149	Customer Journal is the format used to notify changes in customer information. Entries could relate to events such as a new legal address, activation/cancellation of consent and customer status changes due to decease.
41.1	150
43.1	151	You find the Customer Journal technical reference [[here>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.CustomerJournal.WebHome\|\|anchor="HCustomerJournal"]].
41.1	152
	153	=== Accounting Detail ===
	154
43.1	155	Bookkeeping data is produced on two levels. You get accounting records on the transactional level as well as aggretated in the standardised SIE format type 4.
41.1	156
43.1	157	Files are exported from PayEx on a daily schedule.
41.1	158
43.1	159
	160	The Accounting Detail file describes the accounting records on the transaction level and Includes invoice number, book account, amount, value date, etc.
	161
	162	You find the Accounting Detail technical reference [[here>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.6\. ARAccountingDetail.WebHome\|\|anchor="HAccountingDetail" style="background-color: rgb(255, 255, 255);"]].
	163
	164
	165	The SIE4 file describes the accounting records on an aggregated level, that includes total amounts per book account.
	166
	167	You find the SIE4 technical reference [[here>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.SIE4.WebHome\|\|anchor="HSIE4" style="background-color: rgb(255, 255, 255);"]].
	168
	169	(% id="HBalanceReport" %)
41.1	170	=== Balance Report ===
	171
43.1	172	The [[Balance Report (Client Asset Disbursement)>>doc:Main.Invoicing.invoice-service.Implementation guide.Technical reference.BalanceReport.WebHome\|\|anchor="HBalanceReport"]] includes:
41.1	173
	174	* A payment summary of amount sold, fees and, VAT and specification of total amount to be paid out.
	175	* A sales specification. Each record of "Client asset disbursement" listed is equal to the full Accounting Detail for the specified period.
	176	* (((
	177	A Fees specification. Depending on setup, fees are either deducted from the amount to be paid out, or (when applicable) to be invoiced separatly.Each fees row specify Quantity (sales), Amount (sales), Unit price, Provision and fee Amount.
	178	)))