Integrating Travel Solutions

Getting Started

This documentation covers integrating BillPay payment solutions for the travel sector and the BillPay XML API with your booking systems. An overview of the payment methods on offer and general information about BillPay can be found here.

BillPay offers programming libraries in various languages to help simplify your integration. Before getting started, please consult the versioning table to ensure that the BillPay programming library you have is compatible with the current API version. If you are not using one of our libraries, and plan on integrating our XML API, we recommend you take a look at the request specific XSD files in the following table:

API Call	Purpose	XSD Links
preauthorize	Placing a booking	Request / Response
capture	Placing a booking	Request / Response
cancel	Managing a booking	Request / Response
editCartContent	Managing a booking	Request / Response
getBillPayBankData	Managing a booking	Request / Response

Front-end Integration

The core of all integrations is the BillPay JavaScript widget, which displays all BillPay payment method relevant fields and information in a conversion optimized and standardized fashion. Implementing the BillPay widget helps you benefit from BillPay brand recognition and improved customer satisfaction.

It is a requirement to implement the BillPay Widget for the display of the BillPay payment methods.

Configuration

Step 1: Loading the JavaScript

In order to load the JavaScript widget upon the selection of a BillPay payment method in your checkout, the following snippet needs to be included in the your template:

<!-- Initialization & Configuration -->
<script type="application/javascript">

    var bpyReq = {},
            appPath = '//widgetcdn.billpay.de/checkout/1.x.x/';
    (function(win, doc, appPath, objectName) {
        bpyReq = {
            "deps": ['main'],
            "baseUrl": appPath,
            "skipDataMain": true,
            "callback": function() {}
        };
        win['BillPayCheckout'] = objectName;
        win[objectName] = win[objectName] || function() {
                    (win[objectName].queue = win[objectName].queue || []).push(arguments)
                };
        var requireJs = doc.createElement('script');
        requireJs.src = appPath + 'require.js';
        doc.getElementsByTagName('head')[0].appendChild(requireJs);
    })(window, document, appPath, 'billpayCheckout');

</script>

The function billpayCheckout is now available to use.

Step 2:Configuration

In order to configure the JavaScript widget the billpayCheckout function is called, with the first parameter options and a second JSON object containing customer and shop information as the second parameter. The container variable identifies the container (e.g. div) where the BillPay widget should be rendered. The checkout.form variable is the jQuery identifier of the checkout form, to which the values entered into the fields generated by the BillPay widget will be appended. Upon submission of the checkout form, these values will be available for server-side processing and the eventual submission to the BillPay XML API.

<script type="application/javascript">
    billpayCheckout('options', {
        "container":".bpy-checkout-container",
        "checkout": {
            "form": "#payment_form"
        },
        "shop": {
            "apiKey": "710290a938e6b4770000005552",
            "live": false
        },
        "order": {
            "cartAmount": 161.94, // Total order value without shipping or additional fees
            "orderAmount": 166.94, // Total order value including shipping and additional fees
            "currency": "EUR", // the currency to be used for checkout
            "shippingDate": "2017-12-30", // ISO 8601 date format
            "articleTypes": [1,6] // comma separated list of the article types in the booking
        },
        "customer": {
            "billing": {
                "salutation": "", // The customer's salutation. If this field is empty, the salutation input will be shown in the checkout widget.
                "firstName": "Thomas", // The customer's first name
                "lastName": "Testkunde", // The customer's last name
                "street": "Zinnowitzer Str.", // The customer's street (billing address)
                "streetNo": "1", // The customer's house number (billing address)
                "zip": "10115", // The customer's zip code (billing address)
                "city": "Berlin", // The customer's city (billing address)
                "phoneNumber": "3254234234234", // The customer's phone number. If this field is empty, the phone number input will be shown in the checkout widget.
                "countryIso2": "DE", // 2-digit country code of the customer's invoice address
                "countryIso3": "deu", // 3-digit country code of the customer's invoice address
                "dayOfBirth": "1970-01-15" // customer's date of birth in YYYY-MM-DD format. If this field is set, it won't be requested in the checkout widget.
            },
            "language": "de", // 2-digit language code for the checkout session
            "identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // unique session ID hash
            "customerGroup": "private", // private or business customer
            "forceCustomerGroup": true // true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false if you do not have this value
        },
        "inputNames": {
            "order": {
                "cartAmount": "billpay[cart_amount]",
                "orderAmount": "billpay[order_amount]",
                "currency": "billpay[currency]",
                "shippingDate": "billpay[shippingDate]",
                "articleTypes": "billpay[articleTypes]"
            },
            "customer": {
                "salutation": "billpay[customer_salutation]",
                "phoneNumber": "billpay[customer_phone_number]",
                "dayOfBirth": "billpay[customer_day_of_birth]",
                "language": "billpay[customer_language]",
                "companyName": "billpay[company_name]",
                "companyHolder": "billpay[company_holder]",
                "legalForm": "billpay[company_legal_form]",
                "registerNumber": "billpay[company_register_number]",
                "taxNumber": "billpay[company_tax_number]",
                "bankAccount": {
                    "iban": "billpay[customer_iban]",
                    "bic": "billpay[customer_bic]"
                },
                "accountHolder": "billpay[account_holder]"
            },
            "paymentMethods": {
                "invoiceCollateralPromise": {
                    "customerGroup": "billpay[invoice_col_customer_group]",
                    "termsOfService": "billpay[invoice_col_toc]"
                },
                "directDebitCollateralPromise": {
                    "customerGroup": "billpay[direct_debit_col_customer_group]",
                    "termsOfService": "billpay[direct_debit_col_toc]"
                },
                "paylaterCollateralPromise": {
                    "customerGroup": "billpay[paylater_col_customer_group]",
                    "duration": "billpay[paylater_col_duration]",
                    "instalmentsCount": "billpay[paylater_col_instalments_count]",
                    "instalmentAmount": "billpay[paylater_col_instalment_amount]",
                    "feeAbsolute": "billpay[paylater_col_fee_absolute]",
                    "totalAmount": "billpay[paylater_col_total_amount]",
                    "termsOfService": "billpay[paylater_col_toc]"
                }
            }
        }
    });
</script>

Variable	Explanation
container	jQuery selector that defines the container for the BillPay widget to be rendered. (in this example: “.bpy-checkout-container”)
checkout.form	jQuery selector (id) of the checkout form where the widget fields will be included for processing upon submission.
shop.apiKey	Public API Key; generated and delivered by BillPay for your portal.
shop.live	Defines if the widget is running in “test” or “live” mode.
order.cartAmount	Value of the total order (article value excl. shipping cost or any other additional fees.)
order.orderAmount	Total order value (incl. shipping cost or any other additional fees
order.currency	ISO4217 Code for the currency
order.shippingDate	ISO 8601 Departure date. Format YYYY-MM-DD.
order.articleTypes	Comma separated list of the article types in the booking Item classification 0: Miscellaneous 1: Flight 2: Package including flight 3: Combination of items including flight 4: Combination of items without a flight 5: Hotel 6: Travel Insurance 7: Auto Rental
customer.billing.salutation	Salutation
customer.billing.firstName	First name of the customer
customer.billing.lastName	Last name of the customer
customer.billing.street	Street of the customer address
customer.billing.zip	Zip code of the customer address
customer.billing.city	City of the customer address
customer.billing.phoneNumber	Phone number
customer.billing.countryIso2	ISO3166-1 (alpha-2) 2-digit country code of the customer address country
customer.billing.countryIso3	ISO3166 (alpha-3) 3-digit country code of the customer address country
customer.billing.dayOfBirth	Customer’s date of birth
customer.language	ISO3166-1 (alpha-2) Language of the customer
customer.identifier	Unique identifier of the user session. This token is used for fraud prevention (e.g. hash of session ID)
customer.customerGroup	private for B2C Customers business for B2B Customers
customer.forceCustomerGroup	true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown false: when the value is not provided in the customerGroup
inputNames	IDs of the hidden input fields that will be generated inside the checkout.form jQuery selector by the JavaScript widget. (e.g.: billpay[NAME_OF_THE_FORM_FIELD])
inputNames.order	Input fields for the order data
inputNames.customer	Input fields for the customer data
inputNames.paymentMethods	Input fields for payment specific information
request	JSON object, which contains request information (e.g. json_encode($_REQUEST);)

Step 3: Execution

When calling run, the BillPay widget is rendered in the container identified in the options call container variable.

It is also possible to supply the container as a second parameter (json object) when calling run. Doing so allows you to render multiple checkout widgets on one page.

<script type="application/javascript">
    billpayCheckout('run');
</script>

If you choose to define the container when calling run, you would leave the container variable out of the options array and include it in the run call as follows:

<script type="application/javascript">
    billpayCheckout('run', {"container": ".bpy-checkout-container"});
</script>

Variable	Info
container	jQuery selector defining the container for the BillPay payment methods to be displayed. (in this example: “.bpy-checkout-container”)

Step 4: Validating the widget on submit

<script type="application/javascript">
    $("#payment_form").submit(function( event ) {
        if(!billpayCheckout('isValid')){
            event.preventDefault();
        }
    });
</script>

Variable	Info
’#payment_form’	jQuery selector defining the ID of the checkout form that contains the payment methods and is being submitted (in this example: “#payment_form”)

Full Example

<!DOCTYPE html>
<html>
<head></head>

<body>

<!-- Initialisierung & Konfiguration -->
<script type="application/javascript">

    var bpyReq = {},
            appPath = '//widgetcdn.billpay.de/checkout/1.x.x/';
    (function(win, doc, appPath, objectName) {
        bpyReq = {
            "deps": ['main'],
            "baseUrl": appPath,
            "skipDataMain": true,
            "callback": function() {}
        };
        win['BillPayCheckout'] = objectName;
        win[objectName] = win[objectName] || function() {
                    (win[objectName].queue = win[objectName].queue || []).push(arguments)
                };
        var requireJs = doc.createElement('script');
        requireJs.src = appPath + 'require.js';
        doc.getElementsByTagName('head')[0].appendChild(requireJs);
    })(window, document, appPath, 'billpayCheckout');

    billpayCheckout('options', {
        "container":".bpy-checkout-container",
        "checkout": {
            "form": "#payment_form"
        },
        "shop": {
            "apiKey": "710290a938e6b4770000005552",
            "live": false
        },
        "order": {
            "cartAmount": 161.94, // Total order value without shipping or additional fees
            "orderAmount": 166.94, // Total order value including shipping and additional fees
            "currency": "EUR", // the currency to be used for checkout,
            "shippingDate": "2017-12-30", // ISO 8601 date format
            "articleTypes": [1,6] // comma separated list of the article types in the booking
        },
        "customer": {
            "billing": {
                "salutation": "", // The customer's salutation. If this field is empty, the salutation input will be shown in the checkout widget.
                "firstName": "Thomas", // The customer's first name
                "lastName": "Testkunde", // The customer's last name
                "street": "Zinnowitzer Str.", // The customer's street (billing address)
                "streetNo": "1", // The customer's house number (billing address)
                "zip": "10115", // The customer's zip code (billing address)
                "city": "Berlin", // The customer's city (billing address)
                "phoneNumber": "3254234234234", // The customer's phone number. If this field is empty, the phone number input will be shown in the checkout widget.
                "countryIso2": "DE", // 2-digit country code of the customer's invoice address
                "countryIso3": "deu", // 3-digit country code of the customer's invoice address
                "dayOfBirth": "1970-01-15" // customer's date of birth in YYYY-MM-DD format. If this field is set, it won't be requested in the checkout widget.
            },
            "language": "de", // 2-digit language code for the checkout session
            "identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // unique session ID hash
            "customerGroup": "private", // private or business customer
            "forceCustomerGroup": true // true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false if you do not have this value
        },
        "inputNames": {
            "order": {
                "cartAmount": "billpay[cart_amount]",
                "orderAmount": "billpay[order_amount]",
                "currency": "billpay[currency]",
                "shippingDate": "billpay[shippingDate]",
                "articleTypes": "billpay[articleTypes]"
            },
            "customer": {
                "salutation": "billpay[customer_salutation]",
                "phoneNumber": "billpay[customer_phone_number]",
                "dayOfBirth": "billpay[customer_day_of_birth]",
                "language": "billpay[customer_language]",
                "companyName": "billpay[company_name]",
                "companyHolder": "billpay[company_holder]",
                "legalForm": "billpay[company_legal_form]",
                "registerNumber": "billpay[company_register_number]",
                "taxNumber": "billpay[company_tax_number]",
                "bankAccount": {
                    "iban": "billpay[customer_iban]",
                    "bic": "billpay[customer_bic]"
                },
                "accountHolder": "billpay[account_holder]"
            },
            "paymentMethods": {
                "invoiceCollateralPromise": {
                    "customerGroup": "billpay[invoice_col_customer_group]",
                    "termsOfService": "billpay[invoice_col_toc]"
                },
                "directDebitCollateralPromise": {
                    "customerGroup": "billpay[direct_debit_col_customer_group]",
                    "termsOfService": "billpay[direct_debit_col_toc]"
                },
                "paylaterCollateralPromise": {
                    "customerGroup": "billpay[paylater_col_customer_group]",
                    "duration": "billpay[paylater_col_duration]",
                    "instalmentsCount": "billpay[paylater_col_instalments_count]",
                    "instalmentAmount": "billpay[paylater_col_instalment_amount]",
                    "feeAbsolute": "billpay[paylater_col_fee_absolute]",
                    "totalAmount": "billpay[paylater_col_total_amount]",
                    "termsOfService": "billpay[paylater_col_toc]"
                }
            }
        }
    });
</script>

<!-- Container -->
<form id="payment_form">
    <h1>Rechnungskauf</h1>
    <div class="bpy bpy-checkout-container" bpy-pm="invoiceCollateralPromise"></div>
    <h1>Lastschrift</h1>
    <div class="bpy bpy-checkout-container" bpy-pm="directDebitCollateralPromise"></div>
    <h1>PayLater</h1>
    <div class="bpy bpy-checkout-container" bpy-pm="paylaterCollateralPromise"></div>

</form>

<!-- run the widget -->
<script type="application/javascript">
    billpayCheckout('run', {"container": ".bpy-checkout-container"});

    $("#payment_form").submit(function( event ) {
        if(!billpayCheckout('isValid')){
            event.preventDefault();
        }
    });
</script>

</body>
</html>

Legal Texts and Logos

In addition to the integration of the BillPay javascript widget, merchants are required to include BillPay related text passages in the terms and conditions and privacy pages of their website. These passages will be provided to you by BillPay.

Should you display payment method logos in the footer of your website or in the payment method selection portion of your checkout, it is required to also include the relevant BillPay logos. These can be found and downloaded in either png or svg format via the following url:

https://www.billpay.de/en/shopintegration/downloads/

XML API Overview

Every XML service request consists of an XML document, which is sent to the service URL specifically for each request type using the POST method. The BillPay server response contains an error code, as well as a message to be displayed in the frontend (“customer message”), a message to be logged by the merchant (“merchant message”), and potentially a message in the case of an XSD validation error (“developer_message”). The transaction can only be seen as successful after receiving an error code value of “0”. All other error codes imply that there has been some kind of issue with the request.

All XML data must be UTF-8 encoded and all server responses from BillPay will be too.

The schema of all XML service requests is based on the heavy use of XML attributes. Please make sure, that all reserved characters are escaped according to the following table:

Reserved Character	Escape Sequence
&	`&`
“	`"`
’	`'`
<	`<`
>	`>`

Web service URL

The URL for every XML service is constructed using the base URL followed by an identifier for the specific request.

Base URLs

Live System: https://api.billpay.de/v2/xml
Test System: https://test-api.billpay.de/v2/xml/offline

Generic Parameters

Generic parameters for all XML requests

Some parameters are required in all XML requests no matter what endpoint is addressed. (e.g. the merchant API credentials to authorize your connection). The merchant API credentials are generated and sent by BillPay.

<?xml version="1.0" encoding="UTF-8"?>
<data apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <!-- additional request specific data -->
</data>

Attribute	Required	Data Type	Info
mid	+	positive int	Merchant ID
pid	+	positive int	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal.

Response

Generic Parameter for all XML responses

The following parameters are returned with every XML service response:

<?xml version="1.0" encoding="UTF-8"?>
<data apiversion="2.0.0" customermessage="Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction." merchantmessage="Bitte wählen Sie eine andere Zahlart. Der Kunde wurde aufgrund fehlgeschlagener Identitäts- bzw. Bonitätsprüfung abgelehnt." developermessage="" errorcode="32">
    <!-- additional request specific data -->
</data>

Attribute	Required	Data Type	Info
errorcode	+	non-negative int	Numerical error code - the standard value is "0” (no error). List of error codes
merchantmessage	+	string	Detailed error message to be displayed to the merchant only
customermessage	+	string	Detailed error message to be displayed to the customer
developermessage	+	string	Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD.

Please note that we may make changes to the API error messages that are returned for customers and merchants. In addition, new error codes and error messages can be added at any time.

Placing a Booking

Process Overview

“One-Step Booking Creation”

Using the “One-Step” booking model, the identity and credit check of the customer takes place after they have chosen a BillPay payment method and attempt to finalize the booking. In the case of a an approval (status=“APPROVED”) from BillPay, the booking is finalized in the BillPay system. In the case of a rejection (status=“DENIED”), the customer is to be presented with the appropriate message in the front-end (customermessage in the BillPay response) and offered of an alternate payment method.

XML Requests Used	Meaning	Time of execution	Service URL
preauthorize (`manualcapture`=“0”)	An identity and credit check will be performed	After the customer has selected the payment method and clicked to finalize their booking. When approved, the booking is finalized with this request.	[Base-URL]/preauthorize

Flowchart classic scoring

“Two Step Booking Creation”

Using the “Two-Step” booking model, the identity and credit check is performed after the customer has chosen a BillPay payment method and before the booking is finalized. The “Two-Step” model makes sense, when the payment method selection takes place before the actual availability of the flight or trip is known. In this case, you can check to see if the customer can pay using BillPay. If they are rejected, they can be re-directed to select an alternative payment method. If they are accepted, you can proceed to check whether or not the flight or trip is still available. If it is, the flight or trip can be booked and then the order can be finalized with BillPay.

XML service	Meaning	Time of execution	Service URL
preauthorize (`manualcapture`=“1”)	An identity and credit check will be performed	After the customer has selected the payment method in the booking process. When approved, the booking is not finalized with this request.	[Base-URL]/preauthorize
capture	Creation of the booking in the BillPay system	After the final booking	[Base-URL]/capture

Flowchart prescoring

Preauthorize

The preauthorize request is used to transmit all necessary information to perform the identity and credit check on the customer. The result of this check (either “APPROVED” or “DENIED”) will be sent back to your system in realtime and will determine whether or not the customer can use the selected BillPay payment method.

When the manualcapture flag is set to false, in the case of a positive authorization, the order will be created in the BillPay system with the unique ID sent in the reference parameter. From a legal viewpoint, this is the moment BillPay acquires the rights to the debt for this specific customer and booking.

Request

Data Node

This node contains the expecteddaystillshipping attribute. The expecteddaystillshipping is calculated as the amount of time between the date of departure for the first leg of the customer’s journey and the date of the booking in days. To demonstrate the calculation, a customer books a flight on April 8. The flight is from Berlin to Frankfurt and departs Tegel Airport at 8:00 on July 7. In this case, we must receive an “expecteddaystillshipping” value of 90.

<data
        requesttype="PREAUTHORIZE"
        tcaccepted="1"
        expecteddaystillshipping="0"
        manualcapture="0"
        paymenttype="7"
        apiversion="2.0.0"
        originofsale="o">
    <!-- additional request specific data -->
</data>

preauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
preauthorizeRequest
    .setTermsAndConditionAccepted(true)
    .setManualCapture(false)
    .setOriginOfSale(OriginOfSale.ONLINE_SHOP);

preauthorizeRequest.getPaymentDetails()
    .setPaymentType(PaymentType.PAYLATER_COLLATERAL_PROMISE);  

preauthorizeRequest.getShipping()
    .setDaysTillShipping(45);

<?php
use BillPay\Core\Requests\PreauthorizeFactory;
use BillPay\Core\Commons\Constants;

$preauthorizeRequest = PreauthorizeFactory::create();
$preauthorizeRequest
    ->disableManualCapture()
    ->setOriginOfSaleOnline();

$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_PAYLATER_COLLATERAL)
    ->acceptTermsOfUse();

$preauthorizeRequest->getShipping()
    ->setExpectedDaysTillShipping(45);

Attribute	Required	Data Type	Values	Info
requesttype	+	string	PREAUTHORIZE	Type of request
tcaccepted	+	bool	0/1	Boolean flag that indicates if the customer has accepted the BillPay terms of service / the data protection policy
expecteddaystillshipping	+	non-negative int		Required for Payment Type 7, 8 and 9: Amount of days until the customer will depart for their trip.
manualcapture	+	bool	0/1	Boolean flag that indicates if the booking is captured with the preauthorize request (flag set to “0”) or if a separate capture request is required to complete the booking (flag set to “1”).
paymenttype	+	positive int	N..1	ID of the desired payment method 7: PayLater Collateral Promise 8: Invoice Collateral Promise 9: Direct Debit Collateral Promise
apiversion	+	string	2.0.0	BillPay API Version
originofsale	+	string	A..1	Identifier for the point of origin of the purchase. u: Unknown o: Online shop p: Offline / POS t: Telesales / Call Center

Default Params Node (Merchant Credentials)

The merchant API credentials are generated and provided by BillPay.

<default_params
        mid="1234"
        pid="9999"
        passwordhash="25d55ad283aa400af464c76d713c07ad" />

preauthorizeRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")
    .setSessionId("clear text session ID");

<?php
$preauthorizeRequest
    ->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password')
    ->setSessionId('clear text session ID');

Attribute	Required	Data Type	Info
mid	+	positive int	Merchant ID
pid	+	positive int	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal.

Customer Details Node (customer billing address)

<customer_details
        customerid="123456"
        customertype="e"
        salutation="Herr"
        title=""
        firstname="Thomas"
        lastname="Testkunde"
        street="Tinnowitzer Straße"
        streetnumber="1"
        addressaddition=""
        zipcode="10115"
        city="Berlin"
        country="DEU"
        email="anyone@anymail.de"
        phone="03012345678"
        cellphone=""
        dateofbirth="19741012"
        language="de"
        ipaddress="80.111.120.1"
        customergroup="p" />

preauthorizeRequest.getCustomer()
    .setId("123456")
    .setCustomerType(CustomerType.EXISTING_CUSTOMER)
    .setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
    .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
    .setEmail("anymail@gmx.de")
    .setIpAddress("80.111.120.1")
    .setLanguageIso2("de")
    .getBillingAddress()
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setStreet("Tinnowitzer Straße")
        .setStreetNumber("1")
        .setZipCode("10115")
        .setCity("Berlin")
        .setCountryIso3("DEU")
        .setPhone("03012345678");

<?php
$preauthorizeRequest->getCustomer()
    ->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1980-10-14')
    ->setEmail('anymail@gmx.de')
    ->setIpAddress('80.111.120.1')
    ->setLanguageIso2('de')
    ->getBillingAddress()
        ->setSalutation('Herr')
        ->setFirstName('Thomas')
        ->setLastName('Testkunde')
        ->setStreet('Tinnowitzer Straße')
        ->setStreetNumber('1')
        ->setZipCode('10115')
        ->setCity('Berlin')
        ->setCountryIso3('DEU')
        ->setPhone('03012345678');

Attribute	Required	Data Type	Values	Info
customerid	-	string	AN..40	Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/)
customertype	-	string	A..1	Type of customer g: Guest e: Existing Customer n: New Customer
salutation	+	string	A..12	Default: See addendum `Salutations`
title	-	string	AN..20	Academic title (e.g. “Dr.”)
firstname	+	string	AN..40	First name
lastname	+	string	AN..40	Last name
street	+	string	AN..40	Street
streetnumber	-	string	AN..7	House number
addressaddition	-	string	AN..40	Address addition
zipcode	+	string	AN..7	ZIP code
city	+	string	AN..40	City
country	+	string	A..3	Customer country code: ISO3166 (alpha-3) (e.g. “DEU”)
email	+	string	AN..40 (excl. non-valid special characters)	Email address
phone	-*	string	AN..40	Phone number
cellphone	-	string	AN..40	Mobile number
dateofbirth	+	string	YYYYMMDD	Date of Birth - optional for business customers
language	+	string	A..2	Customer language: ISO3166-1 (alpha-2) (e.g. “de”)
ipaddress	+	string	IPv4 or IPv6 (IPv4-Embedded IPv6 Address)	IP address of the client
customergroup	+	string	A..1	Customer group p: Private b: Business

*phone is a mandatory field when paymenttype equals 7.

Shipping Details Node (customer shipping address)

This node contains either the boolean flag usebillingaddress set to “true” (1) or the flag set to “false” (0) with the full alternate shipping address.

<shipping_details
        usebillingaddress="1"
        salutation=""
        title=""
        firstname=""
        lastname=""
        street=""
        streetnumber=""
        addressaddition=""
        zipcode=""
        city=""
        country=""
        phone=""
        cellphone="" />

preauthorizeRequest.getCustomer().createShippingAddress()
    .setSalutation("Herr")
    .setFirstName("Thomas")
    .setLastName("Testkunde")
    .setStreet("Tinnowitzerstrasse")
    .setStreetNumber("1")
    .setZipCode("10115")
    .setCity("Berlin")
    .setCountryIso3("DEU")
    .setPhone("03012345678");

<?php
$preauthorizeRequest->getCustomer()->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Tinnowitzerstrasse')
    ->setStreetNumber('1')
    ->setZipCode('10115')
    ->setCity('Berlin')
    ->setCountryIso3('DEU')
    ->setPhone('03012345678');

Attribute	Required	Data Type	Values	Info
usebillingaddress	+	bool	0/1	0: Use deviating shipping address 1: Use the given billing address identifier that indicates if the shipping address is equal to the billing address
salutation	-	string	A..12	Default: See addendum `Salutations`
title	-	string	AN..20	Academic title (e.g. “Dr.”)
firstname	-	string	AN..40	First name
lastname	-	string	AN..40	Last name
street	-	string	AN..40	Street
streetnumber	-	string	AN..7	House number
addressaddition	-	string	AN..40	Address addition
zipcode	-	string	AN..7	ZIP code
city	-	string	AN..40	City
country	-	string	A..3	Customer country code: ISO3166 (alpha-3) (e.g. “DEU”)
phone	-	string	AN..40	Phone number
cellphone	-	string	AN..40	Mobile number

Company Details Node (Details about business customers)

In case the booking is for a business customer (customertype = “b”), additional information about said customer needs to be collected.

<company_details
        name="Testfirma"
        legalform="GmbH"
        registernumber="HRB 122 029 B"
        holdername="Testinhaber Owner"
        taxnumber="DE268874183" />

preauthorizeRequest.getCustomer().createCompany()
    .setName("Testfirma")
    .setLegalForm("GmbH")
    .setRegisterNumber("HRB 122 029 B")
    .setTaxNumber("DE268874183")
    .setCompanyProprietor("Testinhaber Owner");

Attribute	Required	Format	Values	Info
name	+	string	AN..200	Registered name of the company
legalform	+	string		Company legal form Defaults: see addendum legal forms
registernumber	-	string	AN..20	Company register number
holdername	-	string	AN..100	Owner’s full name
taxnumber	-	string		Valid tax ID (DEXXXXXXXXX)

Article Data Node (list of all booking positions) All information relating to the purchased products are collected in the article_data node. Every unique article is represented by an individual “article” XML tag. In the articletype attribute, please note that a “package including flight (id 2)” is the typical all inclusive package, where as the “combination of items including flight” (id 3) is for a “dynamic package,” which might include only a car rental and a flight or a realtime combination of a hotel and a flight.

<article_data>
    <article
            articleid="220-2365851307" 
            articlequantity="1" 
            articletype="1"
            articlename="LH188"
            articlepricenet="20567"
            articlepricegross="22115">
            <flight_information 
                departingfrom="TXL"
                departingon="20160818" 
                arrivingat="FRA" 
                arrivingon="20160818"
                bookingclass="bc" 
                routetype="ow" 
                tickettype="fl" />
    </article>           
</article_data>

preauthorizeRequest.getCart().createAndAddArticle()
    .setId("220-2365851307")
    .setQuantity(1)
    .setType(ArticleType.FLIGHT)
    .setName("LH188")
    .setPriceNet(20567)
    .setPriceGross(22115)
    .createFlight()
        .setDepartingFromAirport("TXL")
        .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2030/10/14"))
        .setArrivingAtAirport("FRA")
        .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2030/10/14"))
        .setBookingClass(BookingClass.BUSINESS_CLASS)
        .setRouteType(RouteType.ONE_WAY)
        .setTicketType(TicketType.NO_REBOOKING_FEE);

preauthorizeRequest.getCart().createAndAddArticle()
    .setId("220-2365851307")
    .setQuantity(1)
    .setType(ArticleType.FLIGHT)
    .setName("LH188")
    .setPriceNet(20567)
    .setPriceGross(22115)
    .createFlight()
        .setDepartingFromAirport("TXL")
        .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2030/10/14"))
        .setArrivingAtAirport("FRA")
        .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2030/10/14"))
        .setBookingClass(BookingClass.BUSINESS_CLASS)
        .setRouteType(RouteType.ONE_WAY)
        .setTicketType(TicketType.NO_REBOOKING_FEE);

<?php
/** @var \BillPay\Core\Requests\Preauthorize $preauthorizeRequest */
$preauthorizeRequest->getCart()->createAndAddArticle()
    ->setId('220-2365851307')
    ->setQuantity(1)
    ->setTypeFlight()
    ->setName('LH188')
    ->setPriceNet(20567)
    ->setPriceGross(22115)
    ->getFlight()
        ->setDepartingFromAirport('TXL')
        ->setDepartingOn('2030-10-14')
        ->setArrivingAtAirport('FRA')
        ->setArrivingOn('2030-10-14')
        ->setIsBusinessClass()
        ->setIsOneWay()
        ->setIsFreeRebooking();

$preauthorizeRequest->getCart()->createAndAddArticle()
    ->setId('220-2365851307')
    ->setQuantity(1)
    ->setTypeFlight()
    ->setName('LH188')
    ->setPriceNet(20567)
    ->setPriceGross(22115)
    ->getFlight()
        ->setDepartingFromAirport('TXL')
        ->setDepartingOn('2030-10-14')
        ->setArrivingAtAirport('FRA')
        ->setArrivingOn('2030-10-14')
        ->setIsBusinessClass()
        ->setIsOneWay()
        ->setIsFreeRebooking();

Attribute	Required	Data Type	Values	Info
articleid	+	string	AN..20	Unique article ID
articlename	+	string	AN..50	Article name
articletype	+	non-negative int	N..1	Item classification 0: Miscellaneous 1: Flight 2: Package including flight 3: Combination of items including flight 4: Combination of items without a flight 5: Hotel 6: Travel Insurance 7: Auto Rental
articlequantity	+	positive int	N..7	Article quantity
articlepricenet	+	int	N..7	Article net price (excluding taxes in the smallest currency unit; 1,00 EUR = 100)
articlepricegross	+	int	N..7	Article gross price (including taxes in the smallest currency unit; 1,00 EUR = 100)
articlecategory	-	string	AN..50	Article Category
articlesubcategory1	-	string	AN..50	Article Sub-Category
articlesubcategory2	-	string	AN..50	Article Sub-Category
flight_information	- (+ if articletype 1-3)			Child element of the article node (max occurrences 1)
↳departingfrom	- (+ if articletype 1-3)	string	A..3	Departure airport: IATA Location Identifiers
↳departingon	- (+ if articletype 1-3)	string	YYYYMMDD	Date of departure
↳arrivingat	- (+ if articletype 1-3)	string	A..3	Arrival airport: IATA Location Identifiers
↳arrivingon	- (+ if articletype 1-3)	string	YYYYMMDD	Date of arrival
↳bookingclass	- (+ if articletype 1-3)	string	A..2	Class of the ticket na (not available) bc: Business-class fc: First class co: Coach
↳routetype	- (+ if articletype 1-3)	string	A..2	Route na (not available) ow: One-way rt: Round trip
↳tickettype	- (+ if articletype 1-3)	string	A..2	Ticket type na: Not available nr: Rebooking not allowed rf: Rebooking for a fee fl: No rebooking fees (flex)

Bank Account Node (Customer Bank Info)

The bank_account node is only processed when direct debit or PayLater is the selected BillPay payment method. This is the case if parameter paymenttype has values “7” or “9”. Otherwise the bank data is ignored.

<bank_account
        accountholder="Thomas Testkunde"
        accountnumber="DE12500105170648489890"
        sortcode="" />

preauthorizeRequest.getPaymentDetails().createBankAccount()
    .setAccountHolder("Thomas Testkunde")
    .setAccountNumber("DE12500105170648489890");

<?php
$preauthorizeRequest->getBankAccount()
    ->setAccountHolder('Thomas Testkunde')
    ->setAccountNumber('DE12500105170648489890');

Attribute	Required	Data Type	Values	Info
accountholder	+ (if paymentType in {7,9)	string	AN..100	First and last name of account holder
accountnumber	+ (if paymentType in {7,9})	int	AN..30	IBAN - International Bank Account Number
sortcode	+ (if paymentType in {7,9} AND the IBAN does not begin with DE )	int	AN..11	BIC - Bank Identifier Code

Total Node

The total node contains the total values and booking related reference information.

<total
        shippingname="Express Versand"
        shippingpricenet="840"
        shippingpricegross="1000"
        rebatenet="930"
        rebategross="1000"
        orderamountnet="40204"
        orderamountgross="43230"
        currency="EUR"
        reference="ZYLOGT"
        merchantinvoicenumber="1234567" />

preauthorizeRequest.getShipping()
    .setName("Express Versand")
    .setPriceNet(840)
    .setPriceGross(1000);

preauthorizeRequest.getCart()
    .setOrderAmountNet(40204)
    .setOrderAmountGross(43230)
    .setCurrencyIso3("EUR")
    .setReference("ZYLOGT")
    .createAndAddRebate()
        .setRebateNet(930)
        .setRebateGross(1000);

<?php
$preauthorizeRequest
    ->setReference('ZYLOGT');

$preauthorizeRequest->getShipping()
    ->setName('Express Versand')
    ->setPriceNet(840)
    ->setPriceGross(1000);

$preauthorizeRequest->getCart()
    ->setOrderAmountNet(40204)
    ->setOrderAmountGross(43230)
    ->setCurrencyIso3('EUR')
    ->createAndAddRebate()
        ->setPriceNet(930)
        ->setPriceGross(1000);

Attribute	Required	Data Type	Values	Info
shippingname	+	string	AN..50	Shipping method name (e.g. “Express”, “Email”, etc.)
shippingpricenet	+	non-negative int	N..7	Net value (excluding taxes) of all booking specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0
shippingpricegross	+	non-negative int	N..7	Gross value (including taxes) of all booking specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0
rebatenet	+	non-negative int	N..7	Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the booking total value (1,00 EUR = 100), if none please use 0
rebategross	+	non-negative int	N..7	Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the booking total value (1,00 EUR = 100), if none please use 0
orderamountnet	+	positive int	N..7	Net value (excluding taxes) of the booking total (1,00 EUR = 100) [(sum of all articlepricenet) + shippingpricenet - rebatenet]
orderamountgross	+	positive int	N..7	Gross value (including taxes) of the booking total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency	+	string	A..3	3-digit currency code of the booking (e.g. “EUR”): ISO4217
reference	-	string	AN..40	Unique booking ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|)*
merchantinvoicenumber	-	string	AN..40	Unique invoice number from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|\|#\|:\|.)*

Fraud Detection Node

This node contains the session ID parameter that is used to identify fraudulent customers/sessions and prevent them from using the BillPay payment methods. This serves to prevent fraud in your shop and must always have the same value as the identifier designated in the configuration of the JavaScript widget.

<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />

preauthorizeRequest
    .setSessionId("clear text session ID");

<?php
$preauthorizeRequest->setSessionId('clear text session ID');

Attribute	Required	Data Type	Values	Info
sessionid	+	string	AN..100	A session ID (must be equal to the session ID set in the JavaScript widget configuration script)

Rate Request Node

For the payment methods PayLater / Ratenkauf (paymenttype=“7”) some additional parameters have to be passed to the BillPay system. These additional parameters describe the instalment plan itself. The values are set and passed along in your checkout form by our widget when the customer selects their preferred payment plan duration and proceeds through your checkout.

<rate_request ratecount="6" terminmonths="6" totalamountgross="45823" />

preauthorizeRequest.getPaymentDetails().createInstalment()
    .setRateCount(6)
    .setTermInMonths(6)
    .setTotalAmountGross(45823);

<?php
$preauthorizeRequest->getPaymentMethod()
    ->setRateTerm(6)
    ->setRateCount(6)
    ->setTotal(45823);

Attribute	Required	Data Type	Values	Info
ratecount	+	int	N..2	Number of instalments to be paid during the term. This is the `billpay[paylater_instalments_count]` value passed by the widget.
terminmonths	+	int	N..2	Term of the instalment plan. This is the `billpay[paylater_duration]` value passed by the widget.
totalamountgross	+	positive int	N..7	Total amount of the instalments plan including the interest / PayLater fee. This is the `billpay[paylater_col_total_amount]` value passed by the widget.

Trip Data Node

The attributes in the flight_information node are required for PayLater Collateral Promise (paymenttype=“7”), Invoice Collateral Promise (paymenttype=“8”), and Direct Debit Collateral Promise (paymenttype=“9”) when one of the articles in the booking has the articletype = 1 (Flight), 2 (package w/flight) or 3 (combination of items w/flight). For all other article types, please use the default values that are listed.

Please Note: The groupsize attribute must be equal to the number of travelers listed in the traveler_list node. So if there is a groupsize of 2, there must be 2 traveller nodes filled with the relevant information in the traveler_list node.

<trip_data 
        historicaltripcount="1" 
        historicaltripamount="80000" 
        historicaltripcurrency="EUR">
    <traveler_list groupsize="2">
        <traveler 
            salutation="Herr" 
            firstname="Thomas" 
            lastname="Testkunde" 
            dateofbirth="19741012">
            <flight_information>
                    <frequent_flyer 
                        membership="1" 
                        program="1"
                        membershipid="12345" />
            </flight_information>
        </traveler> 
       <traveler 
            salutation="Frau" 
            firstname="Thomassina" 
            lastname="Testkunde" 
            dateofbirth="19720210">
            <flight_information>
                    <frequent_flyer 
                        membership="0" 
                        program="0"
                        membershipid="0" />
            </flight_information>
        </traveler>
    </traveler_list>
</trip_data>

TripData tripData = preauthorizeRequest.createTripData();
tripData.setGroupSize(2)
    .setHistoricalTripCount(1)
    .setHistoricalTripAmount(80000)
    .setHistoricaltripCurrency("EUR");

tripData.createAndAddTraveler()
    .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
    .setSalutation("mr")
    .setFirstName("Thomas")
    .setLastName("Testkunde")
    .setMembership(1)
    .setProgram(1)
    .setMembershipId("12345");

tripData.createAndAddTraveler()
    .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
    .setSalutation("mrs")
    .setFirstName("Thomassina")
    .setLastName("Testkunde")
    .setMembership(0)
    .setProgram(0)
    .setMembershipId("0");

<?php
/** @var \BillPay\Core\Requests\Preauthorize $preauthorizeRequest */
$tripData = $preauthorizeRequest->getTrip();

$tripData
    ->setHistoricalTripCount(1)
    ->setHistoricalTripAmount(80000)
    ->setHistoricalTripCurrency('EUR');

$tripData->createAndAddTraveler()
    ->setDateOfBirth('1980-10-14')
    ->setSalutation('mr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setIsFrequentFlyerMember() // 1
    ->setFrequentFylerProgramId(1)
    ->setFrequentFlyerMembershipId('12345');

$tripData->createAndAddTraveler()
    ->setDateOfBirth('1980-10-14')
    ->setSalutation('mrs')
    ->setFirstName('Thomassina')
    ->setLastName('Testkunde')
    ->setIsUnknownFrequentFlyerMember();

Attribute	Required	Data Type	Values	Info
historicaltripcount	+	non-negative int	N..3	Number of tickets purchased in the past year by the billing person (e.g. 08/04/2015 - 08/04/2016). (default value 0)
historicaltripamount	+	non-negative int	N..7	Total value of tickets purchased in the last year by the billing person in Euros (1,00 EUR = 100) (default value 0)
historicaltripcurrency	+	string	A..3	3-digit currency code of the booking (e.g. “EUR”): ISO4217
↳traveler_list	+			Child node of trip data (max occurences 1)
↳groupsize	+	positive int	N..3	Number traveling or booking.
↳traveler	+			Child node of traveler_list (max occurences 20)
↳salutation	+	string	A..12	Default: See addendum `Salutations`
↳firstname	+	string	AN..40	Traveller’s first name
↳lastname	+	string	AN..40	Traveller’s last name
↳dateofbirth	+	string	YYYYMMDD	Traveller’s date of birth
↳flight_information	+			Child element of traveler (max occurrences 1)
↳frequent_flyer	+			Child element of flight _information (max occurrences 1)
↳membership	+	int	N..1	Frequent flyer membership: 0: Not available 1: Yes, membership in a frequent flyer program 2: No membership in a frequent flyer program
↳program	+	int	N..3	Frequent flyer programs
↳membershipid	+	string	AN..40	Traveller’s frequent flyer membership ID (If the customer is not a member of a frequent flyer program, please use 0 as the default.)

Response

Data Node

The data node contains all relevant information about the scoring result. In addition to the pure result (“APPROVED” / “DENIED”) it contains a unique BillPay transaction ID (transactionid) that identifies the the request and result.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="PREAUTHORIZE"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage=""
        status="APPROVED"
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337">
    <!-- additional response specific data -->
</data>

System.out.println(preauthorizeResponse.getErrorCode());
System.out.println(preauthorizeResponse.getMerchantMessage());
System.out.println(preauthorizeResponse.getDeveloperMessage());
System.out.println(preauthorizeResponse.getCustomerMessage());
System.out.println(preauthorizeResponse.getAuthorizationStatus());
System.out.println(preauthorizeResponse.getTransactionId());

<?php
/** @var \BillPay\Core\Responses\Preauthorize $preauthorizeResponse */
$preauthorizeResponse->getErrorCode();
$preauthorizeResponse->getMerchantMessage();
$preauthorizeResponse->getDeveloperMessage();
$preauthorizeResponse->getCustomerMessage();
$preauthorizeResponse->getStatus();
$preauthorizeResponse->getTransactionId();

Attribute	Required	Data Type	Values	Info
responsetype	+	string	PREAUTHORIZE	Identifies for which request type the response is
errorcode	+	non-negative int	N..3	Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list
merchantmessage	+	string		Detailed error message to be displayed to the merchant only
customermessage	+	string		Detailed error message to be displayed to the customer
developermessage	+	string		Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD.
status	-	string	APPROVED / DENIED	Status of the identity and credit check. Can be empty in the case of a validation error.
transactionid	-	string	AN..50	Unique BillPay transaction ID

Corrected Address Node (Normalized customer address)

This node returns the normalized customer address.

<corrected_address
        street="Zinnowitzer Str."
        streetnumber="1"
        zipcode="10115"
        city="Berlin"
        country="DEU" />

System.out.println(preauthorizeResponse.getCorrectedAddress().getStreet());
System.out.println(preauthorizeResponse.getCorrectedAddress().getStreetNumber());
System.out.println(preauthorizeResponse.getCorrectedAddress().getZipCode());
System.out.println(preauthorizeResponse.getCorrectedAddress().getCity());
System.out.println(preauthorizeResponse.getCorrectedAddress().getCountry());

<?php
/** @var \BillPay\Core\Responses\Preauthorize $preauthorizeResponse */
$preauthorizeResponse->getNormalizedAddress()->getStreet();
$preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
$preauthorizeResponse->getNormalizedAddress()->getZipCode();
$preauthorizeResponse->getNormalizedAddress()->getCity();
$preauthorizeResponse->getNormalizedAddress()->getCountry();

Attribute	Required	Data Type	Values	Info
street	+	string	AN..50	Normalized street
streetnumber	+	string	AN..15	Normalized house number
zipcode	+	string	AN..7	Normalized ZIP code
city	+	string	AN..50	Normalized city
country	+	string	A..3	Normalized country code (e.g. “DEU”): ISO3166 (alpha-3)

Invoice Bank Account Node (only for “Invoice” - paymenttype = “8”)

This node returns the BillPay bank account data to be used by the customer when paying for their booking placed. This information must be parsed and printed on the invoice document the customers receive with their documents.

If it is not possible to save the invoice reference from the BillPay API response, it can also be produced according to the following schema: BP/ Example: BPZYLOGT/9999 (The merchant’s booking code is ZYLOGT and ID for this merchant at BillPay is 9999).

<invoice_bank_account
        activationperformed="0"
        accountholder="BillPay GmbH"
        accountnumber="DE07312312312312312"
        bankcode="BELADEBEXXX"
        bankname="Sparkasse Berlin"
        invoiceduedate=""
        invoicereference="BPZYLOGT/9999" />

System.out.println(preauthorizeResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(preauthorizeResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(preauthorizeResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(preauthorizeResponse.getInvoiceBankAccount().getBankCode());
System.out.println(preauthorizeResponse.getInvoiceBankAccount().getBankName());
System.out.println(preauthorizeResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(preauthorizeResponse.getInvoiceBankAccount().getInvoiceReference());

<?php
/** @var \BillPay\Core\Responses\Preauthorize $preauthorizeResponse */
$preauthorizeResponse->getInvoiceBankAccount()->isActivationPerformed();
$preauthorizeResponse->getInvoiceBankAccount()->getAccountHolder();
$preauthorizeResponse->getInvoiceBankAccount()->getAccountNumber();
$preauthorizeResponse->getInvoiceBankAccount()->getBankCode();
$preauthorizeResponse->getInvoiceBankAccount()->getBankName();
$preauthorizeResponse->getInvoiceBankAccount()->getInvoiceDueDate();
$preauthorizeResponse->getInvoiceBankAccount()->getInvoiceReference();

Attribute	Required	Data Type	Values	Info
activationperformed	+	bool	0/1	If the booking is activated (payment due date set)
accountholder	+	string	AN..255	Account holder
accountnumber	+	string	AN..40	BillPay IBAN - International Bank Account Number
bankcode	+	string	AN..16	BillPay BIC - Bank Identifier Code
bankname	+	string	AN..255	Name of the BillPay bank
invoiceduedate	+	string	N..8	Payment due date in the format: YYYYMMDD
invoicereference	+	string	AN..255	Transaction purpose
esrreference	-	string	AN	Reference number for Swiss payment/deposit slips
esrcodeline	-	string	AN	Bank code for Swiss payment/deposit slips

Credit Card Node

This node returns credit card details for the merchant to process.

<credit_card
        accountholder="BillPay GmbH"
        cardnumber="5105105105105100"
        securitycode="123"
        expirationdate="201908"
        activationdate="20170813" />

System.out.println(preauthorizeResponse.getCreditCard().getAccountHolder());
System.out.println(preauthorizeResponse.getCreditCard().getCardNumber());
System.out.println(preauthorizeResponse.getCreditCard().getSecurityCode());
System.out.println(preauthorizeResponse.getCreditCard().getExpirationDate());
System.out.println(preauthorizeResponse.getCreditCard().getActivationDate());

<?php
/** @var \BillPay\Core\Responses\Preauthorize $preauthorizeResponse */
$preauthorizeResponse->getCreditCard()->getAccountHolder();
$preauthorizeResponse->getCreditCard()->getCardNumber();
$preauthorizeResponse->getCreditCard()->getSecurityCode();
$preauthorizeResponse->getCreditCard()->getExpirationDate();
$preauthorizeResponse->getCreditCard()->getActivationDate();

Attribute	Required	Data Type	Values	Info
accountholder	+	string	AN..40	The virtual credit card account holder
cardnumber	+	long int	N..16	The virtual credit card number
securitycode	+	string	N..3	3 digit security code of the virtual credit card (CVV/CVC)
expirationdate	+	string	N..6	Date the virtual card expires in the format: YYYYMM
activationdate	+	string	N..8	Date the virtual card becomes active in the format: YYYYMMDD

Invoice Numbers Node

This node is returned if BillPay sends the invoice to customers for the merchants.

<assigned_invoice_number>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="ZYLOGT#1" />
</assigned_invoice_number>

InvoiceNumber invoiceNumber = requestResonse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());

<?php
/** @var \BillPay\Core\Responses\Preauthorize $preauthorizeResponse */
$invoiceNumbers = $preauthorizeResponse->getInvoiceNumbers();

$invoiceNumbers[0]->getBillpayInvoiceNumber();
$invoiceNumbers[0]->getInvoiceId();

Attribute	Required	Data Type	Values	Info
invoice_number	+	Child node of the assigned_invoice_number node
↳invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
↳billpayinvoicenumber	+	string	AN..40	Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|\|#\|:\|.)*

Instalment Details Node (only for PayLater - paymenttype = “7”)

In this node, BillPay returns information related to the instalment plan.

<instalment_details>
    <instl_plan numinst="6">
        <calc>
            <duration_in_months>
                6
            </duration_in_months>
            <fee_percent>
                6.00
            </fee_percent>
            <fee_total>
                2520
            </fee_total>
            <total_pymt>
                45520
            </total_pymt>
            <eff_anual>
                24.21
            </eff_anual>
            <nominal>
                20.57
            </nominal>
        </calc>
        <instl_list>
            <instl date="20160531" type="immediate">
                3520
            </instl>
            <instl date="20160630" type="first">
                7000
            </instl>
            <instl date="20160731" type="date">
                7000
            </instl>
            <instl date="20160831" type="date">
                7000
            </instl>
            <instl date="20160930" type="date">
                7000
            </instl>
            <instl date="20161031" type="date">
                7000
            </instl>
            <instl date="20161130" type="date">
                7000
            </instl>
        </instl_list>
    </instl_plan>
</instalment_details>

InstalmentPlan instalmentPlan = requestResonse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());

InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());

<?php
/** @var \BillPay\Core\Responses\Preauthorize $preauthorizeResponse */
$instalmentDetails = $preauthorizeResponse->getInstalmentDetails();
$instalmentDetails->getDurationInMonth();
$instalmentDetails->getFeePercentage();
$instalmentDetails->getFee();
$instalmentDetails->getTotalAmount();
$instalmentDetails->getAnnualPercentageRate();
$instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
$instalments[0]->getAmount();
$instalments[0]->getDate();
$instalments[0]->getType();

Attribute	Required	Data Type	Values	Info
instl_plan	+			parent node - this node only appears for paymenttype=“7” (PayLater)
numinst	+	positive int	N	Number of instalments
calc	+			Child node of the instl_plan node
↳duration_in_months	+	int	N	Duration of the payment plan in months
↳fee_percent	+	decimal		PayLater fee (%) between 0.00 and 100.00
↳fee_total	+	non-negative int	N	Total PayLater fees
↳total_pymt	+	positive int	N	Total amount of the PayLater booking (including the fees)
↳eff_anual	+	decimal		Annual effective interest rate (%) between 0.00 and 100.00
↳nominal	+	decimal		Annual nominal interest rate (%) between 0.00 and 100.00
instl_list	+ (node)			Child node of the instl_plan node.
↳instl	+ (node)			Child node of the instl_list node.
↳date	+	DATE	YYYYMMDD	Date of the instalment
↳type	+	string	AN	Type of Instalment („immediate“, „first“, „date“, „fee“)

Capture

The capture request is used to complete the booking when a two-step capture process is being implemented and the manualcapture attribute is set to 1 in the preauthorize request. Legally speaking, it is with the successful completion of the capture request, that the customer’s debt to the travel partner is transferred from the travel partner to BillPay.

Request

Data Node

<data 
    requesttype="CAPTURE" 
    apiversion="2.0.0">
    <!-- Request Data -->
</data>

Attribute	Data Type	Values	Info
requesttype	string	CAPTURE	Type of request
apiversion	string	2.0.0	BillPay API Version

Default Params Node (Merchant Credentials)

The merchant API credentials are generated and provided by BillPay.

<default_params
        mid="1234"
        pid="9999"
        passwordhash="25d55ad283aa400af464c76d713c07ad" />

captureRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")

<?php
/** @var \BillPay\Core\Requests\Capture $captureRequest */
$captureRequest
    ->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');

Attribute	Required	Data Type	Info
mid	+	positive int	Merchant ID
pid	+	positive int	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal.

Capture Params Node

This node contains the the unique BillPay transaction ID (retrieved from the original preauthorization server response) and the desired booking reference.

<capture_params
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337"
        orderamountgross="43230" 
        currency="EUR" 
        reference="ZYLOGT" 
        merchantinvoicenumber="1234567"
        customerid="123456789" />

captureRequest
    .setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
    .setMerchantInvoiceNumber("1234567");

captureRequest.getCustomer()
    .setCustomerId("123456789");

captureRequest.getCart()
    .setReference("ZYLOGT")
    .setCurrencyIso3("EUR")
    .setOrderAmountGross(43230);

<?php
/** @var \BillPay\Core\Requests\Capture $captureRequest */
$captureRequest
    ->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
    ->setReference('ZYLOGT')
    ->setMerchantInvoiceNumber('1234567');

$captureRequest->getCustomer()
    ->setId('123456789');

$captureRequest->getCart()
    ->setCurrencyIso3('EUR')
    ->setOrderAmountGross(43230);

Attribute	Required	Data Type	Values	Info
transactionid	+	string	AN..50	Unique BillPay transaction ID for this booking - returned in the preauthorize response
orderamountgross	+	positive int	N..7	Gross value (including taxes) of the booking total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency	+	string	A..3	3-digit currency code of the booking (e.g. “EUR”): ISO4217
reference	-	string	AN..40	Unique booking ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|)*
merchantinvoicenumber	-	string	AN..40	Unique invoice number from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|\|#\|:\|.)*
customerid	-	string	AN.40	Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/)

Response

With the capture response, you can determine whether or not the booking has been successfully completed at BillPay based upon the returned error code. When error_code=“0” is returned, the booking has been placed in the BillPay system.

Data Node

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="CAPTURE"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage="">
</data>

System.out.println(captureResponse.getErrorCode());
System.out.println(captureResponse.getMerchantMessage());
System.out.println(captureResponse.getDeveloperMessage());
System.out.println(captureResponse.getCustomerMessage());

<?php
/** @var \BillPay\Core\Responses\Capture $captureResponse */
$captureResponse->getErrorCode();
$captureResponse->getMerchantMessage();
$captureResponse->getDeveloperMessage();
$captureResponse->getCustomerMessage();

Attribute	Required	Data Type	Values	Info
responsetype	+	string	CAPTURE	Identifies for which request type the response is
errorcode	+	non-negative int	N..3	Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list
merchantmessage	+	string		Detailed error message to be displayed to the merchant only
customermessage	+	string		Detailed error message to be displayed to the customer
developermessage	+	string		Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD.

Invoice Bank Account Node (only for “Invoice” - paymenttype 8)

<invoice_bank_account
        activationperformed="0"
        accountholder="BillPay GmbH"
        accountnumber="DE07312312312312312"
        bankcode="BELADEBEXXX"
        bankname="Sparkasse Berlin"
        invoiceduedate="20170813"
        invoicereference="BPZYLOGT/9999" />

System.out.println(captureResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(captureResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(captureResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(captureResponse.getInvoiceBankAccount().getBankCode());
System.out.println(captureResponse.getInvoiceBankAccount().getBankName());
System.out.println(captureResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(captureResponse.getInvoiceBankAccount().getInvoiceReference());

<?php
/** @var \BillPay\Core\Responses\Capture $captureResponse */
$captureResponse->getInvoiceBankAccount()->isActivationPerformed();
$captureResponse->getInvoiceBankAccount()->getAccountHolder();
$captureResponse->getInvoiceBankAccount()->getAccountNumber();
$captureResponse->getInvoiceBankAccount()->getBankCode();
$captureResponse->getInvoiceBankAccount()->getBankName();
$captureResponse->getInvoiceBankAccount()->getInvoiceDueDate();
$captureResponse->getInvoiceBankAccount()->getInvoiceReference();

Attribute	Required	Data Type	Values	Info
activationperformed	+	bool	0/1	If the booking is activated (payment due date set)
accountholder	+	string	AN..255	Account holder
accountnumber	+	string	AN..40	BillPay IBAN
bankcode	+	string	AN..16	BillPay BIC
bankname	+	string	AN..255	Name of the BillPay bank
invoiceduedate	+	string	N..8	Payment due date in the format: YYYYMMDD
invoicereference	+	string	AN..255	Transaction purpose
esrreference	-	string	AN	Reference number for Swiss payment/deposit slips
esrcodeline	-	string	AN	Bank code for Swiss payment/deposit slips

Credit Card Node

This node returns credit card details for the merchant to process.

<credit_card
        accountholder="BillPay GmbH"
        cardnumber="5105105105105100"
        securitycode="123"
        expirationdate="201908"
        activationdate="20170813" />

System.out.println(captureResponse.getCreditCard().getAccountHolder());
System.out.println(captureResponse.getCreditCard().getCardNumber());
System.out.println(captureResponse.getCreditCard().getSecurityCode());
System.out.println(captureResponse.getCreditCard().getExpirationDate());
System.out.println(captureResponse.getCreditCard().getActivationDate());

<?php
/** @var \BillPay\Core\Responses\Capture $captureResponse */
$captureResponse->getCreditCard()->getAccountHolder();
$captureResponse->getCreditCard()->getCardNumber();
$captureResponse->getCreditCard()->getSecurityCode();
$captureResponse->getCreditCard()->getExpirationDate();
$captureResponse->getCreditCard()->getActivationDate();

Attribute	Required	Data Type	Values	Info
accountholder	+	string	AN..40	The virtual credit card account holder
cardnumber	+	long int	N..16	The virtual credit card number
securitycode	+	string	N..3	3 digit security code of the virtual credit card (CVV/CVC)
expirationdate	+	string	N..6	Date the virtual card expires in the format: YYYYMM
activationdate	+	string	N..8	Date the virtual card becomes active in the format: YYYYMMDD

Invoice Numbers Node

This node is returned if BillPay sends the invoice to customers for the merchants.

<assigned_invoice_number>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="ZYLOGT#1" />
</assigned_invoice_number>

InvoiceNumber invoiceNumber = requestResonse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());

Attribute	Required	Data Type	Values	Info
invoice_number	+			Child node of the assigned_invoice_number node
↳invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
↳billpayinvoicenumber	+	string	AN..40	Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|\|#\|:\|.)*

Instalment Details Node (only for PayLater/Ratenkauf)

In this node, BillPay returns information related to the instalment plan.

<instalment_details>
    <instl_plan numinst="6">
        <calc>
            <duration_in_months>
                6
            </duration_in_months>
            <fee_percent>
                6.00
            </fee_percent>
            <fee_total>
                2520
            </fee_total>
            <total_pymt>
                45520
            </total_pymt>
            <eff_anual>
                24.21
            </eff_anual>
            <nominal>
                20.57
            </nominal>
        </calc>
        <instl_list>
            <instl date="20160531" type="immediate">
                3520
            </instl>
            <instl date="20160630" type="first">
                7000
            </instl>
            <instl date="20160731" type="date">
                7000
            </instl>
            <instl date="20160831" type="date">
                7000
            </instl>
            <instl date="20160930" type="date">
                7000
            </instl>
            <instl date="20161031" type="date">
                7000
            </instl>
            <instl date="20161130" type="date">
                7000
            </instl>
        </instl_list>
    </instl_plan>
</instalment_details>

InstalmentPlan instalmentPlan = requestResonse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());

InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());

Attribute	Required	Data Type	Values	Info
instl_plan	+			Parent node - this node only appears for paymenttype=“7” (PayLater)
numinst	+	positive int	N	Number of instalments
calc	+			Child node of the instl_plan node
↳duration_in_months	+	int	N	Duration of the payment plan in months
↳fee_percent	+	decimal		PayLater fee (%) between 0.00 and 100.00
↳fee_total	+	non-negative int	N	Total PayLater fees
↳total_pymt	+	positive int	N	Total amount of the PayLater booking (including the fees)
↳eff_anual	+	decimal		Annual effective interest rate (%) between 0.00 and 100.00
↳nominal	+	decimal		Annual nominal interest rate (%) between 0.00 and 100.00
instl_list	+ (node)			Child node of the instl_plan node.
↳instl	+ (node)			Child node of the instl_list node.
↳date	+	DATE	YYYYMMDD	Date of the instalment
↳type	+	string	AN	Type of Instalment („immediate“, „first“, „date“, „fee“)

Managing a Booking

Request Overview

XML service	Meaning	Time of execution	Service URL
Cancellation	A full cancellation of the existing booking which leaves the booking value at 0 €.	Usually this action is triggered by a backend workflow or scheduled task/cron job.	[Base-URL]/cancel
Editing the booking	Any change in the content of the existing booking or the included fees/rebates of the booking.	Usually triggered when elements of the booking that impact the overall cost have changed or the booking has been cancelled, but a cancellation fee remains.	[Base-URL]/editCartContent

Cancel

Using the cancel request, an existing booking can be fully cancelled and the debt in will be closed with a value of 0 €. If the customer has already transferred money or the customer’s account was already debited, the funds will be automatically returned and a notification email will be sent to the customer.

Request

Data Node

<data
        requesttype="CANCEL"
        apiversion="2.0.0">
    <!-- Request Data -->
</data>

Attribute	Data Type	Values	Info
requesttype	string	CANCEL	Type of request
apiversion	string	2.0.0	BillPay API Version

Default Params Node (Merchant Credentials)

The merchant API credentials are generated and provided by BillPay.

<default_params
        mid="1234"
        pid="9999"
        passwordhash="25d55ad283aa400af464c76d713c07ad" />

cancelRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")

Attribute	Required	Data Type	Info
mid	+	positive int	Merchant ID
pid	+	positive int	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal.

Cancel Params Node

<cancel_params
        reference="ZYLOGT"
        orderamountgross="43230"
        currency="EUR" />

cancelRequest.getCart()
    .setReference("ZYLOGT")
    .setCurrencyIso3("EUR")
    .setOrderAmountGross(43230);

Attribute	Required	Data Type	Values	Info
reference	+	string	AN..40	Unique booking ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|)*
orderamountgross	+	positive int	N..7	Gross value (including taxes) of the booking total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency	+	string	A..3	3-digit currency code of the booking (e.g. “EUR”): ISO4217

Response

The BillPay server response for the cancel request will not return any additional fields besides the error code / error message.

Data Node

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="CANCEL"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage="">
</data>

System.out.println(cancelResponse.getErrorCode());
System.out.println(cancelResponse.getMerchantMessage());
System.out.println(cancelResponse.getDeveloperMessage());
System.out.println(cancelResponse.getCustomerMessage());

Attribute	Required	Data Type	Values	Info
responsetype	+	string	CANCEL	Identifies for which request type the response is
errorcode	+	non-negative int	N..3	Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list
merchantmessage	+	string		Detailed error message to be displayed to the merchant only
customermessage	+	string		Detailed error message to be displayed to the customer
developermessage	+	string		Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD.

Edit Cart Content

Using the editCartContent request, the content of an booking can be adjusted. Using this call, articles can be removed, fees reduced or increased.

Adding articles or increasing fees must follow certain predefined rules:

If the new booking value is lower than the old one, the edit will always succeed.
If the new booking value is higher than the old one, BillPay will perform a risk check for the new amount. If the risk check for the increased amount fails, the request will be rejected with the error code 105 and the booking will not be adjusted.

The request itself contains the information for the new desired booking. All differences between old and new booking will then be added/removed.

Request

Data Node

<data
        requesttype="EDIT_CART_CONTENT"
        apiversion="2.0.0"
    <!-- Request Data -->
</data>

Attribute	Data Type	Values	Info
requesttype	string	EDIT_CART_CONTENT	Type of request
apiversion	string	2.0.0	BillPay API Version

Default Params Node (Merchant Credentials)

The merchant API credentials are generated and provided by BillPay.

<default_params
        mid="1234"
        pid="9999"
        passwordhash="25d55ad283aa400af464c76d713c07ad" />

editCartContentRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")

Attribute	Required	Data Type	Info
mid	+	positive int	Merchant ID
pid	+	positive int	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal.

Total Node

The total node contains all generic information about the booking and all connected fees / rebates.

<total
        shippingname="Express Versand"
        shippingpricenet="0"
        shippingpricegross="0"
        rebatenet="930"
        rebategross="1000"
        orderamountnet="11675"
        orderamountgross="14000"
        currency="EUR"
        reference="ZYLOGT" />

editCartContentRequest.getShipping()
    .setName("none")
    .setPriceNet(0)
    .setPriceGross(0);

editCartContentRequest.getCart()
    .setOrderAmountNet(11675)
    .setOrderAmountGross(14000)
    .setCurrencyIso3("EUR")
    .setReference("ZYLOGT")
    .createAndAddRebate()
        .setRebateNet(930)
        .setRebateGross(1000);

Attribute	Required	Data Type	Values	Info
shippingname	+	string	AN..50	Shipping method name (e.g. “Express”, “Email”, etc.)
shippingpricenet	+	non-negative int	N..7	Net value (excluding taxes) of all booking specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0
shippingpricegross	+	non-negative int	N..7	Gross value (including taxes) of all booking specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0
rebatenet	+	non-negative int	N..7	Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the booking total value (1,00 EUR = 100), if none please use 0
rebategross	+	non-negative int	N..7	Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the booking total value (1,00 EUR = 100), if none please use 0
orderamountnet	+	positive int	N..7	Net value (excluding taxes) of the booking total (1,00 EUR = 100) [(sum of the remaining articlepricenet) + shippingpricenet - rebatenet]
orderamountgross	+	positive int	N..7	Gross value (including taxes) of the booking total (1,00 EUR = 100) [(sum of the remaining articlepricegross) + shippingpricegross - rebategross]
currency	+	string	A..3	3-digit currency code of the booking (e.g. “EUR”): ISO4217
reference	+	string	AN..40	Unique booking ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|)*

Article Data Node (List of all booking articles)

All information relating to the purchased products are collected in the article_data node. Every unique article is represented by an individual XML tag. When dealing with a cancellation where the customer must still pay a percentage of the original booking price, the article ID “BP_CANCELLATION_FEE” must be used.

<article_data>
    <article 
        articleid="BP_CANCELLATION_FEE" 
        articlequantity="1" 
        articletype="1"
        articlename="LH188" 
        articleprice="12605" 
        articlepricegross="15000" />
    </article_data>

editCartContentRequest.getCart().createAndAddArticle()
    .setId("BP_CANCELLATION_FEE")
    .setQuantity(1)
    .setType(ArticleType.FLIGHT)
    .setName("cancellation fee")
    .setPriceNet(12605)
    .setPriceGross(15000);

Attribute	Required	Data Type	Values	Info
articleid	+	string	AN..20	Unique article ID
articlename	+	string	AN..50	Article name
articletype	+	non-negative int	N..1	Item classification 0: Miscellaneous 1: Flight 2: Package including flight 3: Combination of items including flight 4: Combination of items without a flight 5: Hotel 6: Travel Insurance 7: Auto Rental
articlequantity	+	positive int	N..7	Article quantity
articlepricenet	+	int	N..7	Article net price (smallest currency unit; 1,00 EUR = 100)
articlepricegross	+	int	N..7	Article gross price (smallest currency unit; 1,00 EUR = 100)

Response

The server response to the editCartContent request delivers an error code (0=success) as well as a message should the request fail.

Data Node

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="EDIT_CART_CONTENT"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage="">
</data>

System.out.println(editCartContentResponse.getErrorCode());
System.out.println(editCartContentResponse.getMerchantMessage());
System.out.println(editCartContentResponse.getDeveloperMessage());
System.out.println(editCartContentResponse.getCustomerMessage());

Attribute	Required	Data Type	Values	Info
responsetype	+	string	EDIT_CART_CONTENT	Identifies for which request type the response is
errorcode	+	non-negative int	N..3	Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list
merchantmessage	+	string		Detailed error message to be displayed to the merchant only
customermessage	+	string		Detailed error message to be displayed to the customer
developermessage	+	string		Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD.

Invoice Numbers Node

This node is returned if BillPay sends the invoice to customers for the merchants.

<assigned_invoice_number>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="ZYLOGT#1" />
</assigned_invoice_number>

InvoiceNumber invoiceNumber = requestResonse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());

Attribute	Required	Data Type	Values	Info
invoice_number	+			Child node of the assigned_invoice_number node
↳invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
↳billpayinvoicenumber	+	string	AN..40	Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|\|#\|:\|.)*

Instalment Details Node (only for PayLater/Ratenkauf)

In this node, BillPay returns the updated information related to the instalment plan.

<instalment_details>
    <instl_plan numinst="6">
        <calc>
            <duration_in_months>
                6
            </duration_in_months>
            <fee_percent>
                6.00
            </fee_percent>
            <fee_total>
                2520
            </fee_total>
            <total_pymt>
                45520
            </total_pymt>
            <eff_anual>
                24.21
            </eff_anual>
            <nominal>
                20.57
            </nominal>
        </calc>
        <instl_list>
            <instl date="20160531" type="immediate">
                3520
            </instl>
            <instl date="20160630" type="first">
                7000
            </instl>
            <instl date="20160731" type="date">
                7000
            </instl>
            <instl date="20160831" type="date">
                7000
            </instl>
            <instl date="20160930" type="date">
                7000
            </instl>
            <instl date="20161031" type="date">
                7000
            </instl>
            <instl date="20161130" type="date">
                7000
            </instl>
        </instl_list>
    </instl_plan>
</instalment_details>

InstalmentPlan instalmentPlan = requestResonse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());

InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());

Attribute	Required	Data Type	Values	Info
instl_plan	+			Parent node - this node only appears for paymenttype=“7” (PayLater)
numinst	+	positive int	N	Number of instalments
calc	+			Child node of the instl_plan node
↳duration_in_months	+	int	N	Duration of the payment plan in months
↳fee_percent	+	decimal		PayLater fee (%) between 0.00 and 100.00
↳fee_total	+	non-negative int	N	Total PayLater fees
↳total_pymt	+	positive int	N	Total amount of the PayLater booking (including the fees)
↳eff_anual	+	decimal		Annual effective interest rate (%) between 0.00 and 100.00
↳nominal	+	decimal		Annual nominal interest rate (%) between 0.00 and 100.00
instl_list	+ (node)			Child node of the instl_plan node.
↳instl	+ (node)			Child node of the instl_list node.
↳date	+	DATE	YYYYMMDD	Date of the instalment
↳type	+	string	AN	Type of Instalment („immediate“, „first“, „date“, „fee“)

Get Billpay Bank Data

In the case of bookings with invoice as the payment method (paymenttype=“8”), the getBillPayBankData request will return the unique bank account information for the specified booking. The response contains all information needed for the customer to initiate their bank transfer. The response also contains the due date for the payment.

Request

Data Node

<data 
    requesttype="GET_BILLPAY_BANK_DATA" 
    apiversion="2.0.0">
    <!-- Request Data -->
</data>

Attribute	Data Type	Values	Info
requesttype	string	GET_BILLPAY_BANK_DATA	Type of request
apiversion	string	2.0.0	BillPay API Version

Default Params Node (Merchant Credentials)

The merchant API credentials are generated and provided by BillPay.

<default_params
        mid="1234"
        pid="9999"
        passwordhash="25d55ad283aa400af464c76d713c07ad" />

getBillPayBankDataRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")

Attribute	Required	Data Type	Info
mid	+	positive int	Merchant ID
pid	+	positive int	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal.

Order Params Node

 <order_params reference="ZYLOGT" />

getBillPayBankDataRequest.setReference("ZYLOGT");

Attribute	Required	Data Type	Values	Info
reference	+	string	AN..40	Unique booking ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|)*

Response

The XML service response for this request contains all the relevant information for the customer to pay their open debt.

Data Node (Result of the identity and credit check)

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="GET_BILLPAY_BANK_DATA"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage="">
    <!-- additional response specific data -->
</data>

System.out.println(getBillPayBankDataResponse.getErrorCode());
System.out.println(getBillPayBankDataResponse.getMerchantMessage());
System.out.println(getBillPayBankDataResponse.getDeveloperMessage());
System.out.println(getBillPayBankDataResponse.getCustomerMessage());

Attribute	Required	Data Type	Values	Info
responsetype	+	string	GET_BILLPAY_BANK_DATA	Identifies for which request type the response is
errorcode	+	non-negative int	N..3	Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list
merchantmessage	+	string		Detailed error message to be displayed to the merchant only
customermessage	+	string		Detailed error message to be displayed to the customer
developermessage	+	string		Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD.

Bank Account Node (only for invoice - paymenttype=“8”)

<bank_account
        accountholder="BillPay GmbH"
        accountnumber="DE07312312312312312"
        bankcode="BELADEBEXXX"
        bankname="Sparkasse Berlin"
        firstduedate="20170707"
        invoicereference="BPZYLOGT/9999" />

System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getBankCode());
System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getBankName());
System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getInvoiceReference());

Attribute	Required	Data Type	Values	Info
accountholder	+	string	AN..255	Account holder
accountnumber	+	string	AN..40	BillPay IBAN
bankcode	+	string	AN..16	BillPay BIC
bankname	+	string	AN..255	Name of the BillPay bank
firstduedate	+	string	N..8	Payment due date in the format: YYYYMMDD
invoicereference	+	string	AN..255	Transaction purpose

Invoice List Node

This node returns the invoice number and invoice ID in the BillPay system.

<invoice_list>
    <invoice
        duedate="20170324"
        invoiceid="1234567" />
</invoice_list>

DueDate dueDate = getBillPayBankDataResponse.getDueDates().get(0);

System.out.println(dueDate.getDuedate());
System.out.println(dueDate.getInvoiceid());

Attribute	Required	Data Type	Values	Info
invoice	+			Child node of the invoice_list node
↳duedate	+	string	N..8	Payment due date in the format: YYYYMMDD
↳invoiceid	-	string	AN..40	Unique invoice number in our system. Regex: ([A-Z]\|[a-z]\|[0-9]\|-\|_\|#\|:\|.)*

Customer Documents

Another vital component of the integration of BillPay payment methods, is the inclusion of the payment relevant information in the booking confirmation emails and invoices that are sent to your customers. This ensures a positive and seamless customer experience from purchase to payment. The following table outlines the required texts.

Sample Invoices

Invoice	Direct Debit
Instalments

Invoice Texts

Payment	German	English
Invoice	Vielen Dank, dass Sie sich für die BillPay Rechnung entschieden haben. Bitte überweisen Sie den Rechnungsbetrag innerhalb der Zahlungsfrist unter Angabe des Verwendungszwecks $$ Verwendungszweck $$ auf folgendes Konto: Kontoinhaber: $$ Kontoinhaber $$ IBAN: $$ IBAN $$ BIC: $$ BIC $$ Bank: $$ Geldinstitut $$ Fälligkeitsdatum: $$ Fälligkeitsdatum $$ Verwendungszweck: $$ Verwendungszweck $$ Bitte beachten Sie, dass Ihre Rechnung nur dann beglichen ist, wenn Ihre Zahlung auf das oben genannte Konto erfolgt.	Thank you for choosing invoice with BillPay as your payment method. Please transfer the total amount due prior to the expiration of the payment due date using the reference $$ reference $$ to the following account: Account holder: $$ account holder $$ Bank: $$ financial institution $$ IBAN: $$ IBAN $$ BIC: $$ BIC $$ Due date: $$ due date $$ Reference: $$ reference $$ Please note, the invoice is only considered paid in full, when the total amount due is transferred to the above bank account.
Direct Debit	Der fällige Gesamtbetrag wird in den nächsten Tagen von dem bei der Bestellung angegebenen Konto durch die BillPay GmbH abgebucht.	In the coming days, the total amount due will be debited from the account you submitted with your booking by the BillPay GmbH.
Instalments	Sie haben sich für die Zahlungsweise PayLater entschieden. Bitte beachten Sie, dass zusätzlich zu dem auf dieser Rechnung genannten Rechnungsbetrag weitere Kosten im Zusammenhang mit dem Teilzahlungsgeschäft entstehen. Diese Kosten wurden Ihnen vor Abschluss der Bestellung und auf der Bestellbestätigungsseite angezeigt. Die vollständige Berechnung der zu leistenden Beträge im Zusammenhang mit dem Teilzahlungsgeschäft, sowie sämtliche dazugehörige Informationen werden Sie direkt per E-Mail von der BillPay GmbH erhalten.	You have chosen to pay for your booking with a BillPay instalment plan. Please note that in addition to the total amount mentioned on this invoice, additional costs are incurred in connection with the instalment plan. These costs were displayed to you before the booking was completed and on the booking confirmation page. The full calculation of the amounts to be paid in connection with the instalment plan, as well as all related information, will be sent to you via e-mail by the BillPay GmbH.

Sample Requests

Preauth: Invoice

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="45" manualcapture="0" paymenttype="8" apiversion="2.0.0" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
    <shipping_details usebillingaddress="1" />
    <total shippingname="none" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="40204" orderamountgross="43230" currency="EUR" reference="ZYLOGT" merchantinvoicenumber="1234567" />
    <article_data>
        <article articleid="220-2365851307" articlequantity="1" articletype="1" articlename="LH188" articlepricenet="20567" articlepricegross="22115">
            <flight_information departingfrom="TXL" departingon="20170818" arrivingat="FRA"  arrivingon="20170818" bookingclass="bc" routetype="ow" tickettype="fl" />
        </article> 
        <article articleid="220-2365851307" articlequantity="1" articletype="1" articlename="LH188" articlepricenet="20567" articlepricegross="22115">
            <flight_information departingfrom="TXL" departingon="20170820" arrivingat="FRA"  arrivingon="20170820" bookingclass="bc" routetype="ow" tickettype="fl" />
        </article>    
    </article_data>
    <trip_data historicaltripcount="1" historicaltripamount="80000" historicaltripcurrency="EUR">
        <traveler_list groupsize="2">
            <traveler salutation="Herr" firstname="Thomas" lastname="Testkunde" dateofbirth="19741012">
                <flight_information>
                        <frequent_flyer membership="1" program="1" membershipid="12345" />
                </flight_information>
            </traveler> 
           <traveler salutation="Frau" firstname="Thomassina" lastname="Testkunde" dateofbirth="19720210">
                <flight_information>
                        <frequent_flyer membership="0" program="0" membershipid="0" />
                </flight_information>
            </traveler>
        </traveler_list>
    </trip_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

private void preauthorizeInvoiceExample() throws ParseException {
    //build the request
    PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
    preauthorizeRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session ID");

    preauthorizeRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    preauthorizeRequest
        .setTermsAndConditionAccepted(true)
        .setManualCapture(false)
        .setOriginOfSale(OriginOfSale.ONLINE_SHOP);

    preauthorizeRequest.getPaymentDetails()
        .setPaymentType(PaymentType.INVOICE_COLLATERAL_PROMISE);

    preauthorizeRequest.getCustomer()
        .setId("123456")
        .setCustomerType(CustomerType.EXISTING_CUSTOMER)
        .setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setEmail("anymail@example.org")
        .setIpAddress("80.111.120.1")
        .setLanguageIso2("de")
        .getBillingAddress()
            .setSalutation("Herr")
            .setFirstName("Thomas")
            .setLastName("Testkunde")
            .setStreet("Zinnowitzer Straße")
            .setStreetNumber("1")
            .setZipCode("10115")
            .setCity("Berlin")
            .setCountryIso3("DEU")
            .setPhone("03012345678");

    preauthorizeRequest.getCustomer().createShippingAddress()
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setStreet("Zinnowitzer Straße")
        .setStreetNumber("1")
        .setZipCode("10115")
        .setCity("Berlin")
        .setCountryIso3("DEU")
        .setPhone("03012345678");

    preauthorizeRequest.getShipping()
        .setDaysTillShipping(45)
        .setName("none")
        .setPriceNet(0)
        .setPriceGross(0);

    preauthorizeRequest.getCart()
        .setOrderAmountNet(23277)
        .setOrderAmountGross(27700)
        .setCurrencyIso3("EUR")
        .setReference("ZYLOGJ")
        .createAndAddRebate()
            .setRebateNet(840)
            .setRebateGross(1000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("220-2365851307")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH188")
        .setPriceNet(10924)
        .setPriceGross(13000)
        .createFlight()
            .setDepartingFromAirport("TXL")
            .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/14"))
            .setArrivingAtAirport("MUC")
            .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/14"))
            .setBookingClass(BookingClass.BUSINESS_CLASS)
            .setRouteType(RouteType.ONE_WAY)
            .setTicketType(TicketType.NO_REBOOKING_FEE);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("220-2365851308")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH376")
        .setPriceNet(13193)
        .setPriceGross(15700)
        .createFlight()
            .setDepartingFromAirport("MUC")
            .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/15"))
            .setArrivingAtAirport("DOH")
            .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/15"))
            .setBookingClass(BookingClass.BUSINESS_CLASS)
            .setRouteType(RouteType.ONE_WAY)
            .setTicketType(TicketType.NO_REBOOKING_FEE);

    TripData tripData = preauthorizeRequest.createTripData();
    tripData.setGroupSize(2)
        .setHistoricalTripCount(1)
        .setHistoricalTripAmount(80000)
        .setHistoricaltripCurrency("EUR");

    tripData.createAndAddTraveler()
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setMembership(1)
        .setProgram(1)
        .setMembershipId("12345");

    tripData.createAndAddTraveler()
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setSalutation("Frau")
        .setFirstName("Thomassina")
        .setLastName("Testkunde")
        .setMembership(0)
        .setProgram(0)
        .setMembershipId("0");

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse preauthorizeResponse = preauthorizeRequest.send();

    //getting data out of the response

    if (preauthorizeResponse.hasError()) {
        System.out.println(preauthorizeResponse.getErrorCode());
        System.out.println(preauthorizeResponse.getMerchantMessage());
        System.out.println(preauthorizeResponse.getDeveloperMessage());
        System.out.println(preauthorizeResponse.getCustomerMessage());
    } else {
        System.out.println(preauthorizeResponse.getTransactionId());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getStreet());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getStreetNumber());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getZipCode());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getCity());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getCountry());

        System.out.println(preauthorizeResponse.getInvoiceBankAccount().isActivationPerformed());
        System.out.println(preauthorizeResponse.getInvoiceBankAccount().getAccountHolder());
        System.out.println(preauthorizeResponse.getInvoiceBankAccount().getAccountNumber());
        System.out.println(preauthorizeResponse.getInvoiceBankAccount().getBankCode());
        System.out.println(preauthorizeResponse.getInvoiceBankAccount().getBankName());
        System.out.println(preauthorizeResponse.getInvoiceBankAccount().getInvoiceDueDate());
        System.out.println(preauthorizeResponse.getInvoiceBankAccount().getInvoiceReference());

        // the following are only returned if you are implementing virtual credit card solution
        try {
            System.out.println(preauthorizeResponse.getCreditCard().getAccountHolder());
            System.out.println(preauthorizeResponse.getCreditCard().getCardNumber());
            System.out.println(preauthorizeResponse.getCreditCard().getSecurityCode());
            System.out.println(preauthorizeResponse.getCreditCard().getExpirationDate());
            System.out.println(preauthorizeResponse.getCreditCard().getActivationDate());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

<?php
use BillPay\Core\Requests\PreauthorizeFactory;
use BillPay\Core\Commons\Constants;

$preauthorizeRequest = PreauthorizeFactory::create();

$preauthorizeRequest
    ->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password')
    ->setSessionId('clear text session ID');

$preauthorizeRequest->getEnvironment()->setEnvTest();

$preauthorizeRequest
    ->disableManualCapture()
    ->setOriginOfSaleOnline()
    ->setReference('ZYLOGJ');

$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE_COLLATERAL)
    ->acceptTermsOfUse();

$preauthorizeRequest->getCustomer()
    ->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1980-10-14')
    ->setEmail('anymail@example.org')
    ->setIpAddress('80.111.120.1')
    ->setLanguageIso2('de');

// when no shipping address is set we reuse the billing address (see /data/shipping_details/@usebillingaddress)
$preauthorizeRequest->getCustomer()->getBillingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Zinnowitzer Straße')
    ->setStreetNumber('1')
    ->setZipCode('10115')
    ->setCity('Berlin')
    ->setCountryIso3('DEU')
    ->setPhone('03012345678');

$preauthorizeRequest->getShipping()
    ->setExpectedDaysTillShipping(45)
    ->setName('none')
    ->setPriceGross(0)
    ->setPriceNet(0);

$preauthorizeRequest->getCart()
    ->setOrderAmountNet(23277)
    ->setOrderAmountGross(27700)
    ->setCurrencyIso3('EUR');

$preauthorizeRequest->getCart()->createAndAddRebate()
    ->setPriceNet(840)
    ->setPriceGross(1000);

$preauthorizeRequest->getCart()->createAndAddArticle()
    ->setId('220-2365851307')
    ->setQuantity(1)
    ->setTypeFlight()
    ->setName('LH188')
    ->setPriceNet(20567)
    ->setPriceGross(22115)
    ->getFlight()
    ->setDepartingFromAirport('TXL')
    ->setDepartingOn('2030-10-14')
    ->setArrivingAtAirport('FRA')
    ->setArrivingOn('2030-10-14')
    ->setIsBusinessClass()
    ->setIsOneWay()
    ->setIsFreeRebooking();

$preauthorizeRequest->getCart()->createAndAddArticle()
    ->setId('220-2365851307')
    ->setQuantity(1)
    ->setTypeFlight()
    ->setName('LH188')
    ->setPriceNet(20567)
    ->setPriceGross(22115)
    ->getFlight()
    ->setDepartingFromAirport('TXL')
    ->setDepartingOn('2030-10-14')
    ->setArrivingAtAirport('FRA')
    ->setArrivingOn('2030-10-14')
    ->setIsBusinessClass()
    ->setIsOneWay()
    ->setIsFreeRebooking();

$tripData = $preauthorizeRequest->getTrip();

$tripData
    ->setHistoricalTripCount(1)
    ->setHistoricalTripAmount(80000)
    ->setHistoricalTripCurrency('EUR');

$tripData->createAndAddTraveler()
    ->setDateOfBirth('1980-10-14')
    ->setSalutation('mr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setIsFrequentFlyerMember() // 1
    ->setFrequentFylerProgramId(1)
    ->setFrequentFlyerMembershipId('12345');

$tripData->createAndAddTraveler()
    ->setDateOfBirth('1980-10-14')
    ->setSalutation('mrs')
    ->setFirstName('Thomassina')
    ->setLastName('Testkunde')
    ->setIsUnknownFrequentFlyerMember();

// sending the request to BillPay and retrieving the response
$preauthorizeResponse = $preauthorizeRequest->send();

// getting data out of the response
if ($preauthorizeResponse->isError()) {
    echo $preauthorizeResponse->getErrorCode();
    echo $preauthorizeResponse->getMerchantMessage();
    echo $preauthorizeResponse->getDeveloperMessage();
    echo $preauthorizeResponse->getCustomerMessage();

} else {
    echo $preauthorizeResponse->getTransactionId();

    echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
    echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
    echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
    echo $preauthorizeResponse->getNormalizedAddress()->getCity();
    echo $preauthorizeResponse->getNormalizedAddress()->getCountry();

    // the invoice bank account is only returned if you do not use the manual capture option
    if ($preauthorizeResponse->getInvoiceBankAccount() !== null) {
        echo $preauthorizeResponse->getInvoiceBankAccount()->isActivationPerformed();
        echo $preauthorizeResponse->getInvoiceBankAccount()->getAccountHolder();
        echo $preauthorizeResponse->getInvoiceBankAccount()->getAccountNumber();
        echo $preauthorizeResponse->getInvoiceBankAccount()->getBankCode();
        echo $preauthorizeResponse->getInvoiceBankAccount()->getBankName();
        echo $preauthorizeResponse->getInvoiceBankAccount()->getInvoiceDueDateString();
        echo $preauthorizeResponse->getInvoiceBankAccount()->getInvoiceReference();
    }

    // the following are only returned if you are implementing virtual credit card solution
    if ($preauthorizeResponse->getCreditCard() !== null) {
        echo $preauthorizeResponse->getCreditCard()->getAccountHolder();
        echo $preauthorizeResponse->getCreditCard()->getCardNumber();
        echo $preauthorizeResponse->getCreditCard()->getSecurityCode();
        echo $preauthorizeResponse->getCreditCard()->getExpirationDate();
        echo $preauthorizeResponse->getCreditCard()->getActivationDate();
    }
}

Preauth: Direct Debit

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="45" manualcapture="0" paymenttype="9" apiversion="2.0.0" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
    <shipping_details usebillingaddress="1" />
    <total shippingname="none" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="40204" orderamountgross="43230" currency="EUR" reference="ZYLOGT" merchantinvoicenumber="1234567" />
    <article_data>
        <article articleid="220-2365851307" articlequantity="1" articletype="1" articlename="LH188" articlepricenet="20567" articlepricegross="22115">
            <flight_information departingfrom="TXL" departingon="20170818" arrivingat="FRA"  arrivingon="20170818" bookingclass="bc" routetype="ow" tickettype="fl" />
        </article> 
        <article articleid="220-2365851307" articlequantity="1" articletype="1" articlename="LH188" articlepricenet="20567" articlepricegross="22115">
            <flight_information departingfrom="TXL" departingon="20170820" arrivingat="FRA"  arrivingon="20170820" bookingclass="bc" routetype="ow" tickettype="fl" />
        </article>    
    </article_data>
    <trip_data historicaltripcount="1" historicaltripamount="80000" historicaltripcurrency="EUR">
        <traveler_list groupsize="2">
            <traveler salutation="Herr" firstname="Thomas" lastname="Testkunde" dateofbirth="19741012">
                <flight_information>
                        <frequent_flyer membership="1" program="1" membershipid="12345" />
                </flight_information>
            </traveler> 
           <traveler salutation="Frau" firstname="Thomassina" lastname="Testkunde" dateofbirth="19720210">
                <flight_information>
                        <frequent_flyer membership="0" program="0" membershipid="0" />
                </flight_information>
            </traveler>
        </traveler_list>
    </trip_data>
    <bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

private void preauthorizeDirectDebitExample() throws ParseException {
    //build the request

    PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
    preauthorizeRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session ID");

    preauthorizeRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    preauthorizeRequest
        .setTermsAndConditionAccepted(true)
        .setManualCapture(false)
        .setOriginOfSale(OriginOfSale.ONLINE_SHOP);

    preauthorizeRequest.getPaymentDetails()
        .setPaymentType(PaymentType.DIRECT_DEBIT_COLLATERAL_PROMISE)
        .createBankAccount()
        .setAccountHolder("Thomas Testkunde")
        .setAccountNumber("DE96100500003521863462")
        .setSortCode("BELADEBEXXX");

    preauthorizeRequest.getCustomer()
        .setId("123456")
        .setCustomerType(CustomerType.EXISTING_CUSTOMER)
        .setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setEmail("anymail@example.org")
        .setIpAddress("80.111.120.1")
        .setLanguageIso2("de")
        .getBillingAddress()
            .setSalutation("Herr")
            .setFirstName("Thomas")
            .setLastName("Testkunde")
            .setStreet("Zinnowitzer Straße")
            .setStreetNumber("1")
            .setZipCode("10116")
            .setCity("Berlin")
            .setCountryIso3("DEU")
            .setPhone("03012345678");

    preauthorizeRequest.getCustomer().createShippingAddress()
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setStreet("Zinnowitzer Straße")
        .setStreetNumber("1")
        .setZipCode("10115")
        .setCity("Berlin")
        .setCountryIso3("DEU")
        .setPhone("03012345678");

    preauthorizeRequest.getShipping()
        .setDaysTillShipping(45)
        .setName("none")
        .setPriceNet(0)
        .setPriceGross(0);

    preauthorizeRequest.getCart()
        .setOrderAmountNet(23277)
        .setOrderAmountGross(27700)
        .setCurrencyIso3("EUR")
        .setReference("ZYLOGLZ")
        .createAndAddRebate()
            .setRebateNet(840)
            .setRebateGross(1000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("220-2365851307")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH188")
        .setPriceNet(10924)
        .setPriceGross(13000)
        .createFlight()
            .setDepartingFromAirport("TXL")
            .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/14"))
            .setArrivingAtAirport("MUC")
            .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/14"))
            .setBookingClass(BookingClass.BUSINESS_CLASS)
            .setRouteType(RouteType.ONE_WAY)
            .setTicketType(TicketType.NO_REBOOKING_FEE);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("220-2365851308")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH376")
        .setPriceNet(13193)
        .setPriceGross(15700)
        .createFlight()
            .setDepartingFromAirport("MUC")
            .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/15"))
            .setArrivingAtAirport("DOH")
            .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/15"))
            .setBookingClass(BookingClass.BUSINESS_CLASS)
            .setRouteType(RouteType.ONE_WAY)
            .setTicketType(TicketType.NO_REBOOKING_FEE);

    TripData tripData = preauthorizeRequest.createTripData();
    tripData.setGroupSize(2)
        .setHistoricalTripCount(1)
        .setHistoricalTripAmount(80000)
        .setHistoricaltripCurrency("EUR");

    tripData.createAndAddTraveler()
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setMembership(1)
        .setProgram(1)
        .setMembershipId("12345");

    tripData.createAndAddTraveler()
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setSalutation("Frau")
        .setFirstName("Thomassina")
        .setLastName("Testkunde")
        .setMembership(0)
        .setProgram(0)
        .setMembershipId("0");

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse preauthorizeResponse = preauthorizeRequest.send();

    //getting data out of the response

    if (preauthorizeResponse.hasError()) {
        System.out.println(preauthorizeResponse.getErrorCode());
        System.out.println(preauthorizeResponse.getMerchantMessage());
        System.out.println(preauthorizeResponse.getDeveloperMessage());
        System.out.println(preauthorizeResponse.getCustomerMessage());
    } else {
        System.out.println(preauthorizeResponse.getTransactionId());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getStreet());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getStreetNumber());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getZipCode());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getCity());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getCountry());

        // The following is only returned if you are implementing virtual credit card solution
        try {
            System.out.println(preauthorizeResponse.getCreditCard().getAccountHolder());
            System.out.println(preauthorizeResponse.getCreditCard().getCardNumber());
            System.out.println(preauthorizeResponse.getCreditCard().getSecurityCode());
            System.out.println(preauthorizeResponse.getCreditCard().getExpirationDate());
            System.out.println(preauthorizeResponse.getCreditCard().getActivationDate());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

Preauth: PayLater

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="45" manualcapture="0" paymenttype="7" apiversion="2.0.0" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
    <shipping_details usebillingaddress="1" />
    <total shippingname="none" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="40204" orderamountgross="43230" currency="EUR" reference="ZYLOGT" merchantinvoicenumber="1234567" />
    <article_data>
        <article articleid="220-2365851307" articlequantity="1" articletype="1" articlename="LH188" articlepricenet="20567" articlepricegross="22115">
            <flight_information departingfrom="TXL" departingon="20170818" arrivingat="FRA"  arrivingon="20170818" bookingclass="bc" routetype="ow" tickettype="fl" />
        </article> 
        <article articleid="220-2365851307" articlequantity="1" articletype="1" articlename="LH188" articlepricenet="20567" articlepricegross="22115">
            <flight_information departingfrom="TXL" departingon="20170820" arrivingat="FRA"  arrivingon="20170820" bookingclass="bc" routetype="ow" tickettype="fl" />
        </article>    
    </article_data>
    <trip_data historicaltripcount="1" historicaltripamount="80000" historicaltripcurrency="EUR">
        <traveler_list groupsize="2">
            <traveler salutation="Herr" firstname="Thomas" lastname="Testkunde" dateofbirth="19741012">
                <flight_information>
                        <frequent_flyer membership="1" program="1" membershipid="12345" />
                </flight_information>
            </traveler> 
           <traveler salutation="Frau" firstname="Thomassina" lastname="Testkunde" dateofbirth="19720210">
                <flight_information>
                        <frequent_flyer membership="0" program="0" membershipid="0" />
                </flight_information>
            </traveler>
        </traveler_list>
    </trip_data>    
    <rate_request ratecount="6" terminmonths="6" totalamountgross="45823" />
    <bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

private void preauthorizePayLaterExample() throws ParseException {
    //build the request

    PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
    preauthorizeRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session ID");

    preauthorizeRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    preauthorizeRequest
        .setTermsAndConditionAccepted(true)
        .setManualCapture(false)
        .setOriginOfSale(OriginOfSale.ONLINE_SHOP);

    preauthorizeRequest.getPaymentDetails()
        .setPaymentType(PaymentType.PAYLATER_COLLATERAL_PROMISE)
        .createBankAccount()
        .setAccountHolder("Thomas Testkunde")
        .setAccountNumber("DE12500105170648489890")
        .setSortCode("BELADEBEXXX");

    preauthorizeRequest.getPaymentDetails().createInstalment()
        .setRateCount(12)
        .setTermInMonths(12)
        .setTotalAmountGross(31024);

    preauthorizeRequest.getCustomer()
        .setId("123456")
        .setCustomerType(CustomerType.EXISTING_CUSTOMER)
        .setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setEmail("anymail@example.org")
        .setIpAddress("80.111.120.1")
        .setLanguageIso2("de")
        .getBillingAddress()
            .setSalutation("Herr")
            .setFirstName("Thomas")
            .setLastName("Testkunde")
            .setStreet("Zinnowitzer Straße")
            .setStreetNumber("1")
            .setZipCode("10115")
            .setCity("Berlin")
            .setCountryIso3("DEU")
            .setPhone("03012345678");

    preauthorizeRequest.getCustomer().createShippingAddress()
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setStreet("Zinnowitzer Straße")
        .setStreetNumber("1")
        .setZipCode("10115")
        .setCity("Berlin")
        .setCountryIso3("DEU")
        .setPhone("03012345678");

    preauthorizeRequest.getShipping()
        .setDaysTillShipping(45)
        .setName("none")
        .setPriceNet(0)
        .setPriceGross(0);

    preauthorizeRequest.getCart()
        .setOrderAmountNet(23277)
        .setOrderAmountGross(27700)
        .setCurrencyIso3("EUR")
        .setReference("ZYLOGZ")
        .createAndAddRebate()
            .setRebateNet(840)
            .setRebateGross(1000);

    preauthorizeRequest.getCart()
        .createAndAddArticle()
        .setId("220-2365851307")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH188")
        .setPriceNet(10924)
        .setPriceGross(13000)
        .createFlight()
            .setDepartingFromAirport("TXL")
            .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/14"))
            .setArrivingAtAirport("MUC")
            .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/14"))
            .setBookingClass(BookingClass.BUSINESS_CLASS)
            .setRouteType(RouteType.ONE_WAY)
            .setTicketType(TicketType.NO_REBOOKING_FEE);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("220-2365851308")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH376")
        .setPriceNet(13193)
        .setPriceGross(15700)
        .createFlight()
            .setDepartingFromAirport("MUC")
            .setDepartingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/15"))
            .setArrivingAtAirport("DOH")
            .setArrivingOn(new SimpleDateFormat("yyyy/MM/dd").parse("2018/10/15"))
            .setBookingClass(BookingClass.BUSINESS_CLASS)
            .setRouteType(RouteType.ONE_WAY)
            .setTicketType(TicketType.NO_REBOOKING_FEE);

    TripData tripData = preauthorizeRequest.createTripData();
    tripData.setGroupSize(2)
        .setHistoricalTripCount(1)
        .setHistoricalTripAmount(80000)
        .setHistoricaltripCurrency("EUR");

    tripData.createAndAddTraveler()
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setSalutation("Herr")
        .setFirstName("Thomas")
        .setLastName("Testkunde")
        .setMembership(1)
        .setProgram(1)
        .setMembershipId("12345");

    tripData.createAndAddTraveler()
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
        .setSalutation("Frau")
        .setFirstName("Thomassina")
        .setLastName("Testkunde")
        .setMembership(0)
        .setProgram(0)
        .setMembershipId("0");

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse preauthorizeResponse = preauthorizeRequest.send();

    //getting data out of the response

    if (preauthorizeResponse.hasError()) {
        System.out.println(preauthorizeResponse.getErrorCode());
        System.out.println(preauthorizeResponse.getMerchantMessage());
        System.out.println(preauthorizeResponse.getDeveloperMessage());
        System.out.println(preauthorizeResponse.getCustomerMessage());
    } else {
        System.out.println(preauthorizeResponse.getTransactionId());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getStreet());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getStreetNumber());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getZipCode());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getCity());
        System.out.println(preauthorizeResponse.getCorrectedAddress().getCountry());

        // The following is only returned if instalments is the chose payment method
        InstalmentPlan instalmentPlan = preauthorizeResponse.getInstalmentDetails().getInstalmentPlan();
        System.out.println(instalmentPlan.getDurationInMonths());
        System.out.println(instalmentPlan.getFeePercent());
        System.out.println(instalmentPlan.getFeeTotal());
        System.out.println(instalmentPlan.getTotalPayment());
        System.out.println(instalmentPlan.getEffAnual());
        System.out.println(instalmentPlan.getNominal());

        InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
        System.out.println(instalmentItem.getAmount());
        System.out.println(instalmentItem.getDate());
        System.out.println(instalmentItem.getType());

        // The following is only returned if you are implementing virtual credit card solution
        try {
            System.out.println(preauthorizeResponse.getCreditCard().getAccountHolder());
            System.out.println(preauthorizeResponse.getCreditCard().getCardNumber());
            System.out.println(preauthorizeResponse.getCreditCard().getSecurityCode());
            System.out.println(preauthorizeResponse.getCreditCard().getExpirationDate());
            System.out.println(preauthorizeResponse.getCreditCard().getActivationDate());
        } catch (Exception e) {
            System.out.println(e);
        }
    }
}

Capture

<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="CAPTURE" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <capture_params transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337" orderamountgross="43230" currency="EUR" reference="ZYLOGT" merchantinvoicenumber="1234567" customerid="123456789" />
</data>

private void captureExample(){
    //building the request
    CaptureRequest captureRequest = new CaptureRequest();
    captureRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id")
        .setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
        .setMerchantInvoiceNumber("1234567");

    captureRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    captureRequest.getCustomer()
        .setCustomerId("123456789");

    captureRequest.getCart()
        .setReference("ZYLOGT")
        .setCurrencyIso3("EUR")
        .setOrderAmountGross(44230);

    CaptureResponse captureResponse = captureRequest.send();

    if (captureResponse.hasError()){
        System.out.println(captureResponse.getErrorCode());
        System.out.println(captureResponse.getMerchantMessage());
        System.out.println(captureResponse.getDeveloperMessage());
        System.out.println(captureResponse.getCustomerMessage());
    } else {
        System.out.println(captureResponse.getInvoiceBankAccount().isActivationPerformed());

        // The following is only returned for invoice as the payment method.
        System.out.println(captureResponse.getInvoiceBankAccount().isActivationPerformed());
        System.out.println(captureResponse.getInvoiceBankAccount().getAccountHolder());
        System.out.println(captureResponse.getInvoiceBankAccount().getAccountNumber());
        System.out.println(captureResponse.getInvoiceBankAccount().getBankCode());
        System.out.println(captureResponse.getInvoiceBankAccount().getBankName());
        System.out.println(captureResponse.getInvoiceBankAccount().getInvoiceDueDate());
        System.out.println(captureResponse.getInvoiceBankAccount().getInvoiceReference());

        // The following is only returned if instalments is the chose payment method
        InstalmentPlan instalmentPlan = captureResponse.getInstalmentDetails().getInstalmentPlan();
        System.out.println(instalmentPlan.getDurationInMonths());
        System.out.println(instalmentPlan.getFeePercent());
        System.out.println(instalmentPlan.getFeeTotal());
        System.out.println(instalmentPlan.getTotalPayment());
        System.out.println(instalmentPlan.getEffAnual());
        System.out.println(instalmentPlan.getNominal());

        InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
        System.out.println(instalmentItem.getAmount());
        System.out.println(instalmentItem.getDate());
        System.out.println(instalmentItem.getType());

        // The following is only returned if you are implementing virtual credit card solution
        System.out.println(captureResponse.getCreditCard().getAccountHolder());
        System.out.println(captureResponse.getCreditCard().getCardNumber());
        System.out.println(captureResponse.getCreditCard().getSecurityCode());
        System.out.println(captureResponse.getCreditCard().getExpirationDate());
        System.out.println(captureResponse.getCreditCard().getActivationDate());
    }
}

Cancel

Here the booking is completely cancelled and the customer must pay nothing.

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="CANCEL" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <cancel_params reference="ZYLOGT" orderamountgross="43230" currency="EUR" />
</data>

private void cancelExample(){
    //building the request
    CancelRequest cancelRequest = new CancelRequest();
    cancelRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id");

    cancelRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    cancelRequest.getCart()
        .setReference("ZYLOGT")
        .setCurrencyIso3("EUR")
        .setOrderAmountGross(44230);

    CancelResponse cancelResponse = cancelRequest.send();

    if (cancelResponse.hasError()) {
        System.out.println(cancelResponse.getErrorCode());
        System.out.println(cancelResponse.getMerchantMessage());
        System.out.println(cancelResponse.getDeveloperMessage());
        System.out.println(cancelResponse.getCustomerMessage());
    }
}

Edit Cart: booking change

Here the customer has changed their flight and there is a 50 € change booking fee + the cost of the new flight.

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="EDIT_CART_CONTENT" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <total shippingname="None" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="20460" orderamountgross="22000" currency="EUR" reference="ZYLOGT" />
    <article_data>
        <article articleid="220-2365851307" articlequantity="1" articlename="LH188" articlepricenet="16740" articlepricegross="18000" />
        <article articleid="2345" articlequantity="1" articlename="Change booking fee" articlepricenet="4650" articlepricegross="5000" />
    </article_data>
</data>

private void EditCartContentExample() {
    //building the request
    EditCartContentRequest editCartContentRequest = new EditCartContentRequest();
    editCartContentRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id");

    editCartContentRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    editCartContentRequest.getShipping()
        .setName("none")
        .setPriceNet(0)
        .setPriceGross(0);

    editCartContentRequest.getCart().createAndAddArticle()
        .setId("220-2365851307")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("LH188")
        .setPriceNet(20567)
        .setPriceGross(22115);

    editCartContentRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("Change booking fee")
        .setPriceNet(4200)
        .setPriceGross(5000);

    editCartContentRequest.getCart()
        .setOrderAmountNet(16270)
        .setOrderAmountGross(26115)
        .setCurrencyIso3("EUR")
        .setReference("ZYLOGT")
        .createAndAddRebate()
            .setRebateNet(930)
            .setRebateGross(1000);

     EditCartContentResponse editCartContentResponse = editCartContentRequest.send();   

     if (captureResponse.hasError()) {
        System.out.println(editCartContentResponse.getErrorCode());
        System.out.println(editCartContentResponse.getMerchantMessage());
        System.out.println(editCartContentResponse.getDeveloperMessage());
        System.out.println(editCartContentResponse.getCustomerMessage());
    } else {
        // The following is only returned if instalments is the chose payment method
        InstalmentPlan instalmentPlan = editCartContentResponse.getInstalmentDetails().getInstalmentPlan();
        System.out.println(instalmentPlan.getDurationInMonths());
        System.out.println(instalmentPlan.getFeePercent());
        System.out.println(instalmentPlan.getFeeTotal());
        System.out.println(instalmentPlan.getTotalPayment());
        System.out.println(instalmentPlan.getEffAnual());
        System.out.println(instalmentPlan.getNominal());

        InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
        System.out.println(instalmentItem.getAmount());
        System.out.println(instalmentItem.getDate());
        System.out.println(instalmentItem.getType());
    }
}

Edit Cart: cancellation fee

Here the customer has cancelled the flight and must pay a 150,00 € cancellation fee.

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="EDIT_CART_CONTENT" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <total shippingname="None" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="13020" orderamountgross="14000" currency="EUR" reference="ZYLOGT" />
    <article_data>
        <article articleid="BP_CANCELLATION_FEE" articlequantity="1" articlepricenet="13950" articlepricegross="15000" />
    </article_data>
</data>

private void EditCartContentExample() {
    //building the request
    EditCartContentRequest editCartContentRequest = new EditCartContentRequest();
    editCartContentRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id");

    editCartContentRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    editCartContentRequest.getShipping()
        .setName("none")
        .setPriceNet(0)
        .setPriceGross(0);

    editCartContentRequest.getCart().createAndAddArticle()
        .setId("BP_CANCELLATION_FEE")
        .setQuantity(1)
        .setType(ArticleType.FLIGHT)
        .setName("cancellation fee")
        .setPriceNet(12605)
        .setPriceGross(15000);

    editCartContentRequest.getCart()
        .setOrderAmountNet(11675)
        .setOrderAmountGross(14000)
        .setCurrencyIso3("EUR")
        .setReference("ZYLOGT")
        .createAndAddRebate()
            .setRebateNet(930)
            .setRebateGross(1000);

     EditCartContentResponse editCartContentResponse = editCartContentRequest.send();

     if(captureResponse.hasError()){
        System.out.println(editCartContentResponse.getErrorCode());
        System.out.println(editCartContentResponse.getMerchantMessage());
        System.out.println(editCartContentResponse.getDeveloperMessage());
        System.out.println(editCartContentResponse.getCustomerMessage());
    }else{
        // The following is only returned if instalments is the chose payment method
        InstalmentPlan instalmentPlan = editCartContentResponse.getInstalmentDetails().getInstalmentPlan();
        System.out.println(instalmentPlan.getDurationInMonths());
        System.out.println(instalmentPlan.getFeePercent());
        System.out.println(instalmentPlan.getFeeTotal());
        System.out.println(instalmentPlan.getTotalPayment());
        System.out.println(instalmentPlan.getEffAnual());
        System.out.println(instalmentPlan.getNominal());

        InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
        System.out.println(instalmentItem.getAmount());
        System.out.println(instalmentItem.getDate());
        System.out.println(instalmentItem.getType());
    }
}

Get Bank Data

<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="GET_BILLPAY_BANK_DATA" apiversion="2.0.0">
    <default_params
            mid="1234"
            pid="9999"
            passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <order_params reference="ZYLOGT" />
</data>

private void getBankDataExample() {
    //building the request
    GetBillPayBankDataRequest getBillPayBankDataRequest = new GetBillPayBankDataRequest();
    getBillPayBankDataRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id");

    getBillPayBankDataRequest.getEnvironment()
        .setEnv(Environment.Key.TEST);

    getBillPayBankDataRequest.setReference("ZYLOGT");

    GetBillPayBankDataResponse getBillPayBankDataResponse = getBillPayBankDataRequest.send();

     if (captureResponse.hasError()) {
        System.out.println(editCartContentResponse.getErrorCode());
        System.out.println(editCartContentResponse.getMerchantMessage());
        System.out.println(editCartContentResponse.getDeveloperMessage());
        System.out.println(editCartContentResponse.getCustomerMessage());
    } else {
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().isActivationPerformed());
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getAccountHolder());
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getAccountNumber());
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getBankCode());
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getBankName());
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getInvoiceDueDate());
        System.out.println(getBillPayBankDataResponse.getInvoiceBankAccount().getInvoiceReference());

        DueDate dueDate = getBillPayBankDataResponse.getDueDates().get(0);
        System.out.println(dueDate.getDuedate());
        System.out.println(dueDate.getInvoiceid());
    }
}

Addendum

Versioning

API Version	.NET Library Version	PHP Library Version	Java Library Version
2.0.0	>= 2.0.0	>= 2.0.0	>= 2.0.0

Salutations

Gender “female”:	Gender “male”:
frau	herr
fräulein	hr
fr	hr.
fr.	sir
miss	mr
ms	mr.
ms.	signor
mrs	sig
mrs.	sig.
signora	gentleman
sig.a	gentiluomo
sig.ra	padrone
donna	monsieur
la signora	m.
madame	m
mme
mademoiselle
mlle
mle

Frequent Flyer Programs

ID Number	Program Name
0	None
1	Other (not listed)
2	Miles & More
3	Topbonus
4	Etihad Guest
5	Flying Blue
6	Iberia Plus
7	S7 Priority
8	Aeroflot Bonus
9	EuroBonus
10	Flying Blue
11	MilleMiglia
12	WOW Club
13	LANPASS
14	Smiles
15	Aerolíneas Plus
16	LifeMiles
17	MileagePlus
18	SkyMiles
19	AAdvantage
20	Aeroplan
21	Altitude
22	Club Premier
23	Frequent Flyer
24	Executive Club
25	Executive Club
26	Avios Travel Programme
27	My Jet2 Travel Club
28	Vantage Club
29	Flying Club
30	Egyptair Plus
31	Egyptair Plus
32	Matmid Club
33	Miles & Smiles
34	Pegasus Plus
35	SunPoints
36	Phoenix Miles
37	Eastern Miles
38	The Marco Polo Club
39	ANA Mileage Club
40	JAL Mileage Bank
41	BIG
42	Royal Orchid Plus
43	Qantas Frequent Flyer
44	Velocity Frequent Flyer
45	Airpoints

API Error Codes

The Customer Message is what you must display to your customers on your website when an error code is returned. The Merchant Message is what you must log, so you can review the errors that are occuring in your implementation.

Error Code	Message Audience	Message
1	Customer	Error: An internal error occurred. Please try again later.
1	Merchant	Error: An internal error occurred. Please try again later.
2	Customer	Error: Please select another payment method or try again later. An internal error occurred.
2	Merchant	Error: The submitted Merchant ID is wrong.
3	Customer	Error: Please select another payment method or try again later. An internal error occurred.
3	Merchant	Error: The portal ID is wrong.
4	Merchant	Error: API authentication failure.
4	Customer	Error: Please select another payment method or try again later. An internal error occurred.
5	Customer	Error: Please confirm the Billpays Terms & Conditions before you use this payment method from Billpay.
5	Merchant	Error: Please confirm the Billpays Terms & Conditions before you use this payment method from Billpay.
7	Customer	Error: The mandatory parameter [parameter] was not submitted.
7	Merchant	Error: The mandatory parameter [parameter] was not submitted.
8	Customer	Error: Please select another payment method or try again later. An internal error occurred.
8	Merchant	Error: The value for the field [parameter] has the wrong data format.
9	Customer	Error: Please verify your input data. The first name of your billing address must consist of at least 2 letters.
9	Merchant	Error: Please verify your input data. The first name of your billing address must consist of at least 2 letters.
11	Customer	Error: Please verify your input data. The street of your billing address must consist of at least 2 letters.
11	Merchant	Error: Please verify your input data. The street of your billing address must consist of at least 2 letters.
12	Customer	Error: Please verify your input data. The street number of your billing address must consist of at least 1 digit.
12	Merchant	Error: Please verify your input data. The street number of your billing address must consist of at least 1 digit.
13	Customer	Error: Please verify your input data. The zip code of your billing address must consist of exactly [length] digits.
13	Merchant	Error: Please verify your input data. The zip code of your billing address must consist of exactly [length] digits.
14	Customer	Error: Please verify your input data. The city name of your billing address must consist of at least 2 letters.
14	Merchant	Error: Please verify your input data. The city name of your billing address must consist of at least 2 letters.
15	Customer	Error: Please verify your input data. The telephone number of your billing address is not correct.
15	Merchant	Error: Please verify your input data. The telephone number of your billing address is not correct.
16	Customer	Error: Please verify your input data. The mobile phone number of your billing address is not correct.
16	Merchant	Error: Please verify your input data. The mobile phone number of your billing address is not correct.
17	Customer	Error: Please verify your input data. Your email address is invalid.
17	Merchant	Error: Please verify your input data. Your email address is invalid.
18	Customer	Error: Please verify your input data. Your birthday must not be in the future.
18	Merchant	Error: Please verify your input data. Your birthday must not be in the future.
19	Customer	Error: Please select another payment method. You must be at least 18 years old in order to pay with this payment method from Billpay.
19	Merchant	Error: Please select another payment method. You must be at least 18 years old in order to pay with this payment method from Billpay.
21	Customer	Error: Please verify your input data. The last name of your shipping address must consist of at least 2 letters.
21	Merchant	Error: Please verify your input data. The last name of your shipping address must consist of at least 2 letters.
22	Customer	Error: Please verify your input data. The street of your shipping address must consist of at least 2 letters.
22	Merchant	Error: Please verify your input data. The street of your shipping address must consist of at least 2 letters.
23	Customer	Error: Please verify your input data. The street number of your shipping address must consist of at least 1 digit.
23	Merchant	Error: Please verify your input data. The street number of your shipping address must consist of at least 1 digit.
24	Customer	Error: Please verify your input data. The zip code of your shipping address must consist of exactly 5 digits.
24	Merchant	Error: Please verify your input data. The zip code of your shipping address must consist of exactly 5 digits.
25	Customer	Error: Please verify your input data. The city name of your shipping address must consist of at least 2 letters.
25	Merchant	Error: Please verify your input data. The city name of your shipping address must consist of at least 2 letters.
26	Customer	Error: Please verify your input data. The telephone number of your shipping address is not correct.
26	Merchant	Error: Please verify your input data. The telephone number of your shipping address is not correct.
27	Customer	Error: Please verify your input data. The mobile phone number of your shipping address is not correct.
27	Merchant	Error: Please verify your input data. The mobile phone number of your shipping address is not correct.
28	Customer	Error: You can only use this payment method from Billpay if billing and shipping country are located in Germany.
28	Merchant	Error: You can only use this payment method from Billpay if billing and shipping country are located in Germany.
29	Merchant	Please select another payment method. The IP address is assigned to a country that is blacklisted.
29	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
31	Customer	Error: Your billing and shipping addresses may not be a Packstation.
31	Merchant	Error: Your billing and shipping addresses may not be a Packstation.
32	Merchant	Please select another payment method. The request was rejected because of a failed identity or credit check.
32	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
33	Customer	Error: Please select another payment method or try again later. An internal error occurred.
33	Merchant	Error: The order amount does not match the transaction ID.
34	Merchant	Error: No transaction ID was submitted.
34	Customer	Error: Please select another payment method or try again later. An internal error occurred.
35	Customer	Error: An error occurred.
35	Merchant	Error: The submitted transaction ID is invalid.
36	Customer	Error: Please select a salutation.
36	Merchant	Error: Please verify your input data. The mandatory field [parameter] must be Mister or Misses.
37	Customer	Error: Please select another payment method or try again later. An internal error occurred.
37	Merchant	Error: Please verify your input data. The mandatory field [parameter] must contain a valid IP address.
38	Customer	Error: Please select another payment method or try again later. An internal error occurred.
38	Merchant	Error: The mandatory parameter [customerType] was not submitted or is invalid.
39	Customer	Error: The value for field [parameter] must be integer value.
39	Merchant	Error: The value for field [parameter] must be integer value.
41	Merchant	Error: There were too many requests sent from this IP address.
41	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
42	Merchant	Error: The customer has open debts.
42	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
43	Merchant	Error: The order limit at Billpay for this customer is reached.
43	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
44	Merchant	Error: The merchant has open debts against this customer.
44	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
45	Merchant	External identity or credit check failed.
45	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
46	Merchant	Error: If the billing address is used as shipping address, the shipping address must be empty [parameter].
46	Customer	Error: Please select another payment method or try again later. An internal error occurred.
47	Customer	Error: Please verify your input data. The street number must start with a digit [parameter].
47	Merchant	Error: Please verify your input data. The street number must start with a digit [parameter].
48	Customer	Error: An internal error occurred. Please try again later.
48	Merchant	Error: No articles were submitted for cancellation.
49	Customer	Error: The cart has been changed. Please start again the checkout process.
49	Merchant	Error: The order amount submitted for confirmation has changed in comparison to the amount submitted for preauthorization.
51	Customer	Error: The value for field [parameter] must be at least [minLength] characters long.
51	Merchant	Error: The value for field [parameter] must be at least [minLength] characters long.
52	Customer	Error: The value for field [parameter] must be not more than [maxLength] characters long.
52	Merchant	Error: The value for field [parameter] must be not more than [maxLength] characters long.
53	Customer	Error: Please select another payment method or try again later. An internal error occurred.
53	Merchant	Error: The submitted order data is invalid.
54	Customer	Error: The value for field [parameter] must be equal to one of the following values: [string]
54	Merchant	Error: The value for field [parameter] must be equal to one of the following values: [string]
55	Customer	Error: The quantity to be cancelled of one article is higher than the order quantity of this article.
55	Merchant	Error: The quantity to be cancelled of one article is higher than the order quantity of this article.
56	Customer	Error: Please select another payment method or try again later. An internal error occurred.
56	Merchant	Error: The submitted XML is invalid.
57	Customer	Error: Please select another payment method or try again later. An internal error occurred.
57	Merchant	Error: The order has already been captured.
58	Customer	Error: Please select another payment method or try again later. An internal error occurred.
58	Merchant	Error: The order amount submitted for cancellation has changed in comparison to the amount submitted for preauthorization.
59	Merchant	Error: Partial cancellation is not allowed.
59	Customer	Error: Please select another payment method or try again later. An internal error occurred.
61	Customer	Error: The manual activation of the order is not allowed.
61	Merchant	Error: The manual activation of the order is not allowed.
62	Customer	Error: The order amount submitted for manual activation has changed in comparison to the amount submitted for preauthorization.
62	Merchant	Error: The order amount submitted for manual activation has changed in comparison to the amount submitted for preauthorization.
63	Customer	Error: The total amount of partial cancellation must not exceed the total order value.
63	Merchant	Error: The total amount of partial cancellation must not exceed the total order value.
64	Customer	Error: When removing all articles from the order the reduction amount must not deviate from the order amount.
64	Merchant	Error: When removing all articles from the order the reduction amount must not deviate from the order amount.
65	Customer	Error: Please select another payment method or try again later. An internal error occurred.
65	Merchant	Error: The submitted value [parameter
66	Customer	Error: Orders with an amount of zero are not supported.
66	Merchant	Error: Orders with an amount of zero are not supported.
67	Customer	Error: Please verify your input data. The submitted sort code is invalid.
67	Merchant	Error: Please verify your input data. The submitted sort code is invalid.
68	Customer	Error: Please verify your input data. The submitted account number is invalid.
68	Merchant	Error: Please verify your input data. The submitted account number is invalid.
69	Customer	Error: Please verify your input data. The submitted bank account is invalid.
69	Merchant	Error: Please verify your input data. The submitted bank account is invalid.
71	Merchant	Authorization failure.
71	Customer	Error: An internal error occurred. Please try again later.
72	Customer	Error: The submitted value for field [parameter] must equal one of the following values: [list]
72	Merchant	Error: The submitted value for field [parameter] must equal one of the following values: [list]
73	Customer	Error: An internal error occurred. Please try again later.
73	Merchant	Error: Only positive article quantities are allowed for partial cancellation (Field [parameter]).
74	Customer	Error: An internal error occurred. Please try again later.
74	Merchant	Error: The consistency check for the values submitted for the order with Transaction Credit failed.
75	Customer	Error: An internal error occurred. Please try again later.
75	Merchant	Error: The activation delay must not exceed [baseValue] days.
76	Customer	Error: An internal error occurred. Please try again later.
76	Merchant	Error: The submitted number of instalments is not allowed.
77	Customer	Error: The value submitted for field [parameter] must be greater than [baseValue].
77	Merchant	Error: The value submitted for field [parameter] must be greater than [baseValue].
78	Customer	Error: An internal error occurred. Please try again later.
78	Merchant	Error: No article list was submitted or the article list is empty.
79	Customer	Error: Please select another payment method or try again later. An internal error occurred.
79	Merchant	Error: The submitted IP address originates from a local network.
81	Merchant	Error: For this shop the payment method [parameter] is not allowed.
81	Customer	Error: Please select another payment method or try again later. An internal error occurred.
82	Merchant	Error: Orders from business clients using payment method [parameter] are not enabled for this shop.
82	Customer	Error: Please select another payment method or try again later. An internal error occurred.
83	Customer	Error: The value for the field [parameter] must be greater than or equal [baseValue].
83	Merchant	Error: The value for the field [parameter] must be greater than or equal [baseValue].
84	Customer	Error: The value for the field [parameter] must be smaller than or equal [baseValue].
84	Merchant	Error: The value for the field [parameter] must be smaller than or equal [baseValue].
85	Customer	Error: There was no list with due dates submitted or the XML structure of the list is invalid.
85	Merchant	Error: There was no list with due dates submitted or the XML structure of the list is invalid.
86	Customer	Error: The date for the field [parameter] must be in the future.
86	Merchant	Error: The date for the field [parameter] must be in the future.
87	Customer	Error: Orders from country [address.country] are not allowed.
87	Merchant	Error: Orders from country [address.country] are not allowed.
88	Customer	Error: The currency [currency] is not supported.
88	Merchant	Error: The currency [currency] is not supported.
89	Customer	Error: Please select another payment method or try again later. An internal error occurred.
89	Merchant	Error: The portal is deactivated.
91	Customer	Error: For customers from country [parameter] the Billpay payment methods are not available.
91	Merchant	Error: For customers from country [parameter] the Billpay payment methods are not available.
92	Customer	Error: The order amount is less than the minimum amount for orders with this payment method.
92	Merchant	Error: The order amount is less than the minimum amount for orders with this payment method.
93	Customer	Error: The maximum amount for orders with this payment method has been exceeded.
93	Merchant	Error: The maximum amount for orders with this payment method has been exceeded.
94	Customer	Error: Please select another payment method or try again later. An internal error occurred.
94	Merchant	Error: The submitted currency has changed compared to the preauthorization request.
95	Customer	Error: The country [country] is not supported.
95	Merchant	Error: The country [country] is not supported.
96	Customer	Error: An internal error occurred.
96	Merchant	Error: Invalid order status for this operation.
97	Customer	Error: Please verify your input data. The selected legal form is invalid for country [country].
97	Merchant	Error: Please verify your input data. The selected legal form is invalid for country [country].
98	Customer	Error: Please specify a value for the field [parameter].
98	Merchant	Error: Please specify a value for the field [parameter].
99	Customer	Error: Your submission for field [parameter] contains illegal characters.
99	Merchant	Error: Your submission for field [parameter] contains illegal characters.
111	Customer	Error: Please try again later. An internal error occurred.
111	Merchant	Error: The customer data must not change when using the payment control option.
112	Merchant	Error: Invalid preauthorization. For the current portal payment control option is enabled.
112	Customer	Error: Please try again later. An internal error occurred.
113	Merchant	Error: The request was declined because of suspected fraud.
113	Customer	Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
114	Merchant	Error: Activation amount is incorrect
114	Customer	Error: An error has occurred
115	Customer	Error: An error has occurred
115	Merchant	Error: The total activation amount for the shipping fees exceeds the available amount for the shipping fee.
116	Customer	Error: An error has occurred
116	Merchant	Error: Negative order total
117	Merchant	Error: Activation is empty
117	Customer	Error: An error has occurred
118	Customer	Error: An error has occurred
118	Merchant	Error: No sub orders found
119	Customer	Error: An error has occurred
119	Merchant	Error: Item was already activated
121	Customer	Error: An error has occurred
121	Merchant	Error: Partial activation is not allowed
122	Customer	Error: An error has occurred
122	Merchant	Error: This operation is not permitted for this payment method.
123	Customer	Error: An error has occurred
123	Merchant	Error: Invoice number is not unique for this order
124	Customer	Error: An error has occurred
124	Merchant	Error: Reference should not contain hash (#) symbol
125	Customer	Error: An internal error occurred. Please try again later.
125	Merchant	Error: The order has not been captured.
126	Customer	Error: An internal error occurred. Please try again later.
126	Merchant	Error: Increasing the order amount is not allowed for the current status of the order.
127	Customer	Error: An internal error occurred. Please try again later.
127	Merchant	Error: The supplied number of rates is invalid.
128	Customer	Error: An internal error occurred. Please try again later.
128	Merchant	Error: Increasing the order amount is not allowed for the current status of the order.
129	Customer	Error: An internal error occurred. Please try again later.
129	Merchant	Error: The amount of the partial activation exceeds the total amount of the order.
131	Customer	Error: The order reference number was not found.
131	Merchant	Error: The order reference number was not found.
132	Customer	Error: Please verify your input data. The submitted IBAN is invalid.
132	Merchant	Error: Please verify your input data. The submitted IBAN is invalid.
133	Customer	Error: Please verify your input data. The submitted BIC is invalid.
133	Merchant	Error: Please verify your input data. The submitted BIC is invalid.
134	Customer	Error: Please select another payment method. The SEPA mandate for this bank account has been revoked.
134	Merchant	Error: The SEPA mandate for this account has been revoked by the customer.
135	Customer	Error: Please select another payment method or try again later. An internal error occurred.
135	Merchant	Error: Requests for this payment method configuration can only be processed in auto capture mode.
136	Customer	The BIC and IBAN country codes do not match.
136	Merchant	The BIC and IBAN country codes do not match.
137	Customer	Error: Please provide an account holder.
137	Merchant	Error: Please provide an account holder.
138	Customer	Error: The value for account holder contains invalid characters.
138	Merchant	Error: The value for account holder contains invalid characters.
139	Customer	Error: The request is already being processed. Please wait until the processing is completed.
139	Merchant	Error: The request is already being processed. Please wait until the processing is completed.
141	Customer	Error: An internal error occurred. Please try again later.
141	Merchant	Error: This request is invalid because for this customer a subsequent request was performed.
142	Customer	Error: Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction.
142	Merchant	Error: The parameter expecteddaystillshipping is less than the allowed minimum
143	Customer	Error: The shipping fees must not remain in the order if the rest of the order is cancelled.
143	Merchant	Error: The shipping fees must not remain in the order if the rest of the order is cancelled.
144	Customer	Error: Please try again later. An internal error occurred.
144	Merchant	Error: The cart provided for the order change is inconsistent (Total of all item prices + shipping costs - rebates must be equal to the total order amount).
145	Merchant	Error: At least one of the articles provided for an invoice does not exist for this order.
145	Customer	Error: Please try again later. An internal error occurred.
146	Customer	Error: Please try again later. An internal error occurred.
146	Merchant	Error: The invoice related information contained in the request is either invalid for this payment method or does not match the existing invoices.
147	Customer	Error: Please try again later. An internal error occurred.
147	Merchant	Error: The invoice related information contained in the request is invalid for instalment based payment methods.
148	Merchant	Error: At least one of the invoices contained in the request does not exist for this order.
148	Customer	Error: Please try again later. An internal error occurred.
149	Customer	Error: Please try again later. An internal error occurred.
149	Merchant	Error: The cart provided for the change of one of the invoices is inconsistent (Total of all item prices + shipping costs - rebates must be equal to the total order amount).
151	Customer	Error: Please try again later. An internal error occurred.
151	Merchant	Error: The invoiced quantity of an article exceeds the order quantity of this article.
152	Customer	Error: Merchants can not report customer payments for more than the current outstanding activated amount of the order.
152	Merchant	Error: Merchants can not report customer payments for more than the current outstanding activated amount of the order.
153	Customer	Error: Please try again later. An internal error occurred.
153	Merchant	Error: The validation of the XML request failed.

Settlement Files

Every merchant will receive access to a weekly settlement file via download link in the BillPay BackOffice using the dedicated “controlling” user credentials.

You will receive an e-mail notification as soon as the weekly settlement file is available. The settlement period runs from Monday to Sunday of the prior week. The files are available to be downloaded in the following formats:

Included are the individual orders accrued during the billing period as well as their amount and the fees incurred.

Index	Column	Format	Description
1	Transaction Type ID	N..2	0: transaction fee (minimum) 1: setup fee 2: monthly fee 3: transaction fee 4: cancellation fee 15: VAT recovery 7,00% 16: VAT recovery 19,00% 17: credit check costs 18: direct customer payment 19: Dunning fee coverage
2	Transaction Type	AN..50	Description of fee
3	Portal ID	N..6	BillPay portal ID
4	Merchant Reference Number	AN..40	The merchant’s order reference, submitted with the preauthorization
5	Merchant Customer Number	AN..40	The merchant’s customer ID
6	BillPay Customer Number	N..10	BillPay’s customer ID
7	Debt ID	N..10	BillPay’s debt ID
8	Debt Amount [3 character currency code (e.g. “EUR”)]	(-)Float(8:2)	The total amount to be paid out to the merchant
9	Disagio [%]	Float(1:4)	BillPay fee in percent
10	Transaction Fee [3 character currency code (e.g. “EUR”)]	(-)Float(8:2)	BillPay fee in EUR
11	Order Date	YYYMMDD	Order date
12	Activation Date	YYYYMMDD	Date of activation
13	Due Date	YYYYMMDD	The customer’s payment due date
14	Customer Country	A..3	The customer’s country (e.g. DEU) ISO3166 (alpha-3)

Additionally, the files can be downloaded via a https request, which lends itself to being built into an automated process. The link for the https request would be as follows:

https://admin.billpay.de/MerchantInvoiceDownload.action?mh=##########&cw=12&year=2017&format=csv&type=1

Get Variable Descriptions in the Above URL

Variable	Format	Info
mh	string	This is a shop/portal specific indentifying hash. BillPay will provide you with this value upon request.
cw	ISO 8601: WW	The calendar week of the settlement file
year	ISO 8601:YYYY	The year of the desired settlement file (YYYY format)
format	string (csv or pdf)	The format of the document (csv, pdf)
type	positive int	There are different settlement files depending upon the country or payment method. BillPay will provide you the file types you will need upon request.

Downloads

The preferred BillPay payment logos for display on your website and in your checkout, as well as all of our programming libraries can be downloaded here: https://www.billpay.de/en/shopintegration/downloads/

Version history

[2.2.0] - 2017-10-04

The version 2.2.0 is not fully backwards compatible to 2.1.0

Added

Request: getOrderDetails.xsd
Response: getOrderDetails.xsd
Request: prescore.xsd
- attribute expecteddaystillshipping

Changed

Request: shiftDueDate.xsd
- changed attribute newduedate from type date to the name shiftdatesby from the type integer in the range 1 to 90

[2.1.0] - 2017-06-19

The version 2.1.0 is not fully backwards compatible to 2.0.0

Changed

Request: preauthorize.xsd
Request: prescore.xsd
- allowed values from attribute historicaltripcurrency changed from char to enum
Response: invoiceCreated.xsd
- element name has been changed from “invoice_numbers” to “assigned_invoice_number”. Only the invoice_number node for the currently activated suborder is returned.

[2.0.0] - 2017-07-03

Added

Notificatons: asyncCapture.xsd
Request: cancel.xsd
Request: capture.xsd
Request: editCartContent.xsd
Request: getBillPayBankData.xsd
Request: invoiceCreated.xsd
Request: partialCancel.xsd
Request: preauthorize.xsd
Request: prescore.xsd
Request: reportCustomerPayment.xsd
Request: shiftDueDate.xsd
Request: updateOrder.xsd
Response: cancel.xsd
Response: capture.xsd
Response: editCartContent.xsd
Response: getBillPayBankData.xsd
Response: invoiceCreated.xsd
Response: partialCancel.xsd
Response: preauthorize.xsd
Response: prescore.xsd
Response: reportCustomerPayment.xsd
Response: shiftDueDate.xsd
Response: updateOrder.xsd

Should you have any questions relating to this manual and/or integrating BillPay payment methods, please feel free to contact us via support@billpay.de.

Integrating Travel Solutions

Getting Started

Front-end Integration

The JavaScript Widget

Configuration

Full Example

Legal Texts and Logos

XML API Overview

Web service URL

Generic Parameters

Placing a Booking

Process Overview

Preauthorize

Request

Response

Capture

Request

Response

Managing a Booking

Request Overview

Cancel

Request

Response

Edit Cart Content

Request

Response

Get Billpay Bank Data

Request

Response

Customer Documents

Sample Requests

Preauth: Invoice

Preauth: Direct Debit

Preauth: PayLater

Capture

Cancel

Edit Cart: booking change

Edit Cart: cancellation fee

Get Bank Data

Addendum

Versioning

Salutations

Frequent Flyer Programs

API Error Codes

Settlement Files

Downloads

Version history

[2.2.0] - 2017-10-04

Added

Changed

[2.1.0] - 2017-06-19

Changed

[2.0.0] - 2017-07-03

Added