PayEx Developer Portal

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.

)))

)))

== Bicus2 ==

//Below diagram shows the structure of Bicus in current version//

19

20

[[image:1605691001216-370.png||height="985" width="376"]]

(% id="HEncoding" %)

== Encoding ==

(((

(((

The file must use [[__UTF-8 encoding__>>url:https://en.wikipedia.org/wiki/UTF-8]].

----

)))

)))

== 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.

== ==

== 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.

=== BicusInfo ===

==== 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

(% id="HRestrictioninWithdrawalofrecurringproducts" %)

133

===== Restriction invoice period of recurring products =====

134

135

PayEx Billing has a restriction for invoice period of recurring products to a maximum of 24 historical month.

136

137

==== Subscription ====

138

139

BiCus supports different types of subscriptions in order to make it easier to handle customer subscriptions.

140

141

Each subscription is divided into two or more sub elements that can be thought of as properties of the subscription.

142

143

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.

144

145

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.

146

147

===== Generic subscription =====

148

149

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.

150

151

=== DeviationInfo ===

152

153

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.

154

155

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.

156

157

==== Handling of elements ====

158

159

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.

===== clear =====

Is used to clear all data that belongs to the element. All deviation data will be erased when clear is used.

===== set =====

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.

===== add =====

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.

172

173

==== Version handling ====

174

175

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).

176

177

===== Version handling with example =====

178

179

(% border="1" style="margin-right:auto" %)

180

|=(% style="width: 78px;" %)Step|=(% style="width: 548px;" %)Action|=(% style="width: 666px;" %)Effect

181

|(% 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”

182

|(% 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”

183

|(% 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”

184

|(% 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”

185

186

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.

187

188

(% id="HResponsefiles" %)

189

== Response files ==

190

191

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.

192

For both CustomerInfo and DeviationInfo a responsefile will be produced.

193

If the firm doesn´t use DevationInfo no response file regarding deviations will be returned.

194

195

[[BicusResponse file with exampels>>doc:Main.Invoicing.billing.technical-reference.Costumer information.template.BicusResponse.WebHome]]

== ==

== Download current XML schema file ==

(% border="0" style="width:1023px" %)

204

|=(% 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

205

|(% 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

== ChangeLog ==

(((

(% id="HVersion1.1" %)

211

==== **Version 2.0.0** ====

212

213