PayEx Developer Portal

1

= =

2

3

(% class="jumbotron" %)

4

(((

5

(% class="container" %)

6

(((

7

Please note that your Response files might only utilize and/or contain a subset of all elements described below. See the Record description for your response files to learn more.

)))

)))

= Name convention =

PR01_<CompanyNumber>_<DateTime>_<(% style="font-size:14px" %)SEQNO(%%)>.DAT

(% border="1" %)

|=(% style="width: 371px;" %)Names Component|=(% style="width: 1121px;" %)Description

20

|(% style="width:371px" %)CompanyNumber|(% style="width:1121px" %)The company number in PayEx ledger system

21

|(% style="width:371px" %)DateTime|(% style="width:1121px" %)Date created in format YYMMDDHHMMSS

22

|(% style="width:371px" %)SEQNO|(% style="width:1121px" %)Unbroken serial number sequence.

23

24

**For example: **PR01_1234_201001155511_1.DAT

25

26

The file is semicolon-separated.

27

28

29

(% id="HWhattoavoid" %)

30

== What to avoid ==

31

32

* If the PR01-file contains errors that need to be corrected a new PR01 needs to be send with the next coming serial number

33

* The customer number needs to be registred in the PayEx Billing system before processing PR01-files containing.

== ==

== Change log ==

(% border="1" %)

|=**Version**|=(% style="width: 166px;" %)**Date**|=(% style="width: 879px;" %)**Description**|=(% style="width: 328px;" %)**Created by**

41

|1.3|(% style="width:166px" %)2020-06-10|(% style="width:879px" %)(((

42

(% lang="EN-US" style="font-family:~"Garamond~",serif; font-size:12pt" %)Updated Q- and B -record with three new fields that can be used to manage different events on layout or in Billing process.

43

)))|(% style="width:328px" %)Daniel Olsson

44

|1.4|(% style="width:166px" %)2023-09-26|(% style="width:879px" %)Updated with "Soft validation"|(% style="width:328px" %)Daniel Olsson

45

46

=

47

General information and explanation of records =

48

49

Product files to Billing (PR01) are used to add fees for end-user in the PayEx Billing System. PR01-files can contain products on customer level and/or subscription level.

50

51

After creating a billrun in the PayEx Billing system the products from the PR01-file will be presented on the invoice.

52

53

Incorrect data in fields will be returned in a detailed error file.

54

55

PR01 needs to be correct in its total to get processed.

== Standard flow ==

Format errors will be returned in a general error file

60

61

Incorrect data in fields will be returned into an error file (BERR007..ErrorlogProductfile).

62

63

Correct data in all fields will lead to a receipt file (BRCP007..ReceiptProductfile).

64

65

[[image:1686896352935-981.png||height="521" width="1188"]]

66

67

(% id="HResponsefilesdocumentation:" %)

68

==== Response files documentation: ====

69

70

[[Receipt and Error -file example>>doc:Main.Invoicing.billing.technical-reference.Product File.3 PR01.xml schema description.WebHome]]

71

72

=== Soft validation flow ===

73

74

Some type of errors can be configured as "soft" errors. Meaning that customer numbers with certain preconfigured errors can be excluded from the PR-file while processing. These mentioned “soft” errors will be presented as a warning (W) in **BERR007_ErrorlogProductfile** instead and simultaneously returned in an .XML file with name **PRRESPONSE**.

75

This response file needs actions to be taken before resending the incorrect data of the customer in a new PR file after finalizing the original billing process.

76

77

[[image:1686896663842-265.png||height="520" width="1184"]]

78

79

==== Response files documentation: ====

80

81

===== [[Error log PRxx (BERR007)>>doc:.Record description.Error log PR01 (BERR007).WebHome]] =====

82

83

===== [[ProductResponse (XML)>>doc:.Record description.ProductResponse (XML).WebHome]] =====

84

85

===== [[Receipt PRxx (BRCP007)>>doc:.Record description.Receipt PRxx (BRCP007).WebHome]] =====

86

87

= Record Description =

== H - Header ==

Required record

(% border="1" %)

|Transaction type|1|H|Req|Header record

96

|Company number|2|N(5)|Req|The firm number you receive from PayEx

97

|Company name|3|X(40)|Req|Your firm name

98

|Date of creation|4|N(6)|Req|YYMMDD – the same date as in the filename.

99

|Time of creation|5|N(4)|Req|HHMM – the time of creation.

100

101

Example on the records appearance.

102

103

**H;99999;Company AB;180919;1220**

104

105

== M - Metadata record ==

Required record

(% border="1" %)

|Transaction type|1|M|Req|Metadata record

112

|Type of billing|2|N(2)|Req|0 = ordinary invoicing (default). 1 – n = test invoicing. Support for test invoicing and the different codes to be used are set up in cooperation with PayEx.

113

114

115

Example on the records appearance

**M;0;**

== P - Product record ==

Optional record

(% border="1" %)

|Transaction type|1|P| |Product record.

126

|Customer number|2|X(15)|Req|Customer number

127

|Product text|3|X(73)|Req|Product text, see Definitions and terms

128

|Quantity|4|N(5)|Req|Number of products

129

|Unit|5|N(7),N(2-6)|Req|Price for one product, can have 2 to 6 decimals.

130

|VAT rate|6|N(7),N(2)|Req|VAT rate

131

|Product_group_Id|7|N(5)|Req|According to agreement with PayEx.

132

|Identification_No|8|N(10)| |Id used to group statistics. Required when service Revenue Accounting is active, maximum value 2^^31^^

133

|Product_Id|9|N(10)| |Id for the product, maximum value 2^^31^^

134

135

Example on the records appearance.

136

137

**P;12345;Football1;5;23,50;25,00;2;;

138

P;12345;Football2;5;23,50;25,00;2;1;12365487**

139

140

== K - Customer number Information record ==

Optional record

**~*~***Is not used without agreement

(% border="1" %)

|Transaction type|1|K| |Product record.

149

|Customer number|2|X(15)|Req|Customer number

150

|Product text|3|X|Req|Product text, see Definitions and terms

151

|Product_group_Id|4|N(5)|Req|According to agreement with PayEx.*

152

|Group_No|5|N(3)| |Is empty if nothing else is agreed.

153

154

Example on the records appearance:

155

156

**K;000087;Installation: the Villa;9;**

157

158

*Product_group_id is set according to agreement for CustnoInformation record.

159

160

== I - A -number Information record ==

Optional record

**~*~***Is not used without agreement

(% border="1" %)

|Transaction type|1|I| |Product record.

169

|Customer number|2|X(15)|Req|Customer number

170

|A-number|3|X(34)|Req|A-number

171

|Product text|4|X|Req|Product text, see Definitions and terms

172

|Product_group_Id|5|N(5)|Req|According to agreement with PayEx.*

173

|Group_No|6|N(3)| |Is left blank if nothing else is agreed.

174

175

Example on the records appearance:

176

177

**I;000087;0702402377;Installation: The house;9;**

178

179

~* Product_group_id is set according to agreement for A -no Information record.

180

181

== A - A -number product record ==

Optional record

(% border="1" %)

|Transaction type|1|A| |Product record.

188

|Customer number|2|X(15)|Req|Customer no.

189

|A-number|3|X(34)|Req|A-Number

190

|Product text|4|X|Req|Product text, see Definitions and terms

191

|Quantity|5|N(5)|Req|Number of products

192

|Unit|6|N(7),N(2-6)|Req|Price for one product, can have 2 to 6 decimals.

193

|VAT rate|7|N(7),N(2)|Req|VAT rate

194

|Product_group_Id|8|N(5)|Req|According to agreement with PayEx.

195

|Identification_No|9|N(10)| |Id used to group statistics. Required when service Revenue Accounting is active, maximum value 2^^31^^

196

|Product_Id|10|N(10)| |Id for the product, maximum value 2^^31^^

197

198

Example on the records appearance:

199

200

**A;12345;4788743;Installation fee1;5;150,00;25,00;1;2;

201

A;12345;4788743;Installation fee3;5;150,00;25,00;1;2;123456**

202

203

== Q - Date product record ==

Optional record

**~*~***Is not used without agreement

(% border="1" %)

|Transaction type|1|Q| |Product record.

212

|Customer number|2|X(15)|Req|Customer number

213

|Product text|3|X|Req|Product text, see Definitions and terms

214

|Quantity|4|N(5)|Req|Number of products

215

|Unit|5|N(7),N(2-6)|Req|Price for one product, can have 2 to 6 decimals.

216

|VAT rate|6|N(7),N(2)|Req|VAT rate

217

|Product_group_Id|7|N(5)|Req|According to agreement with PayEx.

218

|From-date|8|N(8)|Req|YYYYMMDD – Date from when the product is active

219

|To-date|9|N(8)|Req|YYYYMMDD – Date from when the product no longer is active

220

|Identification_No|10|N(10)| |Id used to group statistics. Required when service Revenue Accounting is active, maximum value 2^^31^^

221

|Product_Id|11|N(10)| |Id for the product, maximum value 2^^31^^

222

|Product property 1|12|N(1)| |Property for product (0-9) ex. for grouping on invoice layout

223

|Product property 2|13|N(1)| |Property for product (0-9)

224

|Product property 3|14|N(1)| |Property for product (0-9)

225

226

Note! When service Revenue Accounting is active, the dates must be within revenue month. It is only allowed to use from- and to-date within a calendar month. Use of “Product property” field is set up in agreement with PayEx

227

228

Example on the records appearance:

229

230

**Q;12345;Football1;5;23,50;25,00;2;20180101;20181001;1;;;;

231

Q;12345;Football2;5;23,50;25,00;2;20180101;20181001;1;1234567;1;2;8**

232

233

== B - Date A -number product record ==

Optional record

**~*~***Is not used without agreement

(% border="1" %)

|Transaction type|1|B| |Product record.

242

|Customer number|2|X(15)|Req|Customer number

243

|A-Number|3|X(34)|Req|A-Number

244

|Product text|4|X|Req|Product text, see Definitions and terms

245

|Quantity|5|N(5)|Req|Number of products

246

|Unit|6|N(7),N(2-6)|Req|Price for one product, can have 2 to 6 decimals.

247

|VAT rate|7|N(7),N(2)|Req|VAT rate

248

|Product_group_Id|8|N(5)|Req|According to agreement with PayEx.

249

|From-date|9|N(8)|Req|YYYYMMDD – Date from when the product is active

250

|To-date|10|N(8)|Req|YYYYMMDD – Date from when the product no longer is active

251

|Identification_No|11|N(10)| |Id used to group statistics. Required when service Revenue Accounting is active, maximum value 2^^31^^

252

|Product_Id|12|N(10)| |Id for the product, maximum value 2^^31^^

253

|Product property 1|13|N(1)| |Property for product (0-9) ex. for grouping on invoice layout

254

|Product property 2|14|N(1)| |Property for product (0-9)

255

|Product property 3|15|N(1)| |Property for product (0-9)

256

257

Note! When service Revenue Accounting is active, the dates must be within revenue month. It is only allowed to use from- and to-date within a calendar month. Use of “Product property” field is set up in agreement with PayEx

258

259

Example on the records appearance:

260

261

**B;12345;4788743;Installationfee1;5;150,00;25,00;1;20180101;20181001;2;;;;

262

B;12345;4788743;Installationfee2;5;150,00;25,00;1;20180101;20181001;2;123456;1;2;8**

263

264

== S - Trailer record ==

Required record

(% border="1" %)

|Transaction type|1|S|Req|Trailer record.

271

|Number of records.|2|N(8)|Req|Number of records, main record and end record included.

272

273

Example on the records appearance:

**S;10**

== Example on appearance ==

278

279

**H;99999;Company AB;180919;1002

280

M;0;

281

P;sp000012;Dressing gown; 3;350,00;25,00;3;;

282

P;sp000012;Mug; 3;50,00;25,00;3;;134567

283

P;sp000302;Dressing gown; 1;350,00;25,00;3;214;

284

I;000087;0702402377;Installation: House;9;

285

I;000087;0702402377;Calculated year consumption: 24795 kWh;9;

286

I;000087;0702402377;Calculated meter reading: 000731: 28671;9;

287

A;000087;0702402377;Electricity june;992;0,129;25,00;6;147;

288

A;000087;0702402377;Energy tax june;992;0,162;25,00;6;;123456

289

Q;12345Football;5;23,50;25,00;2;20180101;20181001;1;1;2;8

290

B;12345;4788743;Installfee;5;150,00;25,00;1;20180101;20181001;212;125478;1;2;8

291

S;12**

292

293

= Definitions and terms =

294

295

Header record and Trailer record exists only once. Records of the type P, A, I, Q, K and B can exist a multiply of times for a single customer number.

296

297

The maximum length of the product text is depending on which type of invoice layout is used, and is therefore agreed with PayEx.

298

299

There are also some limitations regarding which characters can be used in the product text. See below “Characters that can not be used in product text field”.

300

301

== Characters that not can be used in product text field. ==

302

303

(% border="1" %)

304

|=**Character**|=**ASCII**|=**Function**

305

| |0|NUL

306

| |1|SOH