Bicus2

Below diagram shows the structure of Bicus in current version

Encoding

Name convention

Bicus2_<CompanyNumber>_<DateTime>_<SerialNumber>.xml

Names Component	Description
CompanyNumber	The company number in our ledger system
DateTime	Date created, Should be in the format  ISO 8601 format, YYYYMMDDThhmmss
SerialNumber	Should follow an not broken number series, 00001, and so on.

General information and explanation of records

Bicus is used to submit end-user information as well as definitions of deviation products to the PayEx Billing System.

Bicus is divided in two parts of information,  DeviationInfo and BicusInfo.

BicusInfo contains the end customer's customer information, all of the customer's subscriptions and products to be processed in Billing.

Benefits for the use of the Bicus file format:

• Bicus XSD validation on the sending system.
  • Input data and XML errors can be stopped before sending
• The PayEx Billing System processes and stores all correct customers. Incorrect customers will be returned in a detailed response file.
  • Firms can choose to start billing for all customers that are correct in the PayEx Billing system
• Processing Bicusfiles can be scheduled 24/7 and response files will be delivered immediately after processing Bicusfiles

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.

Implementation

Implementation of Bicus requires a complete file with all customers. Otherwise it is sufficient to only send updated customers.

Limitations

Each BiCus file can have a maximum of 50 000 BiCusInfo elements.
DeviationInfo only needs to be send when there are new deviation products and updates of existing deviation products.

BicusInfo

Handling of elements in BicusInfo

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.

The idea is that the sending party sends a total snapshot of a customer’s data to be processed in the Billing System.

Non mandatory elements

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.

All data to be processed per new or updated customer has to occur in the latest processed Bicusfile.

Mandatory elements

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.

Customer information

This element is mandatory.

CustomerStatus

The element CustomerStatus is used to disable and delete the end customers in the Billing System.

The requirement to inactivate a customer is that the customers subscriptions are not active and that all products and usage has been billed.

Existing customers and new customers should have the default value “Active”.

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.

Regnumber

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

LanguageCode

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.

PaymentInfo

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.

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.

CustomerProduct

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.

Restriction invoice period of recurring products

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

Subscription

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

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

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.

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.

Generic subscription

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.

DeviationInfo

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.

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.

Handling of elements

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.

Version handling

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

Version handling with example

Step	Action	Effect
1	Reading product: AVVPR, version 2015-01, price 1kr, description ”Monthly fee A1”	New product AVVPR in the system, price 1kr valid from 2015-01. description ”Monthly fee A1”
2	Reading product: AVVPR, version 2016-01, price 2kr, description ”Monthly fee A2”	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”
3	Reading product: AVVPR, version 2016-01, price 3kr, description ”Monthly fee A3”	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”
4	Reading product: AVVPR, version 2015-01, price 0,50kr, description ”Monthly fee A4”	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”

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.

Response files

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.
For both CustomerInfo and DeviationInfo a responsefile will be produced.
If the firm doesn´t use DevationInfo no response file regarding deviations will be returned.

BicusResponse file with exampels

Download current XML schema file

Fileversion	Version	Releasedate	Comment
Bicus[2.0.0].xsd	2.0.0	2018-04-01	Initial version

ChangeLog