Wiki source code of Bicus2

Last modified by David Persson on 2021/01/29 09:26
Show last authors
1 = =
2
3 (% class="jumbotron" %)
4 (((
5 (% class="container" %)
6 (((
7 This is a technical overview of the fileformat, its elements and related material. This section should be seen as a companion to the standard setup scenario.
8
9 Please note that your Response files might only utilize and/or contain a subset of all elements described below. See the XSD version for your response files to learn more.
10
11
12 )))
13 )))
14
15 == Bicus2 ==
16
17
18 //Below diagram shows the structure of Bicus in current version//
19
20 [[image:1605691001216-370.png||height="985" width="376"]]
21
22
23
24
25
26 (% id="HEncoding" %)
27 == Encoding ==
28
29 (((
30 (((
31 The file must use [[__UTF-8 encoding__>>url:https://en.wikipedia.org/wiki/UTF-8]].
32
33
34 ----
35 )))
36 )))
37
38 == Name convention ==
39
40
41 Bicus2_<CompanyNumber>_<DateTime>_<SerialNumber>.xml
42
43 (% class="table-bordered table-striped" %)
44 |=Names Component|=Description
45 |CompanyNumber|The company number in our ledger system
46 |DateTime|Date created, Should be in the format ISO 8601 format, YYYYMMDDThhmmss
47 |SerialNumber|Should follow an not broken number series, 00001, and so on.
48
49 == ==
50
51 == General information and explanation of records ==
52
53 Bicus is used to submit end-user information as well as definitions of deviation products to the PayEx Billing System.
54
55 Bicus is divided in two parts of information, DeviationInfo and BicusInfo.
56
57 BicusInfo contains the end customer's customer information, all of the customer's subscriptions and products to be processed in Billing.
58
59 Benefits for the use of the Bicus file format:
60
61 * Bicus XSD validation on the sending system.
62 ** Input data and XML errors can be stopped before sending
63 * The PayEx Billing System processes and stores all correct customers. Incorrect customers will be returned in a detailed response file.
64 ** Firms can choose to start billing for all customers that are correct in the PayEx Billing system
65 * Processing Bicusfiles can be scheduled 24/7 and response files will be delivered immediately after processing Bicusfiles
66
67 The deviation-part in the Bicusfile contains definitions of deviation products by entering other selected values override the "master product" which is defined in Billing System.
68
69 (% id="HImplementation" %)
70 === Implementation ===
71
72 Implementation of Bicus requires a complete file with all customers. Otherwise it is sufficient to only send updated customers.
73
74 (% id="HImplementation" %)
75 === Limitations ===
76
77 Each BiCus file can have a maximum of 50 000 BiCusInfo elements.
78 DeviationInfo only needs to be send when there are new deviation products and updates of existing deviation products.
79
80
81 === BicusInfo ===
82
83 ==== Handling of elements in BicusInfo ====
84
85 Bicus is structured so that a new or updated customer has to be sent in its entirety. If any of the customer's information, for example a subscription not will be sent it will be deleted in the Billing System.
86
87 The idea is that the sending party sends a total snapshot of a customer’s data to be processed in the Billing System.
88
89 ==== Non mandatory elements ====
90
91 If the customers data previously submitted in a non-mandatory set and in a subsequent file is not sent with that, the data will be removed.
92
93 All data to be processed per new or updated customer has to occur in the latest processed Bicusfile.
94
95 ==== Mandatory elements ====
96
97 All mandatory data in Bicus has to be sent for each customer. If not, the whole end-customer capture will be cancelled and an error code will be returned to a BicusResponse. The import process then advances to the next end-user.
98
99 ==== Customer information ====
100
101 This element is mandatory.
102
103 ===== CustomerStatus =====
104
105 The element CustomerStatus is used to disable and delete the end customers in the Billing System.
106
107 The requirement to inactivate a customer is that the customers subscriptions are not active and that all products and usage has been billed.
108
109 Existing customers and new customers should have the default value “Active”.
110
111 As soon as a customer has been send with value Inactive no information regarding this customer will be available in any report or API. A final removal of the customers information will be made after x days, where the recommendation is to use the default of 40 days. Within this period it´s possible to reactivate the customer again. This can be done by sending value Active in the CustomerStatus.
112
113
114 ===== Regnumber =====
115
116 Validation of the customers registration number is made when the attribute CountryCode is set and is equivalent to a Nordic country (Sweden, Norway and Denmark).
117
118 ===== LanguageCode =====
119
120 PayEx supports different languages on invoices depending on which Language Code has been set on the customer. This feature must be configured in PayEx before used.
121
122 ===== PaymentInfo =====
123
124 The payment method "BA" (direct debit) is handled in the Payex Sales ledge system and cannot be set by Bicus. For “BA”Bicus the element "Verified payment method” can be used for the Nordic countries.
125
126 Ex: send "Payment Rule / Rule" to "UseBGAGSE" and "value = true" then PayEx is using the payment method BA (direct debit) as soon as it is registered on the end-customer through their bank. This will for example give a possibility to block direct debet temporary for a specific invoice period.
127
128 ===== CustomerProduct =====
129
130 If a customerproduct refers to a deviation product, the DeviationInfo block has to be processed before, either in the current file or in a previous file.
131
132 ==== Subscription ====
133
134 BiCus supports different types of subscriptions in order to make it easier to handle customer subscriptions.
135
136 Each subscription is divided into two or more sub elements that can be thought of as properties of the subscription.
137
138 A subscriber number can only be set once per subscription type. Instead of sending the subscriber number multiple times the different properties that can change under a subscription is made up in periods.
139
140 If one or more of the customer's subscription not will be sent they will be deleted in the Billing System and closed with an end date. All previously invoiced information/statistics will not be taken away. If a subscription accidentally was deleted, it can be submitted again and the Billing System takes into account previous invoicing of products on subscription.
141
142 ===== Generic subscription =====
143
144 The generic subscription is a special subscription that can handle up to 34 digits in subscriber number. This subscription has been developed to support subscriptions that has no need of usage information.
145
146 === DeviationInfo ===
147
148 Deviation products have been developed in order to offer an easy way to describe deviant products for example certain campaign prices. The deviation product does not need to be configured by PayEx, it is solely managed by PayEx Customer.
149
150 All deviation products have to be connected to a PayEx “master” product and the only requirement is that the masterproduct has to be configured in the PayEx Billing system before deviation can be used.
151
152 ==== Handling of elements ====
153
154 BiCus supports functionality to only update specific elements regarding deviation that are target for change instead of the necessity to send all the deviation versions and their information all over again.
155
156 ===== clear =====
157
158 Is used to clear all data that belongs to the element. All deviation data will be erased when clear is used.
159
160 ===== set =====
161
162 Adds or updates existing deviation version. Will update the element according to the data that is sent in the element. Previous data will be erased, meaning that if there exists a previous deviation version with the same “startdate” all products that are not defined again will be erased.
163
164 ===== add =====
165
166 Adds or updates existing deviation version. Will update the element according to the data that is sent in the element. Previous data will be retained, meaning that if there exists a previous deviation version with the same “startdate” the products in the add element will be added to that version.
167
168 ==== Version handling ====
169
170 Deviation products have version handling in order to offer the possibility to make price adjustments. Exactly like recurring products that are configured in the Billing system, price changes can only occur when it´s change of month. A ProductCode can only occur once per Deviation element (version).
171
172 ===== Version handling with example =====
173
174 (% border="1" style="margin-right:auto" %)
175 |=(% style="width: 78px;" %)Step|=(% style="width: 548px;" %)Action|=(% style="width: 666px;" %)Effect
176 |(% style="width:78px" %)1|(% style="width:548px" %)Reading product: AVVPR, version 2015-01, price 1kr, description ”Monthly fee A1”|(% style="width:666px" %)New product AVVPR in the system, price 1kr valid from 2015-01. description ”Monthly fee A1”
177 |(% style="width:78px" %)2|(% style="width:548px" %)Reading product: AVVPR, version 2016-01, price 2kr, description ”Monthly fee A2”|(% style="width:666px" %)New version on existing product, price 1kr valid from 2015-01. Price 2kr valid from 2016-01. Other, non-version handled properties from this file -> description ”Monthly fee A2”
178 |(% style="width:78px" %)3|(% style="width:548px" %)Reading product: AVVPR, version 2016-01, price 3kr, description ”Monthly fee A3”|(% style="width:666px" %)Update existing version. Price 1kr valid from 2015-01. Price 3kr valid from 2016-01. Other, non-version handled properties from this file -> description ”Monthly fee A3”
179 |(% style="width:78px" %)4|(% style="width:548px" %)Reading product: AVVPR, version 2015-01, price 0,50kr, description ”Monthly fee A4”|(% style="width:666px" %)Update existing version. Price 0,50kr valid from 2015-01. Erasing all succeeding versions, price 3kr valid from 2016-01 will be erased. Other, non-version handled properties from this file -> description ”Monthly fee A4”
180
181 According to the description above it’s clear that different versions of products must be read in the correct order where the earliest “valid from date” should be read first. When products are removed from the deviation block all related prices are also removed. This is a precaution to make sure that products don’t fall back on earlier versions by mistake.
182
183 (% id="HResponsefiles" %)
184 == Response files ==
185
186 The response file from Bicus returns only rejected customers. All information about the rejected customer that was send is returned and various/different error messages for each customer will be presented.
187 For both CustomerInfo and DeviationInfo a responsefile will be produced.
188 If the firm doesn´t use DevationInfo no response file regarding deviations will be returned.
189
190 [[BicusResponse file with exampels>>doc:Main.Invoicing.billing.technical-reference.Costumer information.template.BicusResponse.WebHome]]
191
192 == ==
193
194 == Download current XML schema file ==
195
196
197
198 (% border="0" style="width:1023px" %)
199 |=(% style="width: 208px; background-color: rgb(237, 237, 237);" %)Fileversion|=(% style="width: 213px; background-color: rgb(237, 237, 237);" %)Version|=(% style="width: 288px; background-color: rgb(237, 237, 237);" %)Releasedate|=(% style="width: 585px; background-color: rgb(237, 237, 237);" %)Comment
200 |(% style="width:208px" %)[[Bicus[2.0.0].xsd>>attach:Main.billing.technical-reference.WebHome@BiCus[2.0.0].xsd]]|(% style="width:213px" %)2.0.0|(% style="width:288px" %)(% style="left:-5000px; width:1px" %)2018-04-01|(% style="width:585px" %)(% style="left:-5000px; width:1px" %)Initial version
201
202 == ChangeLog ==
203
204 (((
205 (% id="HVersion1.1" %)
206 ==== **Version 2.0.0** ====
207
208 (% id="HJanuary2C2016" %)
209 ===== April, 2018 =====
210
211 [[Bicus[2.0.0].xsd>>attach:Main.billing.technical-reference.WebHome@BiCus[2.0.0].xsd]]
212
213
214 Initial version
215 )))