Version V1.10 – 01.06.2020 

V1.07 V1.08 V1.09 V1.11 V1.12

1.1 Purpose of the document

This document describes the BillingOnline interfaces. This documentation is intended to help developers of third-party systems to be able to respond to the interface with the corresponding data.

It describes the general procedure, communication at a technical level, and the XML format exchanged between the systems.

1.2 Change record

1.3 Referenced documents

1.4 The process of connecting to BillingOnline

The following steps are necessary to establish a productive connection.

1.5 Definition

A distinction between BillingOnline Internal (BOI) and BillingOnline External (BOE) is made in this documentation. BillingOnline Intern (BOI) applies to internal customers of Swiss Post (online services of Swiss Post) and BillingOnline Extern applies to external customers.

1.6 ShowCase implementation

The Payment ShowCase application was designed to test the BillingOnline solution in demo mode. It simply involves consulting a URL, as the application was created via CodePen. The advantage of this is that only the URL needs to be indicated, instead of transmitting the software itself. This is much more convenient as there is nothing to install. It offers potential customers the chance to gain an initial impression of the solution quickly and easily. They also receive instructions for integrating the payment screen into their own online shop for test purposes.

BillingOnline internal (BOI)

https://codepen.io/BillingOnline/full/rNBKByV?showCase=BOI

BillingOnline external (BOE)

https://codepen.io/BillingOnline/full/rNBKByV?showCase=BOE

BillingOnline distinguishes between client server and server server use cases.

2.1 Client server

With these use cases, the user is shown a GUI and needs to select the payment method and enter his payment data in order to conclude the payment process.

2.2 Server server

These use cases are for background payment; the user is not shown a GUI.

There is an annex (see referenced documents: [08]) with XML examples for the various use cases.

2.3 Call addresses

BillingOnline internal (BOI)

BillingOnline external (BOE)

3.1 IF1 call as a client → server

3.1.1 Payment process procedure

3.1.2 Call procedure

The following sequence diagram illustrates the communication between the systems involved.

3.1.3 Inward delivery of the data

The initialization of the payment process for the use cases executed in the client server takes place via an http POST request in which the order data is sent to BillingOnline.

3.1.3.1 Data request

The following form data must be transmitted:

3.1.3.2 Data response

BillingOnline sends back the URLs to the payment screen in the response header upon a successful inward delivery.

This URL launches the payment process in the customer’s browser.

3.1.4 Design of header section

The header section can be designed individually. The online shop logo (logoUrl, red area) is displayed left aligned and scaled to the height of the header (64 px).

The online shop logo should not be wider than 220 px to ensure the close icon (X) is untouched on mobile devices with low resolution.

The background colour of the header section is defined using the shopColor (blue section).

To ensure the logo is loaded successfully, the file size of the logo should be smaller than 50KB.

3.1.4.1 XML guiSettings

The design options should be provided via the guiSettings form field. The data is sent in the same way as the payment information to BillingOnline as xml and base64-encoded. The structure of the XML is defined via the ShopGuiSettings XSD in the annex.

All indicated information is optional. If not specified, the defined default values (hereinafter referred to as defaults) are used.

3.1.5 Displaying the payment screen

There are two options to display the payment screen, as a Javascript overlay, a type of pop-up above the online shop (suitable for single-page applications) or by redirecting the customer to the URL (for apps or as an iFrame). The call and the response after the payment process are different.

3.1.6 Overlay mode

Figure 2 displays the payment screen as a pop-up. The online shop remains partially visible in the background and the browser URL continues to be that of the online shop.

The OnlinePayment Javascript Library is embedded via a script tag in order to display the payment screen as an overlay.

Note: the following information is valid for OnlinePayment Javascript Library Version 2.0.0 and higher.

The OnlinePayment functionalities are initialized via the call by the OnlinePayment module.

3.1.6.1 Description of parameters

The following parameters are to be transmitted.

3.1.6.2 Settings object

All information is optional. If not specified, the defined default values (hereinafter referred to as defaults) are used.

3.1.6.3 Additional configuration options

The following additional configurations should only be undertaken in consultation with BillingOnline.

The attribute data-usepolyfillio is used to define whether polyfill.io is used for reasons of backwards compatibility (Internet Explorer). Should only be switched off if the website has its own polyfill mechanism for older browsers. Default: switched on for IE.

3.1.6.4 Launching the payment process

The payInOverlay() method must be called up to allow the pop-up to open.

The result of the payment process is returned in a Javascript Promise once the payment process has been successfully completed, or was cancelled. The pop-up closes automatically.

3.1.6.5 Payment response

The response object contains the following information:

Important:

Since the response comes via Javascript, this is easy to falsify by the user.
This is why the data object must always be evaluated on a server side in the event of a successful payment, and the validity of the signature must always be verified.

The redirection URLs defined in the XML have no influence in overlay mode during the payment process.

3.1.7 Redirect mode

3.1.7.1 Launching the payment process

The payment process can also be launched without overlay/Javascript library. This involves loading the URL generated by BillingOnline in the customer’s browser (via redirect).

3.1.7.2 Payment response

Once the payment transaction is concluded, the user is redirected to one of the dynamically provided redirection addresses within “Payment Request” (redirectionurls) (HTTP POST). If an error occurs, the URL parameter ErrorCode is attached; if successful, the processed XML is returned.

3.1.8 Asynchronous payment response

An asynchronous confirmation is also sent by BillingOnline to the customer shop alongside the synchronous confirmation. This is done as a POST request to PostbackURL (must be indicated in the activation form).

The data returned here is identical to that contained in the synchronous response.

The asynchronous confirmation ensures that a response also takes place if the user closes their browser during transaction confirmation.

A POST request is only sent to PostbackURL in the event of a successful payment transaction.

In addition to the redirection addresses (redirectionurls), BillingOnline also requires a PostbackURL to generate an asynchronous payment confirmation for a successfully completed payment transaction, as well as a FallBackMail from the online shop (e.g. a support e-mail address from the online shop, do not use personal e-mail accounts) to which an e-mail can be sent if the online shop does not provide a payment confirmation for a successfully completed payment transaction.
Both sets of information are defined in the activation form and managed by Post CH Ltd within the central online shop configuration.

Below is an example of a FallBackMail:

From: noreply 
Sent: Day of week, DD. Month YYYY hh:ss
To: e.g. Online shop’s support e-mail address
Subject: PaymentService Postback failed for ID {OrderId of the order}

Hinweis: Die Bestellung mit der Nummer im Betreff konnte nicht perPostback bestätigt werden.
Remark: The order with the ID in the subject line could not be confirmed from our postback.
Attention: La commande avec le numéro indiqué dans l’objet n’a pu être confirmée par le postback.
Commento: L’ordine con il numero nell’oggetto non può essere confermato via postback.

Please do not reply to this email.

3.1.9 Session timeout

The session times out if there is no successful payment conclusion within a certain time parameter (default 30 min.) from the time an Order XML Request is transmitted by an online shop.

If the payment process times out, the payment screen is “blocked” and the shop customer is unable to perform any further actions in the payment process.

The shop customer is shown a pop-up saying “Please wait. Your data is being processed”.

Verification then takes place to ascertain whether it was still possible to correctly process a payment process that has been completed but coincides with the session timeout.

If yes, a pop-up appears stating “The payment was processed successfully! You will be forwarded automatically to the online shop.”.

If no, a pop-up appears stating “We’re sorry but an error occurred. The payment could not be processed. Please restart the payment process. You will be forwarded automatically to the online shop.”.

3.2 Call as server → server

The background payment process call for the server server use cases (see Server Server) takes place by means of an XML request via the IF1 interface (server → server call).

3.2.1 Payment process procedure

No payment screens are needed in server server mode; the payment process is performed in a call and the response (XML) takes place directly in the response stream.

3.2.2 Call procedure

The following sequence diagram illustrates the communication between the systems involved.

3.2.3 Payment request

3.3 IF1 monitoring

The following URL is available for testing whether the IF1 application can be reached:

Integration https://app-test.swisspost.ch/VPSPayment/Heartbeat.aspxTarget not accessible

Production https://app.swisspost.ch/VPSPayment/Heartbeat.aspxTarget not accessible

4.1 Definitions

The requests for all IF1-CS and IF1-SS use cases are based on the XSD schema billingonline-if1.xsd [04]. The definitions are defined via the following XSD files:

4.2 Description of XML file

The following table shows an excerpt of the most important attributes, and describes the purpose and values capable of accepting a relevant attribute in the IF1 XML file. All possible values are stored in the XSD schema:

4.3 Identification of customer type

In order to identify a customer type, an online shop needs to record the customer type in the IF1 interface (billingonline-if1.xml) in the node ssouser/ssostate in accordance with the overview below.

In addition to identifying the customer type, an online shop also needs to comply with the minimum conditions in the IF1 interface (billingonline-if1.xml) for filling the XML request in accordance with the overview below.

For the elements marked *, no placeholders (e.g. space, -, etc.) can be used!

Communication and thus handover of the XML-IF1 to BillingOnline takes place via a secure connection (HTTPS, Hypertext Transfer Protocol Secure). 

During the setup process BillingOnline will provide the Certificate that has to be used for signing (IF1) and authentication (IF2). In this case Post CH Ltd will act as a Certificate Authority and provide the customer a client certificate including the private/public-key pair. See section 5.4 “Acquiring the client certificate”. 

BillingOnline is not accessed via browser for the use cases UC5, UC6 and UC7 (direct payments via IF1-SS), but directly from the online shop server.

No additional measures are required here concerning the security. The signature using the client certificate facilitates authentication.

The digital signature used in this interface satisfies the specifications for signing and verifying XML published by W3C (http://www.w3.org/TR/xmldsig-core/Not AccessibleNot AccessibleTarget not accessible).

There are three variants of XML signature.

In this interface, the enveloped variant is used for the signature. The XML to be signed forms the root and the signature element is embedded at the very bottom.

The official xsd schema regarding the structure is available online via the following URL: http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/xmldsig-core-schema.xsdTarget not accessible.

5.1 Certificate

The X509 certificate must also be provided with the signature to ensure the signed XML can also be validated by the other side. In the element Signature/KeyInfo/X509Data/X509Certificate, this is inserted in Base64 encoded form.

5.2 Timestamp property

The structure of the signature makes it possible to provide all kinds of information in addition to the signature using so-called SignatureProperties (an object such as http://www.w3.org/2000/09/xmldsig#SignaturePropertiesTarget not accessible).

More often than not, the timestamp of the signature creation is defined as a SignatureProperty. This only allows requests to be accepted whose signature is no older than 10 minutes.

This is why the timestamp SignatureProperty is defined as mandatory. The lack of this element is considered to be an invalid signature and is returned as an error.

5.3 Note on signing with PHP

If PHP creates the XML signatures invalidly, the following workaround can be used:

1. Create the XML using DOMDocument
2. For KeyInfo and X509 Data PHP Library, use xmlseclibs (https://github.com/robrichards/xmlseclibsNot AccessibleTarget not accessible)
3. Save the XML temporarily
4. Using Linux, the certificate can be signed using the library “xmlsec1”. (Installation of the library via “apt-get install xmlsec1”)

This last point can be achieved in various ways:

Signing using a .pem file leads to an error. However, the .pem can be converted to a .p12 using the following command to allow signing.

5.4 Acquiring the ClientCertificate

As part of the setup process BillingOnline will provide the necessary certificate including the corresponding private/public-key pair, which has to be used to sign/verify XML-requests as described in this chapter (5).

You will receive the following files via secure IncaMail message:

• .crt
• .p12
• .key
• .p12pwd.txt

The file named “XXX.p12pwd.txt” contains the passphrase protecting the provided .p12 file.

All provided files are PEM-encoded with base64 encoded content, if the system in use requires a certificate in a DER (binary) format use OpenSSL to change the format accordingly:

Using the same method, the DER (binary) formatted certificate can also be generated as a .der or .cer file by changing the file extension of the output in the command above.

Similar to the format change above, the provided .p12 file can be used to generate a .pem certificate-file (which also contains both the private key and the certificate) if needed.

Use the following command:

The source of the OpenSSL precompiled binaries for Windows can be found here: https://indy.fulgan.com/SSL/

After successfully transmitting the files, BillingOnline will only store the .crt-file and delete all other files. It is therefore the customers’ sole responsibility to safely store the certificates and the corresponding keys. Both the p.12 and the .key file contain the private key.
The certificate is valid for 5 years. Managing the certificate is the customers’ responsibility.

6.1 Credit card details

The following test credit card numbers are available on the integration platform.

Brand: Visa

Brand: Master

Brand: Amex

The credit card data can be added by clicking via an add-on in Google Chrome https://chrome.google.com/webstore/search/flexcheckout?hl=en.

6.2 PostFinance payment methods

PostFinance has no test data for the payment methods PostFinance PostCard and PostFinance E-Finance for tests on the integration platform (PostCard ID number, PostCard card number, E-Finance number).

Only simulators provided by PostFinance for which no test data needs to be entered can be used on the integration platform for PostFinance payment methods.

6.3 TWINT

To install the TWINT App (Prepaid) on iOS and Android devices, TWINT recommends that its configurator be installed on the mobile device in advance, which can used to install the correct TWINT app.

Please use the latest version of Twint (you can use the QR codes below).

Open QR code on mobile device

iOS

Android

Further guidance can be found in Annex 13 TWINT Configurator App guide.pdf

Test credit codes are available for charging the prepaid credit to the TWINT App.

Test credit codes can be requested by e-mailing product-billingonline@post.ch.

BillingOnline provides the option of automating the process in the event of recurring activations. This involves sending in the data via CSV.

The parameters which must be transmitted are defined in the activation project. However, no rows may be deleted. If unused, these should be left empty.

Onboarding process (csv) rules:

BillingOnline offers an SOAP-based web service for the IF02 interface.

8.1 Transport and security

Communication with the BillingOnline BillingMachine (billing system) takes place using a SOAP-based web service via HTTPS (secured connection).
A client certificate is also transmitted at a transport level as an additional security element. Use of webservice security (WSS) is avoided to keep complexity under control.
Transmission of the client certificate takes place upon each web service access and serves to authenticate the accessing online shop.

Some methods can be accessed by all partner systems (public) while others require a higher permission level (admin). For more details see chapter 9.

The client certificate is issued by Post CH Ltd. The information for obtaining the client certificate can be found in this integration guideline, section 5.4 “Acquiring the client certificate”.

8.2 Roles concept

The online shop authenticates itself via the certificate. Authorization takes place via the roles assigned to the online shop certificate. Methods are assigned to each role. One or several roles can be assigned to a certificate:

8.3 WSDL file

The WSDL file includes additional xsd schemas which on the one hand define the method signatures and on the other, the data structures to be transferred. These definitions are provided in the form of files during the implementation phase.

BillingOnline Intern (BOI)

BillingOnline Extern (BOE)

The following section describes all the available web service methods. Individual methods may result in the return of an error code or SOAP exception.

An error code is returned in foreseeable cases of error (see error code table section 3 Overview of error codes). However, an SOAP exception is reported in the event of technical errors or non-permissible access.

There are a small number of methods which sometimes define optional handover parameters. These are presented in italics in the tables. The characteristic is also shown in bold in the description field.

9.1 Public methods

9.1.1 ExecutePing

BillingOnline provides a ping method for test purposes. This enables a connection test to be performed between BillingOnline and the online shop during start-up.

Communication takes place by means of SOAP via HTTPS using client authentication. Each request must include the issued certificate.

Method

BillingService.ExecutePing

Description

This service checks the connectivity of the BillingOnline service for the BillingOnline BillingMachine (billing system).

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.2 CheckAlias

Method

BillingService.CheckAlias

Description

Querying the status of a stored debit/credit card.

The query is performed using the ssoId key.

Provides the alias status, the alias card number in the format XXXXXXXXXXXX0002, the expiry date and the brand of debit/credit card.

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.3 GetAccountSaldo

Method

BillingService.GetAccountSaldo

Description

Querying of the current balance of a customer account type by the online shop.

The query is performed using the ssoid key.

The output is always the forecasted balance.

I.e. the balance contains all bookings with the statuses “settled” and “deferred”.

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.4 ListAccountStatement

Method

BillingService.ListAccountStatement

Description

Querying of the account statement of a customer account type by the online shop.

The query is performed using the ssoid key.

A maximum of 200 transactions are returned by the query.

If no date range is returned, the response provides the last ten transactions.

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.5 ListExpiringCreditCards

Method

BillingService.ListExpiringCreditCards

Description

Querying of all stored credit/debit cards whose validity expires at a certain time (MM/YYYY).

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.6 ListOrderInfo

Obsolete since the returned value SalesAccount is of an incorrect type: “Int”. ListOrderInfo2 should be used.

9.1.7 ListOrderInfo2

Method

BillingService.ListOrderInfo2

Description

Querying of an order using individual order items (LineItems).

The query is performed using the orderId key.

SalesAccount has been changed from type “Int” to “String”. As a result, ListOrderInfo has been renamed ListOrderInfo2

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.8 ListOrderStatement

Method

BillingService.ListOrderStatement

Description

Querying of an order using individual order items (LineItems).

The query is performed using the ssoId key.

Role

Read

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.1.9 DeleteOrder

Method

DeleteOrder

Description

Deletion of an existing booking that has deferred status in billing and cancellation of the reservation on the payment method.

The e-shop reports the OrderID. The order and its LineItem are only deleted if the status is deferred (i.e. no value stream-relevant bookings have yet been executed in the billing system).

Role

write

Input

Output

Exception

SOAP-Exception: Technical error affecting WS interface

Error Code

9.1.10 ConfirmDelivery

Method

BillingService.ConfirmDelivery

Description

Notification of the proof of delivery (after goods dispatch) by the e-shop to BillingOnline.

The e-shop reports the OrderID and LineItemID. The deferred status of the relevant booking is changed to settled (book immediately).

The change is performed using the OrderID_LineItemID key.

Role

Write

Input

Output

Exception

SOAP exception: Technical error affecting WS interface

9.2 Admin Methods

9.2.1 AddCreditBooking

Method

BillingService.AddCreditBooking

Description

Recording of credit to an existing order (using the existing orderId, new lineItemId and booking text).

The query is performed using the orderId key.

Role

Write

Input

Output

Exception

The method AddCreditBooking is excluded for following usecases:

• several payment methods (split payments)
• Payment type vouchers (personnel vouchers, gift vouchers) 

In the above mentioned usecases please send an e-mail to the contractually agreed support email address with following parameters.

• Order number (orderid): O###1474039639###
• Order date (orderdate): 2016-09-16T17:27:19
• Last name: Example
• First name: Hans
• Total amount of order: CHF 1000.50
• Street / house no.: Example street 20
• Postcode / Town: 3030 Berne

SOAP-Exception: Technical error affecting WS interface

Error Code

Detailed Error Code

9.2.2 AddDebitBooking

Method

BillingService.AddDebitBooking

Description

Recording of a subsequent debit (fee) on an existing order (using the existing orderId, new lineItemId and booking text).

The query is performed using the orderId key.

Role

Write

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

Information

9.2.3 DeleteAlias

Method

BillingService.DeleteAlias

Description

Deletes a customer’s alias (ssoId) and sets the alias status to “NotSet”.

The query is performed using the ssoid key.

Role

Write

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

9.2.3 SetAliasState

Method

BillingService.SetAliasState

Description

Deletes a customer’s alias (ssoId) and sets the alias status to the returned value in “aliasState”. 

The query is performed using the ssoid key.

Role

Write

Input

Output

Exception

SOAP exception: Technical error affecting WebService interface

10.1 IF1 error codes

The error code table not only applies to the XML structure under envelope/confirmation, but is also valid for the error codes returned via redirect to declineurl to the online shop. Only in the use cases 05, 06, 07 and 08 (server -> server) are they contained in the XML structure; or if the error message is more of a notice but the payment could still be performed. Error messages shown to the user do not contain any detailed information. They let the user know how they should/can proceed.

Error codes 21–5x concern dependencies that cannot be captured through the schema. These are conditions that are evaluated by additional business logic.

10.2 IF2 error codes

The BillingOnline sales reports are generated and transmitted monthly. You decide what data is submitted by your online shop. BillingOnline will then export it in consolidated form. The reporting is supplied in CSV format. The CSV format means that the file can be input automatically into all common accounting systems for cross-checking of the online shop data.

The following table provides a summary of the data that can be generated in CSV format. You decide what to include.

Contents

In the report, individual or several values can be set as inactive, depending on customer’s wishes. These values will not be sent in the report.

* Currently available only for BillingOnline external(BOE).

Format

CSV (for further automated or manual processing in Excel)

Frequency

monthly

Transmission type

E-mail or storage in FTP account

You can contact us as follows for any questions you may have:

Tel. +41 848 45 66 78
CHF 0.08/min. from Swiss landlines
Availability: Monday to Friday: 8 a.m. to 6 p.m.

E-mail product-billingonline@swisspost.ch

Documents BillingOnline (ZIP, 2.5 MB)