BillingOnline Integration Guidelines



Language navigation

BillingOnline Integration Guidelines

Close

    BillingOnline Integration Guidelines

    Version V1.09 – 13.05.2020

    V1.07 V1.08 V1.10

    1. Introduction

    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

    Version Release Revision Date
    1.00 2.10.0 New document 27.08.2018
    1.01 2.10.0 Adjustment to the call address 04.10.2018
    1.02 2.10.1. Adjustment to the call address 
    New XSD schema / backwards compatible with RE 2.9.1
    19.11.2018
    1.03 2.10.2 New implementation method, new OnlinePaymentLibrary, Google Chrome add-on 05.12.2018
    1.04 2.10.4 Revision of BillingOnline call 07.01.2019
    1.05 2.10.9 ThreatMetrix removed, update to OnlinePaymentLibrary 01.05.2019
    1.06 2.10.9 Review and merging of IF1 & IF2 guidelines 27.06.2019
    1.07 2.11.2 Implementation of method DeleteOrder and removal of
    DeleteBooking
    Adjustment Umsatzreport
    Adjustment Aufrufadressen
    14.11.2019
    1.08 2.12.5 Implementation of Showcase 05.03.2020
    1.09 2.12.6 Update content concerning certificates 13.05.2020

    1.3 Referenced documents

    No. Description Version / release
    [01] BillingOnline activation form  1.0.0 Release 2.10.0
    [02] XSD schema IF1 (billingonline-if1.xsd) 2.0.9 Release. 2.10.1
    [03] OnlinePaymentLibrary 1.0.5. Release 2.10.9
    [04] XSD schema ShopGuiSettings (ShopGuiSettings.xsd) 1.0.0 Release 2.10.1
    [05] XSD schema Timestamp (TimeStampProperty.xsd) 1.0.0, 19.05.2009
    [06] XSD schema Signature (SignatureProperties.xsd) 1.0.0, 13.05.2009
    [07] XSD schema Core Signature (xmldsig-core-schema.xsd) 1.0.0, 21.05.2009
    [08] Annex 01: IG-IF1 Use Cases – XML examples 1.0.0. Release 2.10.0
    [09] csv Onboarding Process 1.0.0. Release 2.10.0
    [10] Certificates 1.0.0. Release 2.10.0
    [11] Icons PaymentTypes 1.0.0. Release 2.10.0
    [12] TWINT Configurator App guide.pdf 1.0.5 Release 2.10.9

    1.4 The process of connecting to BillingOnline

    The following steps are necessary to establish a productive connection.

    No. Tasks
    1 Defining of the desired use cases
    2 Filling in of the activation form
    3 Generation of csr and ordering of certificate
    4 Configuration of the integration platform
    5 Implementation of call without signing (certificate)
    6 Implementation of call with signing (certificate)
    7 Performance of tests and approval on integration platform
    8 Configuration of the production platform
    9 Performance of tests and approval on production platform
    10 Go-Live (incl. productive tests)

    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

    2. IF1 Use Cases

    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.

    Abbreviation Name (use case) Description
    UC1  PaymentAnonymOrTrial Payment process for an anonymous customer
    UC2 PaymentAuth  Payment process for a registered customer
    UC3  ChargeWalletAuth  Topping up the E-Wallet (credit account)
    UC7R  CreateAliasAuth  Storing a credit/debit card

    2.2 Server server

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

    Abbreviation Name (use case) Description
    UC5 DirectPaymentAuth Background payment via the E-Wallet account
    UC6 DirectPaymentESRAuth  Background payment by invoice
    UC7  DirectPaymentCardsAuth  Background payment using the stored credit card

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

    2.3 Call addresses

    BillingOnline internal (BOI)

    Description URL
    Integration https://billingonline-int.post.ch/onlinepayment/web/v1/boi/xmlinterface
    Production https://billingonline.post.ch/onlinepayment/web/v1/boi/xmlinterface

    BillingOnline external (BOE)

    Description URL
    Integration https://billingonline-int.post.ch/onlinepayment/web/v1/boe/xmlinterface
    Production https://billingonline.post.ch/onlinepayment/web/v1/boe/xmlinterface

    3. Procedure

    3.1 IF1 call as a client → server

    3.1.1 Payment process procedure

    No. Description
    01 An anonymous or registered user (shop customer) performs an order in an online shop and wants to perform the payment process for his online order.
    02 The online shop signs the XML digitally using the customer data and order data. The digitally signed XML is transferred to BillingOnline.
    BillingOnline checks the validity of the digital signature, authenticates the online shop, and validates the transferred transaction data in XML.
    The online shop receives a URL as a response to start the payment process.
    03 The URL is opened in the customer’s browser.
    04 The BillingOnline payment screen is shown. This displays the desired payment method (debit/credit cards, TWINT, invoice, vouchers, credit) and the customer performs the payment. 
    05 Once the payment is successfully completed, BillingOnline generates a digitally signed response XML which is reported back to the online shop via the browser.
    06 The digitally signed response XML is reported back asynchronously to the online shop as a backend process (server server) in addition to the synchronous response.

    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.

    Call method https (Swiss Post)
    Interface specification billingonline-if1.xsd (see XSD schema [04])
    Authentication The shop is authenticated by verifying the signature of the XML.
    For details on the signature, see section 1.2 Referenced Documents Annex 10 Certificates and section 4 Transport and Security.
    The raw XML data is UTF-8 encoded. 
    Confirmation request HTTP status code: 302, Found
    - The URLs for launching the BillingOnline payment screen (see URLs to launch the payment screen) are returned.
    (If the Swiss Post request was made directly from the customer’s browser, the BillingOnline payment screen launches automatically)
    Return in the event of error HTTP status code: 302, Found
    Redirect to online shop via declineurl
    A query parameter with error number (ErrorCode=XX) is attached to the URL.
    E.g. http://e-shop.ch/errorpage.html?shopspecific=xy&ErrorCode=01
    For error codes 1–20, this is only possible if the <shopid> parameter has been successfully transmitted.
    HTTP Status Code: 400, Bad Request
    This event can occur if the XML file is not compliant with the schema and if the shopId parameter has also not been transmitted, or has been transmitted incorrectly.
    (If the Swiss Post request was made directly from the customer’s browser, the customer is shown a general error page)
    3.1.3.1 Data request

    The following form data must be transmitted:

    Form field Type Description
    shopId String Shop ID
    (Mandatory field)
    data String base64-encoded XML with the payment order details, 
    See XML documentation
    (Mandatory field)
    guiSettings String base64-encoded XML with the graphical settings for the payment screen
    See Design of header section
    (Optional)
    3.1.3.2 Data response

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

    Header field Description
    x-billingonline-url Absolute URL to the payment screen
    E.g. https://app.swisspost.ch/OnlinePayment/web/v1/boe/XmlInterface/ui/SHOP-XY/ee1cb435-ec4f-439a-bes2-815e8ac06b22
    Location Relative URL to the payment screen (relative due to reasons of backwards compatibility)
    E.g. /XmlInterface/ui/SHOP-XY/ee1cb435-ec4f-43sa-beb2-815e8ac06b22

    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.

    Name Type Description
    shopColor String
    Background colour of the header section, hexadecimal
    Example: #f7c32d
    Default: #ffffff (white)
    logoUrl String (Url) LogoUrl of the online shop, which must be accessible via https.
    Permitted image formats: JPG, PNG, GIF, SVG
    Example: https://myshop.com/images/logo.pngNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot AccessibleNot Accessible
    Default: Post CH Ltd logo
    Important:
    The URL must be encoded!
    Incorrect: https://www.post.ch/my lögö.png
    Correct: https://www.post.ch/my lögö.png

    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.

    Referencing the library

    <script type="text/javascript" src="Scripts/OnlinePaymentLibrary-1.0.4.min.js" 
    data-id="BillingOnline"> 
    </script>

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

    Initialization of the library

    var onlinePayment = OnlinePayment("SHOP-ID", endpointUrl, settings);
    3.1.6.1 Description of parameters

    The following parameters are to be transmitted.

    Name Type Description
    ShopId String The ShopId prescribed by BillingOnline
    EndpointUrl String (Url) The URL sent back by BillingOnline after initialization of the payment order.
    Settings Javascript object For additional configuration options, see the table below
    3.1.6.2 Settings object

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

    Name Type Description
    shopColor String Colour of the loading icon, hexadecimal
    Example: #f7c32d
    Default: #ffcc00
    enableLog boolean If true, information on the payment screen structure is outputted.
    This should be switched off in the productive environment.
    Default: true
    enableTrace boolean If true, trace information on the payment screen structure is outputted.
    Should only be set to true if there are problems with the integration of the payment screen.
    Default: false
    resetElementFocus boolean If true, the focus after the payment process is placed again on the element, which was previously active in the online shop.
    Default: true 
    inertElements boolean If true, all controls in the background of the payment process will be deactivated for accessibility reasons.
    Only the elements of the payment screen can be focussed on and reached using the TAB key.
    Default: true
    3.1.6.3 Additional configuration options

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

    Referencing the library

    <script type="text/javascript" src="Scripts/OnlinePaymentLibrary-1.0.4.min.js"
    data-id="BillingOnline" data-usepolyfillio="true">
    </script>

    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.

    Payment process

    var overlayPayment = OnlinePayment(shopId, targetUrl, settings);
    
    overlayPayment.payInOverlay().then(function (paymentResponse) {
        console.log('Promise resolved');
        console.log('The errorCode: ' + paymentResponse.errorCode);
        console.log('The base64 encoded XML: ' + paymentResponse.data);
        console.log('The errorMessage: ' + paymentResponse.errorMessage);
        console.log('FullResult: ' + JSON.stringify(paymentResponse));
    }).catch(function (err) {
        console.log('Promise rejected: ' + JSON.stringify(err));
    });
    3.1.6.5 Payment response

    The response object contains the following information:

    Name Type Description
    errorCode Int 0 = Payment was successful, otherwise the error codes apply as per section 5.5
    errorMessage String Technical, English detailed description for the error code
    data String The base64-encoded XML sent to BillingOnline.
    If the payment is successful, this features the node confirmation in which the payment details can be found.
    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.

    Call method https (Swiss Post)
    Interface specification billingonline-if1.xsd (see XSD schema [04])
    After successful payment The signed XML is transmitted in the form field <data> (base64 encoded) to the accepturl.
    For details on the signature, see section 4 Transport and Security.
    The raw XML data is UTF-8 encoded.
    After non-successful payment Redirect to online shop via declineurl, basketurl or cancelurl
    A query parameter with error number (ErrorCode=XX) is attached to the URL.
    E.g. http://e-shop.ch/errorpage.html?shopspecific=xy&ErrorCode=01

    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.

    Call method https (Swiss Post) 
    Interface specification billingonline-if1.xsd (see XSD schema [04])
    After successful payment The XML data is either signed directly as an https POST request in RequestStream (base64-encoded) and sent to PostbackURL, or sent signed as an attachment via e-mail if the POST request fails.
    It is mandatory for the signature to be verified to ensure that the data comes from BillingOnline.
    For details on the signature, see section 1.2 Referenced Documents Annex 10 Certificates and section 4 Transport and Security.
    The raw XML data is UTF-8 encoded.
    content-type: text/xml
    content-encoding: base64
    Response analysis In the event of transmission via https POST, BillingOnline only assumes processing has been successful if the online shop returns the following http header variable with the corresponding value in its https response: Payment-confirmation: accepted
    The online shop must confirm the call using the http header variables.
    BillingOnline considers all other cases as errors and attempts to transmit the response up to five times (predefined time sequence of attempts: 3 sec., 10 sec, 30 sec, 5 min, 1 hour).
    If the https response is not confirmed by the online shop (Payment-confirmation: accepted), a one-off e-mail with a signed XML response is sent to the online shop’s FallBackMail (as entered in the activation form) after five attempts.
    Timeout During transmission, BillingOnline assumes that the customer shop will process the asynchronous call within 30 seconds. If this is not the case, the attempt will be classified as erroneous.

    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.

    No. Description
    01 A) A registered customer (shop customer) either has a registered credit card, is able to pay on invoice or has E-Wallet credit. In this case, the payment process can be performed by BillingOnline without a GUI.
    01 B) A background process (e.g. charging of monthly subscription fees) triggers charging for a registered customer.
    02 The payment process can be performed using a call and the customer’s account (credit, invoice, credit card) is charged.

    3.2.2 Call procedure

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

    3.2.3 Payment request

    Call method https (post) 
    Interface specification billingonline-if1.xsd (see XSD schema [04])
    Transmission method The signed XML is transmitted as an https POST Request in RequestStream (base64-encoded) to BillingOnline.
    For details on the signature, see section 4 Transport and Security.
    The raw XML data is UTF-8 encoded.
    content-type: text/xml
    content-encoding: base64
    Authentication Authentication is undertaken using the signature.
    As this was created using the client certificate issued by Post CH Ltd, which itself is embedded in the signature, no client certificate needs to be provided at a transport level.
    Response HTTP Status Code: 200, OK
    Return of the signed XML directly in Response Stream. The returned response on its own does not yet state whether the transaction has been successful. Doing so requires analysis of the node envelope/confirmation.
    In the event of OK, the transactiondate node contains a value and the errors node is empty.
    The nodes ewalletamount, paymentamount and vouchers contain the values for the transferred payment amounts.
    The paymentid establishes the relationship to the payment service provider and is filled in solely for payments using third-party provider cards.
    The orderid corresponds to the order’s unique key and can be used for transaction control in third-party systems.
    Timeout If BillingOnline does not provide a response after 30 seconds, the attempt must be considered erroneous.

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

    Production https://app.swisspost.ch/VPSPayment/Heartbeat.aspx

    4. XML documentation payment order

    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:

    Name Contents
    billingonline-if1.xsd Contents of XML IF1-CS and IF1-SS 
    SignatureProperties.xsd Signature properties for XML IF1-CS and IF1-SS
    TimeStampProperty.xsd Signature timestamp of XML IF1-CS and IF1-SS
    xmldsig-core-schema.xsd Signature for XML IF1-CS and IF1-SS

    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:

    Name Contents
    header For identifying the desired “use case” and the necessary “action”
    E.g. <header usecase="PaymentAuth" action="Request">
    attr: usecase IF1 client server use cases
    PaymentAnonymOrTrial 
    PaymentAuth 
    ChargeWalletAuth 
    CreateAliasAuth 
    IF1 server server use cases
    DirectPaymentAuth
    DirectPaymentESRAuth
    DirectPaymentCardsAuth
    DirectCreditDecisionAuth
    attr: action Request (online shop: always request), response (Post CH Ltd: always response)
    header/shop/shopid Serves to uniquely identify the accessing online shop
    header/shop/parameter Via the XML interface, an online shop has the option of submitting all types of parameter, e.g. a transaction number or session identification.
    These are then returned to the online shop in an identical form in the response.
    header/shop/redirectionurls The redirection addresses (redirectionurls) transmitted in XML-IF1 must be provided by the accessing service to enable an online shop to perform a payment transaction.
    The redirection addresses are used as follows:
    accepturl Redirect after successful completion of a payment
    cancelurl Redirect upon a manual cancellation of the payment process by the customer
    declineurl Redirect upon a logical error in the payment process
    Details on the error codes can be found in the error code table in section 10. Overview of error codes
    basketurl Redirect upon manual navigation to the online shop’s shopping basket by the customer
    header/format E.g. <format languagecode="DE">attr: languagecode
    attr: languagecode Identification of the desired language version of the interactive payment process (DE, FR, IT, EN)
    body/ssouser Detailed information of a registered customer
    attr: languagecode Identification of the language of a registered customer (DE, FR, IT, EN)
    ssoid Unique identification of a registered customer
    emailverification Pending, Verified, Expired, ReverificationPending, Required, NotRequired
    geovalidation false (0), true (1)
    locked false (0), true (1)
    cancelled false (0), true (1)
    adrverification Pending, Verified, Expired, ReverificationPending, Required, NotRequired
    authenticationlevel Identification of a registered customer via authenticationlevel 
    (See section 4.3 Identification of customer type).
    The possible identifications are:
    EmailVerified
    NotValidated
    GeoValidated
    AdrVerified
    businesscustomer May only be used in consultation with Post CH Ltd
    attr: creditworthinesscheck For whitelist business customers for whom no creditworthiness check is required, the value must be set to “false”.
    attr: creditlimit If no credit limit is provided, the credit limit usually stored for the online shop in ShopConfig in parameter “ESRB2BMaxLimit” is verified.
    Assigning a credit limit is the responsibility of the online shop since the receivable will be charged to the online shop once the collection handover time has been reached (the online shop is responsible for its own collection).
    body/order Detailed information on an order
    attr: bookingtype bookingtype: Immediately
    Must generally be used for the following use cases:
    UC01: PaymentAnonymOrTrial 
    UC02: PaymentAuth 
    UC05: DirectPaymentAuth
    UC06: DirectPaymentESRAuth
    UC08: DirectCreditDecisionAuth
    bookingtype: Deferred
    May only be used for the following use cases:
    UC07R: CreateAliasAuth 
    UC07: DirectPaymentCardsAuth
    The identification applies to all use cases except ChargeWalletAuth.
    E.g. <order bookingtype="Immediately" currency="CHF">
    attr: currency As a general rule, only the CHF currency may be used
    orderid Order number, unique identification of an order 
    orderdate Order date which may not be in the past
    lineintems Identification of order items
    lineitem Detailed information on an order item
    attr: type Debit (money debited), credit (money credited, discount)
    E.g. <lineitem type="Debit"> / <lineitem type="Credit">
    lineitemid Unique identification of an order item which must be greater than 0 and no greater than 999999999
    E.g. <lineitemid>1</lineitemid>
    quantity Number of units per order item (used together with priceinctax to check the amountinctax, quantity * priceinctax = amountinctax)
    The number of units is shown on the invoice.
    tax VAT rate in %, from 1 January 2018 in accordance with VAT adjustment of 7.7%
    E.g. <tax>8.0</tax>
    priceinctax Unit price of an order item including VAT.
    The unit price must be rounded to two decimal places.
    amountinctax Total amount of an order item including VAT.
    The total amount of an order item must match the result from “quantity” multiplied by “priceinctax”.
    The total amount of an order item must be rounded to two decimal places.
    orderamount Total amount of an order.
    The total amount of an order must match the sum of all “lineitem” amounts (amountinctax).
    The total amount of an order item must be rounded to two decimal places.
    body/chargewallet Detailed information on charging an EWallet
    Can only be used for the use case ChargeWalletAuth
    attr: currency As a general rule, only the CHF currency may be used
    E.g. <chargewallet currency=“CHF”>
    chargewalletid Order number, unique identification of a charge (same as orderid)
    amount Desired charging amount
    The charging amount can provided pre-filled or as 0.
    body/payment Detailed information on a payment
    purpose Can be seen on the ESR invoice.
    Adopt the purpose from XML, if standard text is empty in the user language: “Your purchase [orderid] from [date]”
    Otherwise, the text supplied by the shop will be stored in Billing (limited to 50 characters).
    displayedmethods Display information
    Can be used to limit the display of the agreed payment methods (in the central online shop configuration under Payment/PaymentMethods) on the payment page of BillingOnline.
    paymentmethod The standard payment methods agreed with an online shop (in the central online shop configuration under Payment/DefaultPSPPaymentMethods) are always displayed on the BillingOnline payment page for selection, even if these are not listed under displayedmethods.
    The valid selection of means of payment depends on the concluded “payment service provider” contracts and is defined upon each integration.
    If the node contains payment methods that have not been contractually agreed, these are not shown. If there are no payment types in the intersection, all payment types supported by the shop will be shown and the selection made will be ignored.
    PaymentWarranty OffRiskBill (ESR payment)
    Online shops which are authorized to use the “by monthly invoice” payment method (ESR), must provide the value “OffRiskBill” in the XML request.
    This ensure that an online solvency check takes place for both private and business customers, which is used to decide whether the payment method should be made available to the customer.
    OnRiskBill (ESROZG payment)
    May only be used in consultation with Post CH Ltd.
    Online shops which are authorized to use the “by monthly invoice...” payment method (ESROZG), must provide the value “OnRiskBill” in the XML request.
    This basically concerns customers from relevant online shops for whom no online solvency check should be performed.
    Verification of whether the customer should be provided with the payment method “by monthly invoice...” (ESROZG) depends on the stored value in the “LimitCustomer” / “LimitNewCustomer” parameter in the central online shop configuration (if the limit has still not been reached, the customer is able to select the payment method).

    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!

    5. Transport and security

    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 have 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”

    To enable the certificate that is used for the signature to be used for authentication at the same time, certification keys must first be exchanged between the online shop and Post CH Ltd (operator of BillingOnline).

    The exchanging process is intended as follows (for instructions on generating the CSR, see section 4.4 Creating an CSR and having it signed.

    Who Description
    Online shop operator Generates a certificate with a key pair (private / public key).
    Online shop operator Generates a Certificate Signing Request File (CSR) using the PublicKey
    Online shop operator The CSR file is to be sent to Post CH Ltd
    Post CH Ltd Acts as a Certificate Authority, i.e. creates a ClientCertificate on the basis of the CSR file using PublicKey and signs it
    Post CH Ltd The created ClientCertificate is issued to the online shop

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

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

    The signed XML output is UTF-8 encoded.

    <?xml version="1.0" encoding="utf-8"?>
    <envelope 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vps-payment.xsd">
        <header usecase="PaymentAuth" action="Request">
            <shop>…</shop>
            <format languagecode="DE">…</format>
        </header>
        <body>
            <ssouser languagecode="DE">…</ssouser>
            <order bookingtype="Deferred" currency="CHF">…</order>
            <payment>…</payment>
        </body>
        <Signature Id="PaymentSignature" xmlns="http://www.w3.org/2000/09/xmldsig#">
            <SignedInfo>
                <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"/>
                <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
                <Reference URI="">
                    <Transforms>
                        <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    </Transforms>
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <DigestValue>nqtcfxFbP3HKbu1eX7Vur6vd348=</DigestValue>
                </Reference>
                <Reference URI="#SignatureProperties" Type="http://www.w3.org/2000/09/xmldsig#SignatureProperties">
                    <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                    <DigestValue>AnhXmCJH6LMCob8hTJlupSy3vH4=</DigestValue>
                </Reference>
            </SignedInfo>                                                                                                                                                                    
            <SignatureValue>dtJUaZWurrMKZQjcinX0Ql4+t6pljmXik0g...</SignatureValue>
            <KeyInfo>
                <X509Data>
                    <X509Certificate>MIICXzCCAcgCAQEwDQYJKoZIhvcNAQEFBQAwg...</X509Certificate>
                </X509Data>
            </KeyInfo>
    <Object Id="SignatureProperties">
                <SignatureProperties 
                    xmlns="">
                    <SignatureProperty Target="#PaymentSignature" Id="TimeStamp">
                        <TimeStamp>
                            <Date>2009-01-22</Date>
                            <Time>14:59:33.3823239+01:00</Time>
                        </TimeStamp>
                    </SignatureProperty>
                </SignatureProperties>
            </Object>
        </Signature>
    </envelope>

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

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

    Via SSH      $ssh = new phpseclibNetSSH2('localhost');
        $ssh->login('sshuser', '123456');
        $content = $ssh->exec('xmlsec1 --sign --pkcs12 ' . $cert . ' --pwd ' . $pwd . ' ' . $tmpXml);
    or using exec().

    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.

    openssl pkcs12 -export -in my.cert.pem -inkey my.key.pem -out my.p12

    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:
    openssl x509 -outform der –in YOURCERTIFICATE.crt –out GENERATEDCERTIFICATE.crt

    Using the same method, the DER (binary) formatted certificate can also be generated as a .der or .cer file by changing the file extension marked blue 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:

    openssl pkcs12 -in YOURCERTIFICATE.p12 -out GENERATEDCERTIFICATE.pem -nodes -password pass:YOURp12PASSWORD

    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. Test information

    6.1 Credit card details

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

    Brand: Visa

    Card number Expiry date Card validation code (CVC/CVV) 3D Secure 3D Password
    4000 0000 0000 0002 Any date in the future Any three numbers Yes 11111
    4111 1111 1111 1111 Any date in the future Any three numbers No N/A

    Brand: Master

    Card number Expiry date Card validation code (CVC/CVV) 3D Secure 3D Password
    5300 0000 0000 0006 Any date in the future Any three numbers Yes 11111
    5399 9999 9999 9999 Any date in the future Any three numbers No N/A

    Brand: Amex

    Card number Expiry date Card validation code (CVC/CVV) 3D Secure 3D Password
    3714 496353 11004 Any date in the future Any four numbers Yes 11111
    3741 111111 11111 Any date in the future Any four numbers No N/A

    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.

    7. Automated onboarding process

    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.

     

    Column name Content / example MaxLength mandatory Validation Rules
    shopid SHOP-XX-AAAX 50 x Starts with SHOP-
    sales-account UM-XX-AAAA.CHF 50 x Starts with UM-
    companyname Webshop AG 50 x if not business customers, specify as customer name
    street Example Street 12 50 x Street incl. number
    zip 3030 10 x -
    city Berne 50 x -
    country CH 2 x According to ISO 3166 ALPHA-2
    language de/fr/it/en 2 x valid values: DE, FR, IT, EN
    phone-nr 031 333 33 33 250 x Telephone numbers are transferred 1:1 from the CSV (also with character +, e.g. +41)
    url-web-shop www.webshop.ch 250 x -
    email-report-sender-address billingonline@swisspost.ch 250 - set and filled by BillingOnline
     - PFSC: smartcommerce@postfinance.ch
    - PCO: billingonline@post.ch
    - EUMZUG: billingonline@post.ch
    email-report-receiver-address hans.meier@swisspost.ch, max.sample@swisspost.ch etc. 250 x valid email address
    Possibility to send to several e-mail addresses (comma separatetd)
    email-report-subject Sample Hans Report 250 - Title of the sales report Emails
    email-report-text Hello, please find the XY sales reports attached ... 2000 - Content of the sales report Emails
    IBAN CH0209000000880103129 (without spaces) 40 x only valid IBAN numbers are accepted (without spaces)
    owner-bank-account WebShop Ltd. 50 x Name of the bank account holder
    bankname PostFinance Ltd 250 x Name of the bank
    title-1 Mr 50 x valid values
    Frau, Herr
    legal-name-1 Meier 50 x -
    legal-prename-1 Hans 50 x -
    birthday-1 YYYY-MM-DD 10 - -
    nationality-country-1 CHE 3 x According to ISO 3166 ALPHA-3
    title-2 Ms 50 - valid values
    Frau, Herr
    legal-name-2 Sample 50 - -
    legal-prename-2 Janine 50 - -
    birthday-2 YYYY-MM-DD 10 - -
    nationality-country-2 CHE 3 - According to ISO 3166 ALPHA-3
    company-founding-year 2017 4 - -
    legal-form Ltd 50 - -
    mcc-industry Service (according to the separate list) 4 x Four-digit MCC code of the service of the shop
    (according to separate list)
    PSPID Online shop 50 - PaymentServiceProvider ID, only mandatory if the shop is not a marketplace model.
    division-post BillingOnline external (according to the activation form) 50 - -

    Onboarding process (csv) rules:

    Reference Description
    File name SHOP-ID_YYYYMMDDHHMISS.csv (example SHOP-PX-POST_20170327164655)
    Format CSV file, separated by semicolon, values in columns without quotation marks, no semicolon at the end of any row
    Encoding ISO-8859-1
    Line break CR+LF (Windows format)
    Transfer FDS account according to activation form
    A maximum of one transfer per day can take place per online shop (initial creation, update)
    Processing 1 x per hour
    Notification Notification after successful or failed processing sent to the defined e-mail address

    8. IF2 Methods

    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:

    Role Description
    read ExecutePing, CheckAlias, GetAccountSaldo, ListAccountStatement, ListExpiringCreditCards, ListOrderInfo2, ListOrderStatement
    write AddCreditBooking, AddDebitBooking, DeleteOrder, ConfirmDelivery, DeleteAlias, SetAliasState

    9. Description of methods

    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
    Parameters Type Description
    ExecutePing - -
    text String Any text
    exceptionTest Boolean Optional
    false = does not trigger an SOAP exception
    true = triggers an SOAP exception
    Output
    Parameters Type Description
    ExecutePingResult - -
    Message String The received “text” is returned.
    “You entered: Hello”
    Timestamp DateTime Current date as string 
    Format = yyyy-MM-ddTHH:mm.ss
    “2017-11-01T11:29:20.6765886+01:00”
    Error - -
    Code String See error code table, section 3
    Text String Error text
    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
    Parameters Type Description
    CheckAlias - -
    shopId String Identification of the accessing online shop
    ssoId String Unique SSO user identification
    Output
    Parameters Type Description
    CheckAliasResult - -
    AliasStatus String Possible statuses:
    Enabled, Disabled, NotSet
    CardNumber String Output of the last four card numbers in plain text, remaining output X: XXXXXXXXXXXX0002
    ExpiryDate String Card expiry date (MMDD)
    Brand String Card type: Visa, Master etc.
    SsoId String User identification (unique SSO)
    Error - -
    Code String See error code table, section 3
    Text String Error text
    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
    Parameters Type Description
    GetAccountSaldo - -
    shopId String Identification of the accessing online shop
    ssoId String Unique SSO user identification
    customerAccountType Int Customer account type
    1 = EWallet
    2 = ESR
    3 = PostCard
    4 = CreditCard
    5 = ESROZG
    Output
    Parameters Type Description
    GetAccountSaldoResult - -
    ForecastSaldo Decimal Balance minus order
    Error - -
    Code String See error code table, section 3
    Text String Error text
    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
    Parameters Type Description
    ListAccountStatement - -
    shopId String Identification of the accessing online shop
    ssoId String Unique SSO user identification
    customerAccountType Int Customer account type
    1 = EWallet
    2 = ESR
    3 = PostCard
    4 = CreditCard
    5 = ESROZG
    dateFrom DateTime Optional – date from
    dateTo DateTime Optional – date until
    Output
    Parameters Type Description
    ListAccountStatementResult - -
    AccountStatement - -
    CustomerAccountType Int Customer account type
    1 = EWallet
    2 = ESR
    3 = PostCard
    4 = CreditCard
    5 = ESROZG
    AccountState Int Account status
    0 = Active
    1 = Inactive
    2 = for collection (payment collection)
    OrderSummaries - Array of OrderSummary (0..n)
    OrderSummary - -
    OrderId String Order number
    OrderText String Order text
    OrderDate DateTime Order date
    LineItems - Array of AccountStatementLineItem (0..n)
    AccountStatementLineItem - -
    PositionNbr Int Item number
    LineItemId Int Line item identification
    LineItemType Int Item type
    1 = Article row
    2 = Payment
    BookingDate DateTime Order date
    ProductNbr String Article number
    ProductText String Article name
    Debit Decimal Optional: article amount or fee
    Credit Decimal Optional: credit amount
    Saldo Decimal Optional: balance amount
    Error - -
    Code String See error code table, section 3 
    Text String Error text
    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
    Parameters Type Description
    ListExpiringCreditCards - -
    shopId String Identification of the accessing online shop
    month String month selected for the query
    year String Year selected for the query
    Output
    Parameters Type Description
    ListExpiringCreditCardsResult - -
    CheckAliasOut - -
    AliasStatus String Enabled, Disabled, NotSet
    CardNumber String Output of the last four card numbers in plain text, remaining output using X: XXXXXXXXXXXX0002
    ExpiryDate String Card expiry date (MMYY)
    Brand String Card type: Visa, Master etc.
    SsoId String Customer number
    Error - -
    Code String See error code table, section 3
    Text String Error textTechnical error affecting WebService interface
    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
    Parameters Type Description
    ListOrderInfo - -
    shopId String Identification of the accessing online shop
    orderId String Order number
    Output
    Parameters Type Description
    ListOrderInfoResult2 - -
    OrderInfo - -
    OrderId String Order number
    SSOId Int Customer number
    OrderDate DateTime Order date
    Name String Customer’s last name
    FirstName String Customer’s first name
    Street String Customer’s street and house no.
    City String Customer’s location
    LineItems - Array of OrderInfoLineItem 2 (0..n)
    OrderInfoLineItem2 - -
    LineItemId Int Item number of the order
    CustomerAccountType Int Customer account type
    1 = EWallet
    2 = ESR
    3 = PostCard
    4 = CreditCard
    5 = ESROZG
    SalesAccount String Name of online shop’s sales account according to the BillingOnline payment activation form.
    BookingState String Order status
    Deferred = the delivery has not yet been released
    Settled = the delivery has already been released
    ProductNbr String Article number
    ProductText String Article name
    Tax Decimal VAT rate in %
    Quantity Int Number of units per line item
    PriceIncTax Decimal Unit price including VAT
    AmountIncTax Decimal Total amount of item including VAT
    Error - -
    Code String See error code table, section 3
    Text String Error text
    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
    Parameters Type Description
    ListOrderStatementssoId - -
    shopId String Identification of the accessing online shop
    ssoId String Unique SSO user identification
    dateFrom DateTime Optional – date from
    dateTo DateTime Optional – date until
    Output
    Parameters Type Description
    ListOrderStatementResult - -
    OrderStatements - Array of OrderStatement (0..n)
    OrderStatement - -
    OrderId String Order number
    OrderText String Order text
    OrderDate DateTime Order date
    OrderAmount Decimal Total amount of order
    LineItems - Array of OrderStatementLineItem (0..n)
    OrderStatementLineItem - -
    PositionNbr Int Item number
    LineItemId Int Item number of the order
    LineItemType Int Item type
    1 = Article row
    2 = Payment
    BookingDate DateTime Order date
    ProductNbr String Article number
    ProductText String Article name
    AmountIncTax Decimal Total amount of item including VAT
    CustomerAccountType Int Customer account type
    1 = EWallet
    2 = ESR
    3 = PostCard
    4 = CreditCard
    5 = ESROZG
    BookingState String Order status
    Deferred = the delivery has not yet been released
    Settled = the delivery has already been released
    Error - -
    Code String See error code table, section 3
    Text String Error text
    Error - -
    Code String See error code table, section 3
    Text String Error text
    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
    Parameters Type Description
    shopId String Identification of the accessing online shop
    orderId String Order number
    Output
    Parameters Type Description
    DeleteOrderOut DeleteOrderOut -
    OrderId String Order number belonging to the deleted booking
    LineItemId Int Item number of the deleted booking.
    Error Error -
    Code String see following error code table 
    Description String Error text
    Exception

    SOAP-Exception: Technical error affecting WS interface

    Error Code
    Error Code Description
    1  Error in validation / candition of the order
    2 Order cannot be deleted / refundet because several payment methods were used or a payment method was used which cannot be processed automatically.
    3 Connection problem / technical error
    4 Error in writing to billing
    99 General system failure

    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
    Parameters Type Description
    shopId String Identification of the accessing online shop
    orderId String Order number
    lineItemId Int Item number of the order
    OrderDate DateTime Order date
    May not be further than one day in the past (starting from today’s date)
    Quantity Int Optional
    Number of units per line item
    Output
    Parameters Type Description
    ConfirmDeliveryOut ConfirmDeliveryOut -
    OrderId String Order number belonging to the released booking
    LineItemId Int Item number of the released booking.
    Error Error Error
    Code String See error code table, section 3
    Description String Error text
    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
    Parameters Type Description
    AddCreditBooking - -
    shopId String Identification of the accessing online shop
    orderId String Order number
    lineItemId Int Item number for credit
    (may not be identical to the existing lineItemIds of the order)
    salesAccount String Name of online shop’s sales account according to the BillingOnline payment activation form.
    bookingDate DateTime Booking date 1)
    productNbr String Article number
    productText String Article name
    productAuxText1 String Additional article name
    tax Decimal VAT rate in %
    amountIncTax Decimal Total amount of item including VAT
    Output
    Parameters Type Description
    AddCreditBookingResult - -
    OrderId String Order number
    LineItemId Int Item number for credit
    Error - -
    Code String See error code table, section 3
    Text String Error text
    Exception

    SOAP exception: Technical error affecting WebService interface

    Information
    Reference Description
    1) Booking date For credits, the online shop needs to communicate the current date as the booking date.
    Bookings in the past are not permitted.
    In exceptional cases, the booking date may be max. one day in the past (starting from today’s date).
    2) Information by e-mail In addition to the electronic delivery of the credit via the server interface, an e-mail needs to be sent to the e-mail address stated in the activation form using the 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

    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
    Parameters Type Description
    AddDebitBooking - -
    shopId String Identification of the accessing online shop
    orderId String Order number
    lineItemId Int Item number for the subsequent debit
    (may not be identical to the existing lineItemIds of the order)
    salesAccount String Name of online shop’s sales account according to the BillingOnline payment activation form.
    bookingDate DateTime Booking date 1)
    productNbr String Article number
    productText String Article name
    productAuxText1 String Additional article name
    tax Decimal VAT rate in %
    amountIncTax Decimal Total amount of item including VAT
    Output
    Parameters Type Description
    AddCreditBookingResult - -
    OrderId String Order number
    LineItemId Int Item number for credit
    Error - -
    Code String See error code table, section 3
    Text String Error text
    Exception

    SOAP exception: Technical error affecting WebService interface

    Information
    Reference Description
    1) Booking date For credits, the online shop needs to communicate the current date as the booking date.
    Bookings in the past are not permitted.
    In exceptional cases, the booking date may be max. one day in the past (starting from today’s date).

    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
    Parameters Type Description
    DeleteAlias - -
    shopId String Identification of the accessing online shop
    ssoId String Unique SSO user identification
    Output
    Parameters Type Description
    DeleteAliasResult - -
    AliasStatus String NotSet
    CardNumber String Output of the last four card numbers in plain text, remaining output X: XXXXXXXXXXXX0002
    ExpiryDate String Card expiry date (MMDD)
    Brand String Card type: Visa, Master etc.
    Error - -
    Code String See error code table, section 3
    Text String Error text
    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
    Parameters Type Description
    SetAliasState - -
    shopId String Identification of the accessing online shop
    ssoId String Unique SSO user identification
    aliasState String Enabled, Disabled, NotSet
    Output
    Parameters Type Description
    SetAliasStateResult - -
    AliasStatus String Enabled, Disabled, NotSet
    CardNumber String Output of the last four card numbers in plain text, remaining output X: XXXXXXXXXXXX0002
    ExpiryDate String Card expiry date (MMDD)
    Brand String Card type: Visa, Master etc.
    Error - -
    Code String See error code table, section 3
    Text String Error text
    Exception

    SOAP exception: Technical error affecting WebService interface

    10. Overview of error codes

    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.

    Error code Description
    1 The sent XML does not comply with the schema upon the call
    2 The digital signature has failed
    3 The Swiss Post parameter data is not contained in the XML request
    4 The shop ID (<shopid>) is incorrect
    7 The time of signing the XML request is too far in the past (max. 10 min.)
    8 The thumbprint of the certificate used does not match the value in the configuration
    9 A maintenance window is active (use case 5, otherwise a relevant info page appears)
    10 Internal server error
    11 The data has been signed but the server is configured in such a way that it rejects signed data
    12 User has cancelled the payment process
    21 The current release does not support all the payment types contained in the schema (xsd) (enumeration paymentmethod)
    The accepted values are: Master, Visa, Amex, PostFinanceCard, EFinance, ESR, EWallet, VoucherEmployee, VoucherGift
    22 The XML request may not simultaneously contain the nodes ssouser(envelope.body.ssouser) and anonymoususer(envelope.body.anonymoususer)
    23 The sum of the amounts (<amountinctax>) of all order items (<lineitem>) must match the order amount (<orderamount>)
    24 The quantity (<quantity>) of an order item multiplied by the individual price (<priceinctax>) of an order item must match the total price (<amountinctax>) of an order item
    25 User identification (<ssoid>) is required for all payment types except Master, Visa, Amex, PostFinanceCard, EFinance in use case 1
    26 The order is rejected due to a negative order amount (<orderamount>)
    28 The node body/order is required for use cases 1, 2, 5
    29 The node body/chargewallet is required for use case 3
    30 Within an order (<order>), a single order item number (<lineitemid>) may only appear once
    31 The order amount is not covered by the payment type EWallet (use case 5)
    32 An indicated sales account (<salesaccount>) is incorrect
    34 The same order number (<orderid>) has already been used
    35 The EWallet charging process cannot be performed since the maximum permitted EWallet amount (EWalletMaxAmount) will be exceeded
    37 The order amount of at least one order item (<amountinctax>) is negative
    38 The solvency check was unsuccessful (Intrum error code in the error description). Only used for use cases 6, 8
    40 The shop customer does not belong to the indicated online shop (incorrect prefix used for customer identification <sssoid>), or elements are missing for the non-registered shop customer (<anonymoususer>) – see table in section 5.4 Identification of customer type
    41 The maximum permitted amount for an invoice (LimitCustomer, LimitNewCustomer) has been exceeded. Only used for use case 6
    42 The shop customer does not have a valid alias status (alias status is not set or is deactivated), or the shop customer is unknown. Only used for use case 7
    45 Use case 7R can only be performed as booking type “Deferred” (<order bookingtype="Deferred" currency="CHF">)
    47 The currency check is unsuccessful
    48 The booking date of at least one order item (<lineitem>) is too old
    51 The payment has been declined by the PSP (Payment Service Provider) (external cause) or the order could not be written into the billing system (internal error)
    52 Session timeout with redirect to the decline URL of the online shop (no payment within 30 min. by the shop customer after transmitting the order XML request)
    53 Server-server use cases may not be performed in overlay mode
    54 One of the use cases listed below is not configured for use by the online shop 5 DirectPaymentAuth, 6 DirectPaymentESRAuth, 7 DirectPaymentCardsAuth

    10.2 IF2 error codes

    Error code Description
    1 System error
    11 Input parameter missing
    12 Input parameter format invalid
    13 Input parameter value range invalid
    21 System temporarily unavailable
    22 Logical error
    23 Data does not exist

    11. Sales report

    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
    Value Description
    OrderDate Order date or date of receipt of proof of delivery
    OrderID Order number stored in the shopping basket
    LineItemID Order item number stored in the shopping basket 
    SalesAccount Sales account stored in the shopping basket
    ProductNbr Item number stored in the shopping basket
    ProductText Item text for the order item, credit or subsequent debit
    Quantity Quantity for each order item stored in the shopping basket
    Typ Booking type (credit or subsequent debit) stored in the shopping basket
    Commission* Commission calculated per OrderID
    Payout* Net revenue calculated per OrderID
    Tax VAT rate transmitted from the shopping basket
    PriceIncTax Unit price per order item (if quantity is 1, this is identical to AmountIncTax)
    AmountIncTax Gross price per order item
    SSOID Blank = positive (item / fees); minus sign = negative (credits)
    FirstName Purchaser’s first name
    LastName Purchaser’s last name
    City Purchaser’s town
    AccountName Credit or debit card
    PSPPaymentMethod* Payment method (Visa, Mastercard, Amex, etc.)

    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

    12. Any questions?

    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

    13. Documents