BillPay Techdocs
Navbar
XML Java PHP

E-Commerce Solutions

Getting Started

This documentation covers integrating BillPay e-commerce payment solutions and the BillPay XML API with your shop and order management 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
prescore Placing an order Request / Response
preauthorize Placing an order Request / Response
capture Placing an order Request / Response
invoiceCreated Managing an order Request / Response
cancel Managing an order Request / Response
editCartContent Managing an order Request / Response
updateOrder Managing an order Request / Response
getBillPayBankData Managing an order Request / Response

Front-end Integration

The JavaScript Widget

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 your shop benefit from BillPay brand recognition and improved customer satisfaction.

For integration projects where the shop system is developed in-house or BillPay does not offer a plug-in, 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 shop 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
        },
        "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]"
            },
            "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": {
                "invoice": {
                    "customerGroup": "billpay[invoice_customer_group]",
                    "termsOfService": "billpay[invoice_toc]"
                },
                "directDebit": {
                    "customerGroup": "billpay[direct_debit_customer_group]",
                    "termsOfService": "billpay[direct_debit_toc]"
                },
                "transactionCredit": {
                    "customerGroup": "billpay[transaction_credit_customer_group]",
                    "duration": "billpay[transaction_credit_duration]",
                    "instalmentsCount": "billpay[transaction_credit_instalments_count]",
                    "instalmentAmount": "billpay[transaction_credit_instalment_amount]",
                    "firstInstalmentAmount": "billpay[transaction_credit_first_instalment_amount]",
                    "totalAmount": "billpay[transaction_credit_total_amount]",
                    "feeAbsolute": "billpay[transaction_credit_fee_absolute]",
                    "feePercentage": "billpay[transaction_credit_fee_percentage]",
                    "processingFee": "billpay[transaction_credit_processing_fee_absolute]",
                    "annualPercentageRate": "billpay[transaction_credit_annual_percentage_rate]",
                    "termsOfService": "billpay[transaction_credit_toc]"
                },
                "paylater": {
                    "customerGroup": "billpay[paylater_customer_group]",
                    "duration": "billpay[paylater_duration]",
                    "instalmentsCount": "billpay[paylater_instalments_count]",
                    "instalmentAmount": "billpay[paylater_instalment_amount]",
                    "feeAbsolute": "billpay[paylater_fee_absolute]",
                    "totalAmount": "billpay[paylater_total_amount]",
                    "termsOfService": "billpay[paylater_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
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
        },
        "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]"
            },
            "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": {
                "invoice": {
                    "customerGroup": "billpay[invoice_customer_group]",
                    "termsOfService": "billpay[invoice_toc]"
                },
                "directDebit": {
                    "customerGroup": "billpay[direct_debit_customer_group]",
                    "termsOfService": "billpay[direct_debit_toc]"
                },
                "transactionCredit": {
                    "customerGroup": "billpay[transaction_credit_customer_group]",
                    "duration": "billpay[transaction_credit_duration]",
                    "instalmentsCount": "billpay[transaction_credit_instalments_count]",
                    "instalmentAmount": "billpay[transaction_credit_instalment_amount]",
                    "firstInstalmentAmount": "billpay[transaction_credit_first_instalment_amount]",
                    "totalAmount": "billpay[transaction_credit_total_amount]",
                    "feeAbsolute": "billpay[transaction_credit_fee_absolute]",
                    "feePercentage": "billpay[transaction_credit_fee_percentage]",
                    "processingFee": "billpay[transaction_credit_processing_fee_absolute]",
                    "annualPercentageRate": "billpay[transaction_credit_annual_percentage_rate]",
                    "termsOfService": "billpay[transaction_credit_toc]"
                },
                "paylater": {
                    "customerGroup": "billpay[paylater_customer_group]",
                    "duration": "billpay[paylater_duration]",
                    "instalmentsCount": "billpay[paylater_instalments_count]",
                    "instalmentAmount": "billpay[paylater_instalment_amount]",
                    "feeAbsolute": "billpay[paylater_fee_absolute]",
                    "totalAmount": "billpay[paylater_total_amount]",
                    "termsOfService": "billpay[paylater_toc]"
                }
            }
        }
    });
</script>

<!-- Container -->
<form id="payment_form">
    <h1>Rechnungskauf</h1>
    <div class="bpy bpy-checkout-container" bpy-pm="invoice"></div>
    <h1>Lastschrift</h1>
    <div class="bpy bpy-checkout-container" bpy-pm="directDebit"></div>
    <h1>PayLater</h1>
    <div class="bpy bpy-checkout-container" bpy-pm="paylater"></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>

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 use of attributes. Please make sure, that all reserved characters are escaped according to the following table:

Reserved Character Escape Sequence
& &amp;
&quot;
&apos;
< &lt;
> &gt;

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

Generic Parameters

Generic parameters for all XML requests

Some parameters are required in all XML requests no matter which 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 an Order

Process Overview

Prescoring

Using the “prescore” scoring model, the identity and credit check of the customer is performed before the payment method options are displayed. The results of the check are then used to display or hide the available payment methods accordingly. This eliminates the negative purchasing experience of a “rejection”.

Flowchart prescoring

“One-Step Order Creation”

Using the “One-Step” order model, the identity and credit check of the customer takes place after they have chosen a BillPay payment method and attempt to finalize their order. In the case of a an approval (status=“APPROVED”) from BillPay, the order can be placed. 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 order. When approved, the order is finalized with this request. [Base-URL]/preauthorize

Flowchart classic scoring

“Two Step Order Creation”

Using the “Two-Step” order model, the identity and credit check of the customer is performed after they have chosen a BillPay payment method and before their order is finalized. In this scenario, you can check to see if the customer can pay using BillPay before they attempt to finalize their order. 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. In the case of an approval (status=“APPROVED”) from BillPay, the customer can proceed to the order overview page to finalize their order. If a customer has the ability to make any changes to their order that impact the order value on the order overview page - like entering a coupon code or changing the shipping method, in the event of such a change, a new preauthorize request must be sent.

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 order process. When approved, the order is not finalized with this request. [Base-URL]/preauthorize
capture Creation of the order in the BillPay system After the final order [Base-URL]/capture

Flowchart prescoring

PayLater with a Downpayment

In order for customers to improve their credit score, we offer a special feature with our “PayLater” (DEU) payment method. Customers have the ability to make a “down payment” via our partner giropay. By offering this option, the acceptance rate for PayLater increases.

Customers that are conditionally accepted if they make a downpayment, are redirected to the giropay banking gateway, where they can use their known and trusted online banking environment to transfer a portion of the order total in real-time. Following the successful transfer, the customer returns to the checkout and the order can be finalized.

Flowchart prepayment

Prescore

With the prescore request, merchants can filter the payment options shown to their customers before they are displayed. This prevents the customer from being presented a negative alert message in the case of a rejection, allowing for a more positive user-experience and dramatically increasing the conversion rate. This option requires every customer to undergo a credit and identity check before landing on the payment method selection page. This service can be viewed as an alternative to scoring a customer after he/she has chosen to use a Billpay payment method. It is necessary for the customer to actively accept an opt-in (check a check box), acknowledging they have read and accept the BillPay terms and conditions, privacy statement, and consent to an identity and credit check.

Only one scoring method, prior to or post selection of the payment method can be used at a time for a given portal.

The response parameters are only valid as long as all of the input parameters sent with the prescore request remain unchanged. As soon as the customer changes his or her personal data or the cart content, the prescore request must be sent again.

Request

Data Node

<data
        requesttype="PRESCORE"
        apiversion="2.0.0"
        originofsale="o">
    <!-- additional request specific data -->
</data>
prescoreRequest prescoreRequest = new PrescoreRequest();
prescoreRequest
    .setOriginOfSale(OriginOfSale.ONLINE_SHOP);    
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PrescoreFactory;

$prescoreRequest = PrescoreFactory::create();
$prescoreRequest
    ->setOriginOfSaleOnline();
Attribute Required Data Type Values Info
requesttype + string PRESCORE 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
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" />
prescoreRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")
    .setSessionId("clear text session id");
<?php
$prescoreRequest
    ->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 1"
        streetnumber=""
        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" />
prescoreRequest.getCustomer()
    .setId("123456")
    .setCustomerType(CustomerType.EXISTING_CUSTOMER)
    .setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
    .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1975/10/12"))
    .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
$customer = $prescoreRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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, .,-,_,/). This ID is displayed in the merchant settlement file.
customertype - string A..1 Type of customer
g: Guest
e: Existing Customer
n: New Customer
salutation + string 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 (e.g. “DEU”): ISO3166 (alpha-3)
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 (e.g. “de”): ISO3166-1 (alpha-2)
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 for:
1. PayLater (paymenttype = “4”)
2. for invoice (paymenttype = “1”) when the customer’s billing address is in the Netherlands (country=“NLD”), and
3. for all payment methods where the customer’s billing address is in Switzerland (country=“CHE”).

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="" />
prescoreRequest.getCustomer().createShippingAddress()
    .setSalutation("Herr")
    .setFirstName("Thomas")
    .setLastName("Testkunde")
    .setStreet("Tinnowitzer Straße")
    .setStreetNumber("1")
    .setZipCode("10115")
    .setCity("Berlin")
    .setCountryIso3("DEU")
    .setPhone("03012345678");
<?php
/* 
if the shipping address is the same as the billing address, you do not need to do anything here.  If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->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 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 (e.g. “DEU”): ISO3166 (alpha-3)
phone - string AN..40 Phone number
cellphone - string AN..40 Mobile number

Company Details Node (Details about business customers)

In case you are offering goods to business customers (customertype = “b”), additional information about the business customer needs to be sent in your request.

<company_details
        name="Testfirma"
        legalform="GmbH"
        registernumber="HRB 122 029 B"
        holdername="Testinhaber Owner"
        taxnumber="DE268874183" />
prescoreRequest.getCustomer().createCompany()
    .setName("Testfirma")
    .setLegalForm("GmbH")
    .setRegisterNumber("HRB 122 029 B")
    .setTaxNumber("DE268874183")
    .setCompanyProprietor("Testinhaber Owner");
<?php
$company = $customer->getCompany();
$company->setLegalFormGmbh()
    ->setName('Testfirma')
    ->setRegisterNumber('HRB 122 029 B')
    ->setCompanyProprietor('Testinhaber Owner')
    ->setTaxNumber('DE268874183');
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 order 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.

<article_data>
    <article 
        articleid="1234" 
        articlequantity="2" 
        articletype="0" 
        articlename="Shirt" 
        articlecategory="Clothing" 
        articlesubcategory1="Van Laack" 
        articlepricenet="10084" 
        articlepricegross="12000" />
    <article
        articleid="2345" 
        articlequantity="1" 
        articletype="0" 
        articlename="Hose" 
        articlecategory="Clothing" 
        articlesubcategory1="Ralph Lauren"  
        articlepricenet="16807" 
        articlepricegross="20000" />
</article_data>
prescoreRequest.getCart().createAndAddArticle()
    .setId("1234")
    .setQuantity(2)
    .setType(ArticleType.OTHER)
    .setName("Shirt")
    .setCategory("Clothing")
    .setFirstSubCategory("Van Laack")
    .setPriceNet(10084)
    .setPriceGross(12000);

prescoreRequest.getCart().createAndAddArticle()
    .setId("2345")
    .setQuantity(1)
    .setType(ArticleType.OTHER)
    .setName("Hose")
    .setCategory("Clothing")
    .setFirstSubCategory("Ralph Lauren")
    .setPriceNet(16807)
    .setPriceGross(20000);    
<?php
$cart = $prescoreRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');    
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: Default
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

Total Node

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

<total 
    shippingname="Express Versand" 
    shippingpricenet="840" 
    shippingpricegross="1000" 
    rebatenet="1681" 
    rebategross="2000" 
    orderamountnet="36134" 
    orderamountgross="43000" 
    currency="EUR" />
prescoreRequest.getShipping()
    .setName("Express Versand")
    .setPriceNet(840)
    .setPriceGross(1000);

prescoreRequest.getCart()
    .setOrderAmountNet(36134)
    .setOrderAmountGross(43000)
    .setCurrencyIso3("EUR")
    .createAndAddRebate()
        .setRebateNet(1681)
        .setRebateGross(2000);
<?php
$shipping = $prescoreRequest->getShipping();
$shipping->setPriceGross('1000')
    ->setPriceNet('840')
    ->setTrackingNumber('123456')
    ->setName('Express Versand');

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate);   
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 order 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 order 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 order 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 order total value (1,00 EUR = 100), if none please use 0
orderamountnet + Positive int N..7 Net value (excluding taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricenet) + shippingpricenet - rebatenet]
orderamountgross + Positive int N..7 Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency + string A..3 3-digit currency code of the order (e.g. “EUR”): ISO4217
reference - string AN..40 Unique order ID from the merchant system. This number is used as an identifier in the settlement file, as well as in subsequent requests to edit a order.
Allowed characters are:
0-9, a-z, A-Z, -,

Regex:
([A-Z]|[a-z]|[0-9]|-|
)*
trackingnumber - string AN..40 Tracking number for shipment

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" />
prescoreRequest
    .setSessionId("clear text session ID");
<?php
$prescoreRequest->setSessionId('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)

Response

Data Node

The data node contains all relevant information about the scoring result. In addition to the simple decision (“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="PRESCORE"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage=""
        status="APPROVED"
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337">
    <!-- additional response specific data -->
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
System.out.println(requestResponse.getAuthorizationStatus());
System.out.println(requestResponse.getTransactionId());
<?php
// send the request to BillPay and retrieve the response
$prescoreResponse = $prescoreRequest->send();

// get data out of the response
if ($prescoreResponse->isError()) {
    echo $prescoreResponse->getStatus();
    echo $prescoreResponse->getErrorCode();
    echo $prescoreResponse->getMerchantMessage();
    echo $prescoreResponse->getDeveloperMessage();
    echo $prescoreResponse->getCustomerMessage();
} else {
    echo $prescoreResponse->getStatus();
    echo $prescoreResponse->getTransactionId();
}
Attribute Required Data Type Values Info
responsetype + string PRESCORE 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(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
<?php
echo $prescoreResponse->getNormalizedAddress()->getStreet();
echo $prescoreResponse->getNormalizedAddress()->getStreetNumber();
echo $prescoreResponse->getNormalizedAddress()->getZipCode();
echo $prescoreResponse->getNormalizedAddress()->getCity();
echo $prescoreResponse->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)

Customer Restriction Node (Optional)

This node returns customer specific restrictions in relation to the order as described in the request. The inclusion of this node in the response must be enabled by BillPay.

<customer_restriction
        shippingtypeobligation="IDENTITY_SHIPPING" />  
System.out.println(requestResponse.getCustomerRestriction().getShippingTypeObligation());
<?php
echo $prescoreResponse->getCustomerRestriction();
Attribute Required Data Type Values Info
shippingtypeobligation - string AN..50 Shipping method restrictions

Allowed Methods Node

This node contains information relating to the allowed payment methods in the case of positive response. Every unique payment method is represented by an individual “payment_method” XML node.

<allowed_methods>
    <payment_method>
      <name>
        INVOICE_B2C
      </name>
      <customer_group>
        p
      </customer_group>
      <payment_type>
        1
      </payment_type>
      <additional_data/>
    </payment_method>
    <payment_method>
      <name>
        DIRECT_DEBIT_B2C
      </name>
      <customer_group>
        p
      </customer_group>
      <payment_type>
        2
      </payment_type>
      <additional_data/>
    </payment_method>
  </allowed_methods>
System.out.println(requestResponse.getAllowedPaymentOptions();
<?php
$allowed = $prescoreResponse->getAllowedPaymentMethods();
foreach($allowed as $billpaypm){
    echo $billpaypm->getCustomerGroup();
    echo $billpaypm->getPaymentId();
    echo $billpaypm->getName();
}
Attribute Mandatory Type Possible Values Details
name + String AN..50 Payment method name
customer_group + String A..1 Customer group
p: Consumer (B2C)
b: Business customer (B2B)
payment_type + String N..1 ID of chosen payment method
1: Invoice
2: Direct Debit
3: Transaction Credit
4: PayLater

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

Request

Data Node

<data
        requesttype="PREAUTHORIZE"
        tcaccepted="1"
        expecteddaystillshipping="0"
        manualcapture="0"
        paymenttype="1"
        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.INVOICE);  

preauthorizeRequest.getShipping()
    .setDaysTillShipping(0);         
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PreauthorizeFactory;

$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
            ->acceptTermsOfUse();
$preauthorizeRequest
    ->setOriginOfSaleOnline()
    ->disableManualCapture();
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 Expected number days until the goods are shipped.
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
1: Invoice
2: Direct Debit
3: Transaction Credit
4: PayLater
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.

Preauth Params

This node is only required if your portal makes use of the prescoring request. If you have not contractually agreed to the implementation of prescoring, than you can ignore this data.

<preauth_params
        isprescored="1"
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337" />
preauthorizeRequest
    .setPrescore("true", "1aa2fb2d-2b78-4393-bf06-be0012dda337");
<?php
$preauthorizeRequest
    ->setPrescoreTransactionId($transactionId);
Attribute Required Data Type Values Info
isprescored + bool 0/1 Value indicates if a prescore request was previously sent for this order.
0: Request was not prescored.
1: Request was prescored.

Please note: prescoring must be activated for your portal.
transactionid + string AN…50 BillPay transaction number

The transaction number is sent in the response to the prescore-request. It is used to match prescore- and preauthorize-requests.

Customer Details Node (customer billing address)

<customer_details
        customerid="123456"
        customertype="e"
        salutation="Herr"
        title=""
        firstname="Thomas"
        lastname="Testkunde"
        street="Tinnowitzer Straße 1"
        streetnumber=""
        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("1974/10/12"))
    .setEmail("anyone@anymail.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
$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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, .,-,_,/). This ID is displayed in the merchant settlement file.
customertype - string A..1 Type of customer
g: Guest
e: Existing Customer
n: New Customer
salutation + string 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 (e.g. “DEU”): ISO3166 (alpha-3)
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 (e.g. “de”): ISO3166-1 (alpha-2)
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 for PayLater (paymenttype = “4”), for invoice (paymenttype = “1”) when the customer’s billing address is in the Netherlands (country=“NLD”), and for all payment methods where the customer’s billing address is in Switzerland (country=“CHE”).

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("Tinnowitzer Straße")
    .setStreetNumber("1")
    .setZipCode("10115")
    .setCity("Berlin")
    .setCountryIso3("DEU")
    .setPhone("03012345678");
<?php
/* 
if the shipping address is the same as the billing address, you do not need to do anything here.  If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->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 (e.g. “DEU”): ISO3166 (alpha-3)
phone - string AN..40 Phone number
cellphone - string AN..40 Mobile number

Company Details Node (Details about business customers)

In case you are offering goods to business customers (customertype = “b”), additional information about the business 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");
<?php
$company = $customer->getCompany();
$company->setLegalFormGmbh()
    ->setName('Testfirma')
    ->setRegisterNumber('HRB 122 029 B')
    ->setCompanyProprietor('Testinhaber Owner')
    ->setTaxNumber('DE268874183');
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 order 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.

<article_data>
    <article 
        articleid="1234" 
        articlequantity="2" 
        articletype="0" 
        articlename="Shirt" 
        articlecategory="Clothing" 
        articlesubcategory1="Van Laack" 
        articlepricenet="10084" 
        articlepricegross="12000" />
    <article
        articleid="2345" 
        articlequantity="1" 
        articletype="0" 
        articlename="Hose" 
        articlecategory="Clothing" 
        articlesubcategory1="Ralph Lauren"  
        articlepricenet="16807" 
        articlepricegross="20000" />
</article_data>
preauthorizeRequest.getCart().createAndAddArticle()
    .setId("1234")
    .setQuantity(2)
    .setType(ArticleType.OTHER)
    .setName("Shirt")
    .setCategory("Clothing")
    .setFirstSubCategory("Van Laack")
    .setPriceNet(10084)
    .setPriceGross(12000);

preauthorizeRequest.getCart().createAndAddArticle()
    .setId("2345")
    .setQuantity(1)
    .setType(ArticleType.OTHER)
    .setName("Hose")
    .setCategory("Clothing")
    .setFirstSubCategory("Ralph Lauren")
    .setPriceNet(16807)
    .setPriceGross(20000);    
<?php
$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');  
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: Default
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

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 “2” or “4”. 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')
            ->setSortCode('');
Attribute Required Data Type Values Info
accountholder + (if paymentType in {2,4) string AN..100 First and last name of account holder
accountnumber + (if paymentType in {2,4}) int AN..30 IBAN - International Bank Account Number
sortcode + (if paymentType in {2,4} 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 order related reference information.

<total
        shippingname="Express Versand"
        shippingpricenet="840"
        shippingpricegross="1000"
        rebatenet="1681"
        rebategross="2000"
        orderamountnet="36134"
        orderamountgross="43000"
        currency="EUR"
        reference="1519088641"
        merchantinvoicenumber="1234567"
        trackingnumber="ABZ12398892131" />
preauthorizeRequest.getShipping()
    .setName("Express Versand")
    .setPriceNet(840)
    .setPriceGross(1000)
    .setTrackingNumber("ABZ12398892131");
preauthorizeRequest.getCart()
     .setOrderAmountNet(36134)
     .setOrderAmountGross(43000)
     .setCurrencyIso3("EUR")
     .setReference("1519088641")
     .setInvoiceNumber("1234567")
     .createAndAddRebate()
        .setRebateNet(1681)
        .setRebateGross(2000);
<?php
$shipping = $preauthorizeRequest->getShipping();
$shipping->setPriceGross('1000')
    ->setPriceNet('840')
    ->setTrackingNumber('123456')
    ->setName('Express Versand');

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate); 
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 order 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 order 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 order 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 order total value (1,00 EUR = 100), if none please use 0
orderamountnet + Positive int N..7 Net value (excluding taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricenet) + shippingpricenet - rebatenet]
orderamountgross + Positive int N..7 Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency + string A..3 3-digit currency code of the order (e.g. “EUR”): ISO4217
reference - string AN..40 Unique order 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]|-|
|#|:|.)*
trackingnumber - string AN..40 Tracking ID for this order shipment

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('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=“4”) 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="46883" />
    preauthorizeRequest.getPaymentDetails().createInstalment()
        .setRateCount(6)
        .setTermInMonths(6)
        .setTotalAmountGross(46883);
<?php
$payment->setRateCount('6')
    ->setRateTerm('6')
    ->setTotal('46883');
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_total_amount] value passed by the widget.

Async Capture Request Node - for our prepayment process

For the payment methods PayLater, BillPay offers a unique “prepayment” feature, which allows certain customers that would ordinarily be denied customers, the ability to complete their purchase, provided they pay a small percentage of the order total upfront (via the Giropay online banking gateway).

This node contains the URLs the customer will be redirected to to perform the online transfer as well as the URL for the asynchronous BillPay server response.

<async_capture_request>
    <redirect_url><![CDATA[http://url1.de/redirect]]></redirect_url>
    <notify_url><![CDATA[http://url1.de/notify]]></notify_url>
</async_capture_request>
    preauthorizeRequest
        .setRedirectUrl("http://url1.de/redirect")
        .setNotifyUrl("http://url1.de/notify");
<?php
$payment->setRedirectUrl('www.redirect.de')
    ->setNotifyUrl('www.notify.de');
Attribute Required Data Type Values Info
redirect_url + string AN Shop-sided result page after successful / failed prepayment.
notify_url + string AN Shop-sided web service URL for async BillPay response.

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(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
System.out.println(requestResponse.getAuthorizationStatus());
System.out.println(requestResponse.getTransactionId());
<?php
// send the request to BillPay and retrieve the response
$preauthorizeResponse = $preauthorizeRequest->send();

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getErrorCode();
    echo $preauthorizeResponse->getMerchantMessage();
    echo $preauthorizeResponse->getDeveloperMessage();
    echo $preauthorizeResponse->getCustomerMessage();
} else {
    echo $preauthorizeResponse->getStatus();
    echo $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(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
<?php
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $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)

Customer Restriction Node - optional

This node returns customer specific restrictions in relation to the order as described in the request. The inclusion of this node in the response must be enabled by BillPay.

<customer_restriction
        shippingtypeobligation="DHL Ident Verfahren"/> 
System.out.println(requestResponse.getCustomerRestriction().getShippingTypeObligation());
<?php
echo $preauthorizeResponse->getCustomerRestriction();
Attribute Required Data Type Values Info
shippingtypeobligation - string AN..50 Shipping method restrictions

Invoice Bank Account Node only for invoice (paymenttype=“1”) and transaction credit in Switzerland (paymenttype=“3”)

This node returns the BillPay bank account data to be used by the customer when paying for their order. 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(Merchant’s order code was passed on to the API)/(Merchant-ID at BillPay) Example: BP1519088641/9999 The merchant’s order code is 1519088641 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="BP1519088641/9999" />
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $preauthorizeResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
Attribute Required Data Type Values Info
activationperformed + bool 0/1 If the order 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

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="1519088641#1" />
</assigned_invoice_number>        
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
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 Transction Credit (paymenttype = “3”) and PayLater (paymenttype = “4”)

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

Paylater (paymenttype = “4”)

<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 = requestResponse.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
$instalmentDetails = $preauthorizeResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
instl_plan + Parent node - this node only appears for paymenttype=“4” (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 order (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 Installment („immediate“, „first“, „date“, „fee“)

Transaction Credit (paymenttype = “3”)

<instalment_details>
    <option ratecount="6" term="6">
      <calculation>
        <base>
          14345
        </base>
        <cart>
          14444
        </cart>
        <surcharge>
          420
        </surcharge>
        <intermediate>
          14765
        </intermediate>
        <total>
          15039
        </total>
        <interest>
          49
        </interest>
        <anual>
          1542
        </anual>
        <fee>
          175
        </fee>
      </calculation>
      <dues>
        <due date="" type="first">
          2739
        </due>
        <due date="" type="following">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
      </dues>
    </option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());

DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $preauthorizeResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
option + Parent node - this node only appears for paymenttype=“3” (Transaction Credit)
ratecount + Positive int N Number of instalments
terminmonths + Positive int N Duration of financing plan in months
calculation + Child node of the option node
  ↳base + Positive int N Portion of the order that is being financed (order value less shipping fees and other charges)
  ↳cart + Positive int N Total value of the order including shipping, but excluding the financing interest
  ↳surcharge + Positive int N Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳intermediate + Positive int N Base amount plus the surcharge for the financing
  ↳total + Positive int N Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳interest + Positive int N Monthly interest surcharge in % (e.g: 59 = 0.59%)
  ↳anual + Positive int N Annual percentage rate in % (e.g: 1614 = 16,14%)
  ↳fee + Positive int N Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000)
dues + Child node of the option node
  ↳due + Child node of the option node. N…7
      ↳date + DATE YYYYMMDD Due date of the instalment
      ↳type + string AN Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)

Async Capture Parameters Node - only relevant for PayLater

This node returns the necessary linking and redirects for the proper implementation of down-payments via GiroPay.

<async_capture_params>
    <rate_plan_url></rate_plan_url>
    <external_redirect_url></external_redirect_url>
</async_capture_params>        
System.out.println(requestResponse.getForwardingDetails().getRatePlanUrl());
System.out.println(requestResponse.getForwardingDetails().getExternalRedirectUrl());
<?php
$asynchCapture = $preauthorizeResponse->getForwardingDetails();
echo $asynchCapture->getRatePlanUrl();
echo $asynchCapture->getExternalRedirectUrl();
Attribute Required Data Type Values Info
rate_plan_url + string AN..255 Link to rate plan.
external_redirect_url + string AN..40 External link to GiroPay to execute pre-payment.

Campaign Node (only relevant for PayLater and down-payments with GiroPay)

This node contains information to be displayed to your shop visitors if their PayLater order request has been approved on the condition of a down-payment via GiroPay.

<campaign>
    <type></type>
    <display_text></display_text>
    <display_image_url></display_image_url>
</campaign>        
System.out.println(requestResponse.getForwardingDetails().getType());
System.out.println(requestResponse.getForwardingDetails().getDisplayText());
System.out.println(requestResponse.getForwardingDetails().getImageUrl());
<?php
echo $asynchCapture->getType();
echo $asynchCapture->getText();
echo $asynchCapture->getImageUrl();
Attribute Required Data Type Values Info
type + string AN..255 Defines what the text and image are for
display_text + string AN Text to be displayed to your customers informing them of the down-payment option.
display_image_url + string AN Image to be displayed to your customers informing them of the down-payment option.

Capture

The capture request is used to complete the order when a two-step capture process is being implemented (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 merchant is transferred from the merchant 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
$captureRequest = CaptureFactory::create();
$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 order reference.

<capture_params
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337"
        orderamountgross="43230" 
        currency="EUR" 
        reference="1519088641" 
        merchantinvoicenumber="1234567"
        customerid="123456789" />
captureRequest
    .setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
    .setMerchantInvoiceNumber("1234567");

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

captureRequest.getCart()
    .setReference("1519088641")
    .setCurrencyIso3("EUR")
    .setOrderAmountGross(43230);
<?php
$captureRequest->setReference('1519088641')
    ->setPortalId(9999)
    ->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
    ->setMerchantInvoiceNumber('1234567')
    ->getCart()
        ->setOrderAmountGross(43230)
        ->setCurrencyIso3('EUR')
    ->getCustomer()
            ->setId('123456789');     
Attribute Required Data Type Values Info
transactionid + string AN..50 Unique BillPay transaction ID for this order - returned in the preauthorize response
orderamountgross + Positive int N..7 Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency + string A..3 3-digit currency code of the order (e.g. “EUR”): ISO4217
reference - string AN..40 Unique order 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. This ID is displayed in the merchant settlement file.
Allowed characters are: 0-9, a-z, A-Z, .,-,_,/

Response

With the capture response, you can determine whether or not the order has been successfully completed at BillPay based upon the returned error code. When the error_code=“0”, the order 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(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$captureResponse = $captureRequest->send();

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $captureResponse->getStatus();
    echo $captureResponse->getErrorCode();
    echo $captureResponse->getMerchantMessage();
    echo $captureResponse->getDeveloperMessage();
    echo $captureResponse->getCustomerMessage();
} else {
    echo $captureResponse->getStatus();
}
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.

Customer Restriction Node - optional

This node returns customer specific restrictions in relation to the order as described in the request. The inclusion of this node in the response must be enabled by BillPay.

<customer_restriction
        shippingtypeobligation="DHL Ident Verfahren"/> 
System.out.println(requestResponse.getCustomerRestriction().getShippingTypeObligation());
<?php
echo $captureResponse->getCustomerRestriction();
Attribute Required Data Type Values Info
shippingtypeobligation - string AN..50 Shipping method restrictions

Invoice Bank Account Node only for invoice (paymenttype=“1”) and transaction credit in Switzerland (paymenttype=“3”)

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

<invoice_bank_account
        activationperformed="0"
        accountholder="BillPay GmbH"
        accountnumber="DE07312312312312312"
        bankcode="BELADEBEXXX"
        bankname="Sparkasse Berlin"
        invoiceduedate="20170813"
        invoicereference="BP1519088641/9999" />
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $captureResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
Attribute Required Data Type Values Info
activationperformed + bool 0/1 If the order 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

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="1519088641#1" />
</assigned_invoice_number>        
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $captureResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
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 Transction Credit (paymenttype = “3”) and PayLater (paymenttype = “4”)

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

Paylater (paymenttype = “4”)

<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 = requestResponse.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
$instalmentDetails = $captureResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
instl_plan + Parent node - this node only appears for paymenttype=“4” (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 order (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 Installment („immediate“, „first“, „date“, „fee“)

Transaction Credit (paymenttype = “3”)

<instalment_details>
    <option ratecount="6" term="6">
      <calculation>
        <base>
          14345
        </base>
        <cart>
          14444
        </cart>
        <surcharge>
          420
        </surcharge>
        <intermediate>
          14765
        </intermediate>
        <total>
          15039
        </total>
        <interest>
          49
        </interest>
        <anual>
          1542
        </anual>
        <fee>
          175
        </fee>
      </calculation>
      <dues>
        <due date="" type="first">
          2739
        </due>
        <due date="" type="following">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
      </dues>
    </option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());

DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $captureResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
option + Parent node - this node only appears for paymenttype=“3” (Transaction Credit)
ratecount + Positive int N Number of instalments
terminmonths + Positive int N Duration of financing plan in months
calculation + Child node of the option node
  ↳base + Positive int N Portion of the order that is being financed (order value less shipping fees and other charges)
  ↳cart + Positive int N Total value of the order including shipping, but excluding the financing interest
  ↳surcharge + Positive int N Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳intermediate + Positive int N Base amount plus the surcharge for the financing
  ↳total + Positive int N Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳interest + Positive int N Monthly interest surcharge in % (e.g: 59 = 0.59%)
  ↳anual + Positive int N Annual percentage rate in % (e.g: 1614 = 16,14%)
  ↳fee + Positive int N Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000)
dues + Child node of the option node
  ↳due + Child node of the option node. N…7
      ↳date + DATE YYYYMMDD Due date of the instalment
      ↳type + string AN Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)

Managing an Order

Request Overview

XML service Meaning Time of execution Service URL
Activation Invoice: Setting of the payment due date; Direct Debit/PayLater: Initialization of the debit process When generating the invoice; usually this action is triggered by a backend workflow or scheduled task/cron job. [Base-URL]/invoiceCreated
Cancellation A full cancellation of the existing order which leaves the order value at 0 €. Usually this action is triggered by a backend workflow or scheduled task/cron job. [Base-URL]/cancel
Editing the order Any change in the content of the existing order or the included fees/rebates of the order. Usually triggered when elements of the order that impact the overall cost have changed or the order has been cancelled, but a cancellation fee remains. [Base-URL]/editCartContent
Updating the order ID Update the order ID (reference number). Used in cases where the order is completed before the order reference number is available/known. Order process; after the order is placed in the shop [Basis-URL]/updateOrder
Get the bank details for payment Only for invoice orders. Retrieve the payment details for a given order for display on the order invoice From the backend, in cases where the bank details can’t be used/saved from the capture/invoiceCreated response. [Basis-URL]/getBillPayBankData

Invoice Creation

The “invoiceCreated” request is used to set the customer’s payment due date (“invoice” and “transaction credit CHE”) / start the debit process (“Direct Debit” and “PayLater”). This process is called the “activation” of the debt and has to be triggered for each order prior to the invoice being printed. Only if the BillPay XML service response indicates no error (errorcode=“0”), is all the necessary data for the invoice document available. For the payment methods Direct Debit and PayLater, this process will set the debit date for the funds to be drawn from the customer’s bank account. BillPay also offers merchants the ability to split ship their orders for the payment methods invoice and direct debit. This is an option that needs to be activated by BillPay.

Request

Data Node

<data
        requesttype="INVOICE_CREATED"
        apiversion="2.0.0">
    <!-- Request Data -->
</data>
Attribute Data Type Values Info
requesttype string INVOICE_CREATED 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" />
invoiceCreatedRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")
<?php
$invoiceRequest = InvoiceCreatedFactory::create();
$invoiceRequest->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.

Invoice Params Node

<invoice_params
    invoiceamountnet="19327"
    invoiceamountgross="23000"
    is_partial="0" 
    rebatenet="1681" 
    rebategross="2000"
    shippingname="Express Versand" 
    shippingpricenet="840" 
    shippingpricegross="1000" 
    currency="EUR" 
    reference="1773673332" 
    deliverydelayindays="0" 
    merchantinvoicenumber="1234567"
    trackingnumber="ABZ12398892131" />
invoiceCreatedRequest
    .setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
    .setMerchantInvoiceNumber("1234567")
    .setIsPartial(0)
    .setDeliveryDelayInDays(0);

invoiceCreatedRequest.getShipping()
    .setName("Express Versand")
    .setPriceNet(840)
    .setPriceGross(1000)
    .setTrackingNumber("ABZ12398892131"); 

invoiceCreatedRequest.getCart()
    .setReference("1519088641")
    .setInvoiceNumber("1234567")
    .setCurrencyIso3("EUR")
    .setOrderAmountGross(23000)
    .setOrderAmountNet(19327);      
<?php
$invoice = $invoiceRequest->getInvoice();

$invoice->setDeliveryDelayInDays(0)
    ->isPartialActivation(0)
    ->setMerchantInvoiceNumber('1234567');

$invoice->getShipping()
    ->setName('shipping')
    ->setPriceGross('1000')
    ->setPriceNet('950')
    ->setTrackingNumber('ABZ12398892131');

$invoice->getCart()
    ->setOrderAmountGross('23000')
    ->setOrderAmountNet('19327')
    ->setCurrencyIso3('EUR')
    ->createAndAddRebate()
        ->setPriceGross('2000')
        ->setPriceNet('1681');
Attribute Required Data Type Possible values Info
invoiceamountnet - Positive int N..7 Net value (excluding taxes) of the order total (1,00 EUR = 100)
invoiceamountgross + Positive int N..7 Gross value (including taxes) of the order total (1,00 EUR = 100)
ispartial + boolean 0/1 0: Shipping/Activation of the full order
1: Partial shipment / partial activation
rebatenet - non-negative int N..7 Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
rebategross - non-negative int N..7 Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
shippingname - string AN..50 Shipping method name (e.g. “Express”)
shippingpricenet - non-negative int N..7 Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross - non-negative int N..7 Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
currency + string A..3 3-digit currency code of the order (e.g. “EUR”): ISO4217
reference + string AN..40 Unique order 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]|-|
|#|:|.)*
trackingnumber - string AN..40 Tracking ID for this order shipment
deliverydelayindays + non-negative int N..3 Amount of days that will be added to the payment due date (e.g. in case of delayed shipping)

Article Data Node - list of all sent articles All information concerning the shipped products are collected in the article_data node. Every unique article is represented by an individual “article” XML tag.

<article_data>
    <article
            articleid="2345"
            articlequantity="1"
            articlename="Hose"
            articlecategory="Clothing"
            articlesubcategory1="Ralph Lauren"
            articlepricenet="16807"
            articlepricegross="20000" />
</article_data>
invoiceCreatedRequest.getCart().createAndAddArticle()
    .setId("2345")
    .setQuantity(1)
    .setType(ArticleType.OTHER)
    .setName("Hose")
    .setCategory("Clothing")
    .setFirstSubCategory("Ralph Lauren")
    .setPriceNet(16807)
    .setPriceGross(20000);    
<?php
$invoice->getCart()->createAndAddArticle()
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setName('Hose')
    ->setQuantity('1')
    ->setId('2345')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Ralph Lauren');
Attribute Required Data Type Values Info
articleid + string AN..20 Unique article ID
articlename + string AN..50 Article name
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)

Partial Shipment / partial activation is only possible for the following payment methods:

Payment Method ID Payment Method
1 Invoice
2 Direct Debit

Response

For the payment methods “invoice” and “transaction credit Switzerland”, the invoiceCreated response contains the BillPay bank account data and the payment due date to be printed on the invoice for the customer. This bank information, in combination with the payment due date and the transaction purpose, needs to be sent to the customer, so they can pay their invoice in a timely fashion.

For the payment methods “PayLater” and “Direct Debit”, these parameters have no meaning and can be ignored. Instead, a static text, as found in the “Customer Documents” must be printed on the document.

Data Node

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="INVOICE_CREATED"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage="">
    <!-- weitere Antwortdaten -->
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$invoiceResponse = $invoiceRequest->send();

// get data out of the response
echo $invoiceResponse->getErrorCode();
echo $invoiceResponse->getMerchantMessage();
echo $invoiceResponse->getDeveloperMessage();
echo $invoiceResponse->getCustomerMessage();
Attribute Required Data Type Values Info
responsetype + string INVOICE_CREATED 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

Invoice Bank Account Node only for invoice (paymenttype=“1”) and transaction credit in Switzerland (paymenttype=“3”)

This node returns the BillPay bank account data to be used by the customer when paying for their order. This information should be parsed and printed on the invoice document the customers receive with their shipment. In the case of partial activation (split shipping), the bank details and invoicereference are the same for all invoices generated from a given order.

<invoice_bank_account
        activationperformed="1"
        accountholder="BillPay GmbH"
        accountnumber="DE07312312312312312"
        bankcode="BELADEBEXXX"
        bankname="Sparkasse Berlin"
        invoiceduedate="20170707"
        invoicereference="BP555666777/9999"/>
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $invoiceResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
Attribute Required Data Type Values Info
activationperformed + bool 0/1 Is the order 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

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="Z2I8EB#1" />
</assigned_invoice_number>        
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $invoiceResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
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 Transction Credit (paymenttype = “3”) and PayLater (paymenttype = “4”)

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

Paylater (paymenttype = “4”)

<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 = requestResponse.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
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
instl_plan + Parent node - this node only appears for paymenttype=“4” (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 order (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 Installment („immediate“, „first“, „date“, „fee“)

Transaction Credit (paymenttype = “3”)

<instalment_details>
    <option ratecount="6" term="6">
      <calculation>
        <base>
          14345
        </base>
        <cart>
          14444
        </cart>
        <surcharge>
          420
        </surcharge>
        <intermediate>
          14765
        </intermediate>
        <total>
          15039
        </total>
        <interest>
          49
        </interest>
        <anual>
          1542
        </anual>
        <fee>
          175
        </fee>
      </calculation>
      <dues>
        <due date="" type="first">
          2739
        </due>
        <due date="" type="following">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
      </dues>
    </option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());

DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
option + Parent node - this node only appears for paymenttype=“3” (Transaction Credit)
ratecount + Positive int N Number of instalments
terminmonths + Positive int N Duration of financing plan in months
calculation + Child node of the option node
  ↳base + Positive int N Portion of the order that is being financed (order value less shipping fees and other charges)
  ↳cart + Positive int N Total value of the order including shipping, but excluding the financing interest
  ↳surcharge + Positive int N Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳intermediate + Positive int N Base amount plus the surcharge for the financing
  ↳total + Positive int N Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳interest + Positive int N Monthly interest surcharge in % (e.g: 59 = 0.59%)
  ↳anual + Positive int N Annual percentage rate in % (e.g: 1614 = 16,14%)
  ↳fee + Positive int N Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000)
dues + Child node of the option node
  ↳due + Child node of the option node. N…7
      ↳date + DATE YYYYMMDD Due date of the instalment
      ↳type + string AN Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)

Cancel

Using the cancel request, an existing order 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")
<?php
$cancelRequest = CancelFactory::create();

$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="1519088641"
        orderamountgross="43000"
        currency="EUR" />
cancelRequest.getCart()
    .setReference("1519088641")
    .setCurrencyIso3("EUR")
    .setOrderAmountGross(43000);
<?php
$cancelRequest->setReference('1519088641');

$cancelRequest->getCart()
    ->setOrderAmountGross(43000)
    ->setCurrencyIso3('EUR');
Attribute Required Data Type Values Info
reference + string AN..40 Unique order ID from the merchant system.
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 order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross]
currency + string A..3 3-digit currency code of the order (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());
<?php
// send the request to BillPay and retrieve the response
$cancelResponse = $cancelRequest->send();

// get data out of the response
echo $cancelResponse->getErrorCode();
echo $cancelResponse->getMerchantMessage();
echo $cancelResponse->getDeveloperMessage();
echo $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 order can be adjusted. Using this call, articles can be removed or changed and fees can be reduced or increased.

Adding articles or increasing fees must follow certain predefined rules:

  • If the new order value is lower than the old one, the edit will always succeed.
  • If the new order 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 order will not be adjusted.
  • An increase for orders where PayLater is the payment method are not allowed.

The request itself contains the information for the new desired order. All differences between old and new order 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")
<?php
$editCartContentRequest = EditCartContentFactory::create();
$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 order and all connected fees / rebates.

<total
        shippingname="Express Versand"
        shippingpricenet="840"
        shippingpricegross="1000"
        rebatenet="1681"
        rebategross="2000"
        orderamountnet="26050"
        orderamountgross="31000"
        currency="EUR"
        reference="1519088641"
        trackingnumber="12345" />
editCartContentRequest.getShipping()
    .setName("Express Versand")
    .setPriceNet(840)
    .setPriceGross(1000);

editCartContentRequest.getCart()
    .setOrderAmountNet(26050)
    .setOrderAmountGross(31000)
    .setCurrencyIso3("EUR")
    .setReference("1519088641")
    .createAndAddRebate()
        .setRebateNet(1681)
        .setRebateGross(2000);
<?php
$editCartContentRequest->setReference('1519088641');

$editCartContentRequest->getShipping()
    ->setName('Express Versand')
    ->setPriceGross(1000)
    ->setPriceNet(840)
    ->setTrackingNumber('12345');

$editCartContentRequest->getCart()
    ->setOrderAmountNet('26050')
    ->setOrderAmountGross('31000')
    ->setCurrencyIso3('EUR');

$editCartContentRequest->getCart()->createAndAddRebate()
    ->setPriceGross(2000)
    ->setPriceNet(1681);                       
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 order 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 order 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 order 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 order total value (1,00 EUR = 100), if none please use 0
orderamountnet + Positive int N..7 Net value (excluding taxes) of the order total (1,00 EUR = 100) [(sum of the remaining articlepricenet) + shippingpricenet - rebatenet]
orderamountgross + Positive int N..7 Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of the remaining articlepricegross) + shippingpricegross - rebategross]
currency + string A..3 3-digit currency code of the order (e.g. “EUR”): ISO4217
reference + string AN..40 Unique order ID from the merchant system.
Allowed characters are:
0-9, a-z, A-Z, -,

Regex:
([A-Z]|[a-z]|[0-9]|-|
)*
trackingnumber - string AN..40 Tracking ID for this order shipment

Article Data Node (List of all ordered 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.

<article_data>
    <article
            articleid="2345"
            articlequantity="1"
            articletype="0"
            articlename="Hose"
            articlecategory="Clothing"
            articlesubcategory1="Ralph Lauren"
            articlepricenet="16807"
            articlepricegross="20000" />
</article_data>
editCartContentRequest.getCart().createAndAddArticle()
    .setId("2345")
    .setQuantity(1)
    .setType(ArticleType.OTHER)
    .setName("Hose")
    .setCategory("Clothing")
    .setFirstSubCategory("Ralph Lauren")
    .setPriceNet(16807)
    .setPriceGross(20000);    
<?php
$editCartContentRequest->getCart()->createAndAddArticle()
    ->setId(2345)
    ->setQuantity(1)
    ->setName('Hose')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Ralph Lauren')
    ->setPriceGross('16807')
    ->setPriceNet('20000');
Attribute Required Data Type Values Info
articleid + string AN..20 Unique article ID
articlename + string AN..50 Article name
articlequantity + Positive int N..7 Article quantity
articletype + non-negative int N..1 Item classification: 0: Default
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)

Special Feature: Editing of partially shipped orders

In addition to the information described above, an invoice_list has to be added when editing partially shipped orders. This list references each individual partial invoice via the invoice_number parameter. In each invoice node the details of the partial shipment are described in an invoice_params node. Here, total amount of the invoice, shipping costs and any kind of rebates are summed up. It also contains the usual article_data node to highlight what articles were shipped in that particular invoice. Please review the examples below.

Invoice List Node

<invoice_list>
    <invoice merchantinvoicenumber="1234567">
        <invoice_params
            invoiceamountnet="19327"
            invoiceamountgross="23000"
            rebatenet="1681" 
            rebategross="2000"
            shippingname="Express Versand" 
            shippingpricenet="840" 
            shippingpricegross="1000" 
            currency="EUR" 
            reference="1773673332" 
            trackingnumber="ABZ12398892131" />
         <article_data>
            <article
                    articleid="2345"
                    articlequantity="1"
                    articlename="Hose"
                    articlepricenet="16807"
                    articlepricegross="20000" />
        </article_data>   
    </invoice>
</invoice_list>            
  Invoice invoice1 = editCartContentRequest.createAndAddInvoice("1234567")
        .setTotalPriceNet(15966)
        .setTotalPriceGross(19000)
        .setShippingPriceNet(840)
        .setShippingPriceGross(1000)
        .setShippingName("shipping name")
        .setRebateNet(1681)
        .setRebateGross(2000);

    invoice1.createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setName("Hose")
        .setPriceNet(16807)
        .setPriceGross(20000);
<?php
$invoice1 = $editCartContentRequest->createAndAddInvoice()
    ->setMerchantInvoiceNumber('1234567');

$invoice1->getCart()
    ->setOrderAmountNet('19327')
    ->setOrderAmountGross('23000')
    ->setCurrencyIso3('EUR');

$invoice1->getShipping()
    ->setName('shipping name')
    ->setPriceGross('1000')
    ->setPriceNet('840')
    ->setTrackingNumber('ABZ12398892131');

$invoice1->getCart()->createAndAddArticle()
    ->setId(2345)
    ->setQuantity(1)
    ->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->appendTo($editCartContentRequest->getCart()); // append to ecc request cart as well

$invoice1->getCart()->createRebate()
    ->setPriceGross(1010)
    ->setPriceNet(1009)
    ->appendTo($invoice1->getCart()); 
Attribute Required Data Type Possible values Info
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]|-|
|#|:|.)*
invoice_params + Child node of the invoice node
  ↳shippingname - string AN..50 Shipping method name (e.g. “Express”)
  ↳trackingnumber - string AN..40 Tracking ID for this order shipment
  ↳shippingpricenet - non-negative int N..7 Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
  ↳shippingpricegross - non-negative int N..7 Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
  ↳rebatenet - non-negative int N..7 Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
  ↳rebategross - non-negative int N..7 Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the -> order total value (1,00 EUR = 100)
  ↳invoiceamountnet - Positive int N..7 Net value (excluding taxes) of the order total (1,00 EUR = 100)
  ↳invoiceamountgross + Positive int N..7 Gross value (including taxes) of the order total (1,00 EUR = 100)
article_data + Child node of the invoice node
  ↳article + Child element of the article_data node
      ↳articleid + string AN..20 Unique article ID
      ↳articlename + string AN..50 Article name
      ↳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 for 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(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$editCartContentResponse = $editCartContentRequest->send();

// get data out of the response
echo $editCartContentResponse->getErrorCode();
echo $editCartContentResponse->getMerchantMessage();
echo $editCartContentResponse->getDeveloperMessage();
echo $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="1519088641#1" />
</assigned_invoice_number>        
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);

System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $editCartContentResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
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 Transction Credit (paymenttype = “3”) and PayLater (paymenttype = “4”)

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

Paylater (paymenttype = “4”)

<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 = requestResponse.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
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
instl_plan + Parent node - this node only appears for paymenttype=“4” (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 order (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 Installment („immediate“, „first“, „date“, „fee“)

Transaction Credit (paymenttype = “3”)

<instalment_details>
    <option ratecount="6" term="6">
      <calculation>
        <base>
          14345
        </base>
        <cart>
          14444
        </cart>
        <surcharge>
          420
        </surcharge>
        <intermediate>
          14765
        </intermediate>
        <total>
          15039
        </total>
        <interest>
          49
        </interest>
        <anual>
          1542
        </anual>
        <fee>
          175
        </fee>
      </calculation>
      <dues>
        <due date="" type="first">
          2739
        </due>
        <due date="" type="following">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
        <due date="" type="date">
          2460
        </due>
      </dues>
    </option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());

DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute Required Data Type Values Info
option + Parent node - this node only appears for paymenttype=“3” (Transaction Credit)
ratecount + Positive int N Number of instalments
terminmonths + Positive int N Duration of financing plan in months
calculation + Child node of the option node
  ↳base + Positive int N Portion of the order that is being financed (order value less shipping fees and other charges)
  ↳cart + Positive int N Total value of the order including shipping, but excluding the financing interest
  ↳surcharge + Positive int N Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳intermediate + Positive int N Base amount plus the surcharge for the financing
  ↳total + Positive int N Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000)
  ↳interest + Positive int N Monthly interest surcharge in % (e.g: 59 = 0.59%)
  ↳anual + Positive int N Annual percentage rate in % (e.g: 1614 = 16,14%)
  ↳fee + Positive int N Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000)
dues + Child node of the option node
  ↳due + Child node of the option node. N…7
      ↳date + DATE YYYYMMDD Due date of the instalment
      ↳type + string AN Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)

Update Order

Request

Using the UpdateOrder request, the unique order reference can be changed. This request, if required, must be sent before the order is activated via the invoiceCreated request.

Data Node

<data 
    requesttype="UPDATE_ORDER" 
    apiversion="2.0.0">
    <!-- Request Daten -->
</data>
Attribute Data Type Values Info
requesttype string UPDATE_ORDER 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" />
updateOrderRequest
    .setMerchantId(1234)
    .setPortalId(9999)
    .setApiPassword("clear text password")
<?php
$updateOrderRequest = UpdateOrderFactory::create();
$updateOrderRequest
    ->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');
Attribute Required Data Type Info
mid + Positive integer Merchant ID
pid + Positive integer Portal ID
passwordhash + string MD5 hash of the security key generated for this portal.

Update Params Node

This node contains the the unique BillPay transaction ID (retrieved from the original preauthorize server response) and the new desired order reference.

<update_params
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337"
        reference="1591605922_updated" />
updateOrderRequest
    .setReference("1591605922_updated")
    .setTransactionId("b61648a3-46a1-4771-834f-903b89510ed9");
<?php
$updateOrderRequest
    ->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
    ->setReference('1591605922_updated');
Attribute Required Data Type Values Info
transactionid + string AN..50 Unique BillPay transaction ID for this order
reference + string AN..40 Unique order ID from the merchant system.
Allowed characters are:
0-9, a-z, A-Z, -,

Regex:
([A-Z]|[a-z]|[0-9]|-|
)*

ID Update List Node

This node contains all individual article IDs to be updated by the request.

<id_update_list>
    <id_update articleid="2345" updateid="2345_mod"/>
</id_update_list>
updateOrderRequest.createAndAddUpdateOrder()
    .setNewId("2345")
    .setOldId("2345_mod"); 
<?php
$updateOrderRequest->getCart()->createAndAddArticleUpdate()
    ->setId('2345')
    ->setNewId('2345_mod');
Attribute Required Data Type Values Info
articleid + string AN..40 The original article ID
updateid + string AN..40 The new article ID

Response

Data Node

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="UPDATE_ORDER"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        developermessage="">
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$updateOrderResponse = $updateOrderRequest->send();

// get data out of the response
echo $updateOrderResponse->getErrorCode();
echo $updateOrderResponse->getMerchantMessage();
echo $updateOrderResponse->getDeveloperMessage();
echo $updateOrderResponse->getCustomerMessage();
Attribute Required Data Type Values Info
responsetype + string UPDATE_ORDER 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

Get Billpay Bank Data

Request

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

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")
<?php
$bankDataRequest = GetBillPayBankDataFactory::create();
$bankDataRequest->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="1519088641" />
getBillPayBankDataRequest.setReference("1519088641");
<?php
$bankDataRequest->setReference('1519088641');
Attribute Required Data Type Values Info
reference + string AN..40 Unique order ID from the merchant system.
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

<?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(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$bankDataResponse = $bankDataRequest->send();

// get data out of the response
echo $bankDataResponse->getErrorCode();
echo $bankDataResponse->getMerchantMessage();
echo $bankDataResponse->getDeveloperMessage();
echo $bankDataResponse->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=“1”) and transaction credit in Switzerland (paymenttype=“3”)

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

<bank_account
        accountholder="BillPay GmbH"
        accountnumber="DE07312312312312312"
        bankcode="BELADEBEXXX"
        bankname="Sparkasse Berlin"
        firstduedate="20170707"
        invoicereference="BP1519088641/9999" />
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $bankDataResponse->getInvoiceBankAccount();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->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 = requestResponse.getDueDates().get(0);

System.out.println(dueDate.getDuedate());
System.out.println(dueDate.getInvoiceid());
<?php
$dueDate = $bankDataResponse->getDueDates();
echo $dueDate->getDuedate();
echo $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 Invoice number in the BillPay system.
Allowed characters are:
0-9, a-z, A-Z, -, , #, ., :

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 order 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
Transaction Credit

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 order by the BillPay GmbH.
Instalments (DE, AT) 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 order 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 order was completed and on the order 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.
Transaction Credit (CH) Sie haben sich für die Zahlungsweise Ratenkauf entschieden. Bitte beachten Sie, dass zusätzlich zu dem auf dieser Rechnung genannten Rechnungsbetrag weitere Kosten im Zusammenhang mit dem Ratenkauf 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 Ratenkauf, sowie sämtliche dazugehörige Informationen werden Sie direkt per E-Mail von der BillPay GmbH erhalten. You have chosen to pay for your order with BillPay Transaction Credit. Please note that in addition to the total amount mentioned on this invoice, additional costs are incurred in connection with the rate plan. These costs were displayed to you before the order was completed and on the order confirmation page. The full calculation of the amounts to be paid in connection with the rate plan, as well as all related information, will be sent to you via e-mail by the BillPay GmbH.

Sample Requests

Prescore

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PRESCORE" 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="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="36134" orderamountgross="43000" currency="EUR" />
    <article_data>
        <article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000">
        </article> 
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren"  articlepricenet="16807" articlepricegross="20000">
        </article>    
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>
private void prescoreExample() throws ParseException {
    //build the request
    PrescoreRequest prescoreRequest = new PrescoreRequest();
    prescoreRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session ID");

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

    prescoreRequest
        .setOriginOfSale(OriginOfSale.ONLINE_SHOP);

    prescoreRequest.getCustomer()
        .setId("123456")
        .setCustomerType(CustomerType.EXISTING_CUSTOMER)
        .setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
        .setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1975/10/12"))
        .setEmail("anymail@example.org")
        .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");

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

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

    prescoreRequest.getCart()
        .setOrderAmountNet(36134)
        .setOrderAmountGross(43000)
        .setCurrencyIso3("EUR")
        .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

    prescoreRequest.getCart().createAndAddArticle()
        .setId("1234")
        .setQuantity(2)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setCategory("Clothing")
        .setFirstSubCategory("Van Laack")
        .setPriceNet(10084)
        .setPriceGross(12000);

    prescoreRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setCategory("Clothing")
        .setFirstSubCategory("Ralph Lauren")
        .setPriceNet(16807)
        .setPriceGross(20000); 

    //sending the request to BillPay and retrieving the response

    PrescoreResponse requestResponse = prescoreRequest.send();

    //getting data out of the response

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

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

    }
}
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PrescoreFactory;

$prescoreRequest = PrescoreFactory::create();

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

$customer = $prescoreRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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');

$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->setCity('Berlin')
    ->setCountryIso3('DEU')
    ->setPhone('03012345678');

$company = $customer->getCompany();
$company->setLegalFormGmbh()
    ->setName('Testfirma')
    ->setRegisterNumber('HRB 122 029 B')
    ->setCompanyProprietor('Testinhaber Owner')
    ->setTaxNumber('DE268874183');

$cart = $prescoreRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');    

$shipping = $prescoreRequest->getShipping();
$shipping->setPriceGross('1000')
    ->setPriceNet('840')
    ->setTrackingNumber('123456')
    ->setName('Express Versand');

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate);   

$prescoreRequest->setSessionId('session id'); 

// send the request to BillPay and retrieve the response
$prescoreResponse = $prescoreRequest->send();

// get data out of the response
if ($prescoreResponse->isError()) {
    echo $prescoreResponse->getStatus();
    echo $prescoreResponse->getErrorCode();
    echo $prescoreResponse->getMerchantMessage();
    echo $prescoreResponse->getDeveloperMessage();
    echo $prescoreResponse->getCustomerMessage();
} else {
    echo $prescoreResponse->getStatus();
    echo $prescoreResponse->getTransactionId();
    echo $prescoreResponse->getCustomerRestriction();
    $allowed = $prescoreResponse->getAllowedPaymentMethods();
    foreach($allowed as $billpaypm){
        echo $billpaypm->getCustomerGroup();
        echo $billpaypm->getPaymentId();
        echo $billpaypm->getName();
    }
}

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

Preauth: Invoice-B2C

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" 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="1519088641" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131"/>
    <article_data>
        <article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />    
    </article_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);

    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()
        .setName("Express Versand")
        .setPriceNet(840)
        .setPriceGross(1000)
        .setTrackingNumber("ABZ12398892131");

    preauthorizeRequest.getCart()
         .setOrderAmountNet(36134)
         .setOrderAmountGross(43000)
         .setCurrencyIso3("EUR")
         .setReference("1519088641")
         .setInvoiceNumber("1234567")
         .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("1234")
        .setQuantity(2)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setCategory("Clothing")
        .setFirstSubCategory("Van Laack")
        .setPriceNet(10084)
        .setPriceGross(12000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setCategory("Clothing")
        .setFirstSubCategory("Ralph Lauren")
        .setPriceNet(16807)
        .setPriceGross(20000);  

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse requestResponse = preauthorizeRequest.send();

    //getting data out of the response

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

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

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

$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
            ->acceptTermsOfUse();

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

$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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');

/* 
if the shipping address is the same as the billing address, you do not need to do anything here.  If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->setCity('Berlin')
    ->setCountryIso3('DEU');

$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');

$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');  

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

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');

$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate); 

$preauthorizeRequest->setSessionId('session id'); 

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

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getErrorCode();
    echo $preauthorizeResponse->getMerchantMessage();
    echo $preauthorizeResponse->getDeveloperMessage();
    echo $preauthorizeResponse->getCustomerMessage();
} else {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getTransactionId();

    echo $preauthorizeResponse->getCustomerRestriction();

    $bankAccount = $preauthorizeResponse->getInvoiceBankAccount();
    echo $bankAccount->isActivationPerformed();
    echo $bankAccount->getAccountHolder();
    echo $bankAccount->getAccountNumber();
    echo $bankAccount->getBankCode();
    echo $bankAccount->getBankName();
    echo $bankAccount->getInvoiceDueDate();
    echo $bankAccount->getInvoiceReference();
    echo $bankAccount->getEsrReference();
    echo $bankAccount->getEsrCodeLine();

    $invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
    echo $invoiceNumber->getInvoiceId();
    echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();

Preauth: Invoice-B2B

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" 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="anymail@gmx.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="b" />
    <shipping_details usebillingaddress="1" />
    <company_details name="Testfirma" legalform="GmbH" registernumber="HRB 122 029 B" holdername="Testinhaber" taxnumber="DE268874183" />
    <total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="36134" orderamountgross="43000" currency="EUR" reference="123456" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131" />
    <article_data>
        <article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_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);

    preauthorizeRequest.getCustomer()
        .setId("123456")
        .setCustomerType(CustomerType.EXISTING_CUSTOMER)
        .setCustomerGroup(CustomerGroup.BUSINESS_CLIENT)
        .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.getCustomer().createCompany()
        .setName("Testfirma")
        .setLegalForm("GmbH")
        .setRegisterNumber("HRB 122 029 B")
        .setTaxNumber("DE268874183")
        .setCompanyProprietor("Testinhaber Owner");   

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

    preauthorizeRequest.getCart()
         .setOrderAmountNet(36134)
         .setOrderAmountGross(43000)
         .setCurrencyIso3("EUR")
         .setReference("1519088641")
         .setInvoiceNumber("1234567")
         .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("1234")
        .setQuantity(2)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setCategory("Clothing")
        .setFirstSubCategory("Van Laack")
        .setPriceNet(10084)
        .setPriceGross(12000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setCategory("Clothing")
        .setFirstSubCategory("Ralph Lauren")
        .setPriceNet(16807)
        .setPriceGross(20000);  

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse requestResponse = preauthorizeRequest.send();

    //getting data out of the response

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

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

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

$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
            ->acceptTermsOfUse();

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

$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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');

/* 
if the shipping address is the same as the billing address, you do not need to do anything here.  If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->setCity('Berlin')
    ->setCountryIso3('DEU');

$company = $customer->getCompany();
$company->setLegalFormGmbh()
    ->setName('Testfirma')
    ->setRegisterNumber('HRB 122 029 B')
    ->setCompanyProprietor('Testinhaber Owner')
    ->setTaxNumber('DE268874183');

$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');

$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');  

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

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');

$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate); 

$preauthorizeRequest->setSessionId('session id'); 

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

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getErrorCode();
    echo $preauthorizeResponse->getMerchantMessage();
    echo $preauthorizeResponse->getDeveloperMessage();
    echo $preauthorizeResponse->getCustomerMessage();
} else {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getTransactionId();

    echo $preauthorizeResponse->getCustomerRestriction();

    $bankAccount = $preauthorizeResponse->getInvoiceBankAccount();
    echo $bankAccount->isActivationPerformed();
    echo $bankAccount->getAccountHolder();
    echo $bankAccount->getAccountNumber();
    echo $bankAccount->getBankCode();
    echo $bankAccount->getBankName();
    echo $bankAccount->getInvoiceDueDate();
    echo $bankAccount->getInvoiceReference();
    echo $bankAccount->getEsrReference();
    echo $bankAccount->getEsrCodeLine();

    $invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
    echo $invoiceNumber->getInvoiceId();
    echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();

Preauth: Direct Debit

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="2" 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="1519088641" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131" />
    <article_data>
        <article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />    
    </article_data>
    <bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
    <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.DIRECT_DEBIT);

    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()
        .setName("Express Versand")
        .setPriceNet(840)
        .setPriceGross(1000)
        .setTrackingNumber("ABZ12398892131");
    preauthorizeRequest.getCart()
         .setOrderAmountNet(36134)
         .setOrderAmountGross(43000)
         .setCurrencyIso3("EUR")
         .setReference("1519088641")
         .setInvoiceNumber("1234567")
         .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("1234")
        .setQuantity(2)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setCategory("Clothing")
        .setFirstSubCategory("Van Laack")
        .setPriceNet(10084)
        .setPriceGross(12000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setCategory("Clothing")
        .setFirstSubCategory("Ralph Lauren")
        .setPriceNet(16807)
        .setPriceGross(20000);  

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

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse requestResponse = preauthorizeRequest.send();

    //getting data out of the response

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

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

$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_DIRECT_DEBIT);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
            ->acceptTermsOfUse();

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

$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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');

/* 
if the shipping address is the same as the billing address, you do not need to do anything here.  If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->setCity('Berlin')
    ->setCountryIso3('DEU');

$preauthorizeRequest->getBankAccount()
            ->setAccountHolder('Thomas Testkunde')
            ->setAccountNumber('DE12500105170648489890')
            ->setSortCode('');    

$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');

$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');  

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

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');

$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate); 

$preauthorizeRequest->setSessionId('session id'); 

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

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getErrorCode();
    echo $preauthorizeResponse->getMerchantMessage();
    echo $preauthorizeResponse->getDeveloperMessage();
    echo $preauthorizeResponse->getCustomerMessage();
} else {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getTransactionId();

    echo $preauthorizeResponse->getCustomerRestriction();

    $invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
    echo $invoiceNumber->getInvoiceId();
    echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();

Preauth: PayLater

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="4" 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="1519088641" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131" />
    <article_data>
        <article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />    
    </article_data>
    <rate_request ratecount="6" terminmonths="6" totalamountgross="46883" />
    <bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
    <async_capture_request>
    <redirect_url><![CDATA[http://url1.de/redirect]]></redirect_url>
    <notify_url><![CDATA[http://url1.de/notify]]></notify_url>
</async_capture_request>
</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.PAYLATER);

    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()
        .setName("Express Versand")
        .setPriceNet(840)
        .setPriceGross(1000)
        .setTrackingNumber("ABZ12398892131");
    preauthorizeRequest.getCart()
         .setOrderAmountNet(36134)
         .setOrderAmountGross(43000)
         .setCurrencyIso3("EUR")
         .setReference("1519088641")
         .setInvoiceNumber("1234567")
         .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("1234")
        .setQuantity(2)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setCategory("Clothing")
        .setFirstSubCategory("Van Laack")
        .setPriceNet(10084)
        .setPriceGross(12000);

    preauthorizeRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setCategory("Clothing")
        .setFirstSubCategory("Ralph Lauren")
        .setPriceNet(16807)
        .setPriceGross(20000);  

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

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

    //sending the request to BillPay and retrieving the response

    PreauthorizeResponse requestResponse = preauthorizeRequest.send();

    //getting data out of the response

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

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

$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_PAYLATER);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
            ->acceptTermsOfUse();

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

$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
    ->setIsExistingCustomer()
    ->setIsPrivateCustomer()
    ->setDateOfBirth('1975-10-12')
    ->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');

/* 
if the shipping address is the same as the billing address, you do not need to do anything here.  If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
    ->setSalutation('Herr')
    ->setFirstName('Thomas')
    ->setLastName('Testkunde')
    ->setStreet('Hardenberger Straße')
    ->setStreetNumber('1')
    ->setZipCode('10623')
    ->setCity('Berlin')
    ->setCountryIso3('DEU');

$preauthorizeRequest->getBankAccount()
            ->setAccountHolder('Thomas Testkunde')
            ->setAccountNumber('DE12500105170648489890')
            ->setSortCode('');    

$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
    ->setPriceGross('12000')
    ->setPriceNet('10084')
    ->setQuantity('2')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Van Laack')
    ->setId('1234');

$cart->createAndAddArticle()->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setQuantity('1')
    ->setCategory('Hose')
    ->setFirstSubCategory('Ralph Lauren')
    ->setId('2345');  

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

$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
    ->setPriceNet('1681');

$cart->setOrderAmountGross('43000')
    ->setOrderAmountNet('36134')
    ->setCurrencyIso3('EUR')
    ->addRebate($rebate); 

$payment->setRateCount('6')
    ->setRateTerm('6')
    ->setTotal('46883');

$payment->setRedirectUrl('www.redirect.de')
    ->setNotifyUrl('www.notify.de');

$preauthorizeRequest->setSessionId('session id'); 

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

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getErrorCode();
    echo $preauthorizeResponse->getMerchantMessage();
    echo $preauthorizeResponse->getDeveloperMessage();
    echo $preauthorizeResponse->getCustomerMessage();
} else {
    echo $preauthorizeResponse->getStatus();
    echo $preauthorizeResponse->getTransactionId();

    echo $preauthorizeResponse->getCustomerRestriction();

    $invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
    echo $invoiceNumber->getInvoiceId();
    echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();

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="1519088641" 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("1519088641")
        .setCurrencyIso3("EUR")
        .setOrderAmountGross(43000);

    CaptureResponse requestResponse = captureRequest.send();

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

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

        // The following is only returned if instalments is the chosen payment method
        InstalmentPlan instalmentPlan = requestResponse.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 transaction credit is the chosen payment method
        RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
        System.out.println(rateOption.getRateCount());
        System.out.println(rateOption.getTerm());
        System.out.println(rateOption.getCalculationBaseAmount());
        System.out.println(rateOption.getCartTotalGross());
        System.out.println(rateOption.getSurcharge());
        System.out.println(rateOption.getTotalPaymentAmount());
        System.out.println(rateOption.getMonthlyInterestRate());
        System.out.println(rateOption.getAnualInterestRate());
        System.out.println(rateOption.getAdditionalFee());

        DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
        System.out.println(dueDetail.getAmount());
        System.out.println(dueDetail.getDate());
        System.out.println(dueDetail.getRateType());

        // The following is only returned if you are implementing virtual credit card solution
        System.out.println(requestResponse.getCreditCard().getAccountHolder());
        System.out.println(requestResponse.getCreditCard().getCardNumber());
        System.out.println(requestResponse.getCreditCard().getSecurityCode());
        System.out.println(requestResponse.getCreditCard().getExpirationDate());
        System.out.println(requestResponse.getCreditCard().getActivationDate());
    }
}
<?php
$captureRequest = CaptureFactory::create();
$captureRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password')

$captureRequest->setReference('1519088641')
    ->setPortalId(9999)
    ->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
    ->setMerchantInvoiceNumber('1234567')
    ->getCart()
        ->setOrderAmountGross(43230)
        ->setCurrencyIso3('EUR')
    ->getCustomer()
            ->setId('123456789');     

// send the request to BillPay and retrieve the response
$captureResponse = $captureRequest->send();

// get data out of the response
if ($preauthorizeResponse->isError()) {
    echo $captureResponse->getStatus();
    echo $captureResponse->getErrorCode();
    echo $captureResponse->getMerchantMessage();
    echo $captureResponse->getDeveloperMessage();
    echo $captureResponse->getCustomerMessage();
} else {
    echo $captureResponse->getStatus();
    echo $captureResponse->getCustomerRestriction();

    $bankAccount = $captureResponse->getInvoiceBankAccount();
    echo $bankAccount->isActivationPerformed();
    echo $bankAccount->getAccountHolder();
    echo $bankAccount->getAccountNumber();
    echo $bankAccount->getBankCode();
    echo $bankAccount->getBankName();
    echo $bankAccount->getInvoiceDueDate();
    echo $bankAccount->getInvoiceReference();
    echo $bankAccount->getEsrReference();
    echo $bankAccount->getEsrCodeLine();

    $invoiceNumber = $captureResponse->getInvoiceNumbers();
    echo $invoiceNumber->getInvoiceId();
    echo $invoiceNumber->getBillpayInvoiceNumber();
}

Invoice Created: complete

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <invoice_params carttotalgross="43000" currency="EUR" reference="1519088641" deliverydelayindays="0" />
</data>
private void invoiceCreatedExample(){
    //building the request
    InvoiceCreatedRequest invoiceCreatedRequest = new InvoiceCreatedRequest();
    invoiceCreatedRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id")
        .setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
        .setMerchantInvoiceNumber("1234567");
        .setIsPartial(0)
        .setDeliveryDelayInDays(0);

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

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

    invoiceCreatedRequest.getCart()
        .setReference("1519088641")
        .setCurrencyIso3("EUR")
        .setOrderAmountGross(43000);

    InvoiceCreatedResponse invoiceCreatedResponse = invoiceCreatedRequest.send();

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

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

        // The following is only returned if instalments is the chosen payment method
        InstalmentPlan instalmentPlan = invoiceCreatedResponse.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 transaction credit is the chosen payment method
        RateOption rateOption = invoiceCreatedResponse.getInstalmentDetails().getRateOption();
        System.out.println(rateOption.getRateCount());
        System.out.println(rateOption.getTerm());
        System.out.println(rateOption.getCalculationBaseAmount());
        System.out.println(rateOption.getCartTotalGross());
        System.out.println(rateOption.getSurcharge());
        System.out.println(rateOption.getTotalPaymentAmount());
        System.out.println(rateOption.getMonthlyInterestRate());
        System.out.println(rateOption.getAnualInterestRate());
        System.out.println(rateOption.getAdditionalFee());

        DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
        System.out.println(dueDetail.getAmount());
        System.out.println(dueDetail.getDate());
        System.out.println(dueDetail.getRateType());

        // The following is only returned if you are implementing virtual credit card solution
        System.out.println(invoiceCreatedResponse.getCreditCard().getAccountHolder());
        System.out.println(invoiceCreatedResponse.getCreditCard().getCardNumber());
        System.out.println(invoiceCreatedResponse.getCreditCard().getSecurityCode());
        System.out.println(invoiceCreatedResponse.getCreditCard().getExpirationDate());
        System.out.println(invoiceCreatedResponse.getCreditCard().getActivationDate());
    }
}
<?php
$invoiceRequest = InvoiceCreatedFactory::create();
$invoiceRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');

$invoice = $invoiceRequest->getInvoice();

$invoice->setDeliveryDelayInDays(0)
    ->isPartialActivation(0)
    ->setMerchantInvoiceNumber('1234567');

$invoice->getCart()
    ->setOrderAmountGross('43000')
    ->setOrderAmountNet('19327')
    ->setCurrencyIso3('EUR');

// send the request to BillPay and retrieve the response
$invoiceResponse = $invoiceRequest->send();

// get data out of the response
echo $invoiceResponse->getErrorCode();
echo $invoiceResponse->getMerchantMessage();
echo $invoiceResponse->getDeveloperMessage();
echo $invoiceResponse->getCustomerMessage();

// The following is only returned for invoice as the payment method.

$bankAccount = $invoiceResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();

$invoiceNumber = $invoiceResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();

// The following is only returned if instalments is the chosen payment method

$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

// The following is only returned if transaction credit is the chosen payment method

$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

Invoice Created: partial

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <invoice_params carttotalgross="23000" currency="EUR" reference="1773673332" deliverydelayindays="0" is_partial="1" invoice_number="INV551202291" shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="19327" />
    <article_data>
        <article articleid="1234" articlequantity="2" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
    </article_data>
</data>
private void invoiceCreatedExample(){
    //building the request
    InvoiceCreatedRequest invoiceCreatedRequest = new InvoiceCreatedRequest();
    invoiceCreatedRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id")
        .setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
        .setMerchantInvoiceNumber("1234567");
        .setIsPartial(1)
        .setDeliveryDelayInDays(0);

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

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

    invoiceCreatedRequest.getCart()
        .setReference("1773673332")
        .setCurrencyIso3("EUR")
        .setOrderAmountGross(23000);
        .setInvoiceNumber("INV551202291")
        .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

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

    InvoiceCreatedResponse invoiceCreatedResponse = invoiceCreatedRequest.send();

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

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

        // The following is only returned if instalments is the chosen payment method
        InstalmentPlan instalmentPlan = invoiceCreatedResponse.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 transaction credit is the chosen payment method
        RateOption rateOption = invoiceCreatedResponse.getInstalmentDetails().getRateOption();
        System.out.println(rateOption.getRateCount());
        System.out.println(rateOption.getTerm());
        System.out.println(rateOption.getCalculationBaseAmount());
        System.out.println(rateOption.getCartTotalGross());
        System.out.println(rateOption.getSurcharge());
        System.out.println(rateOption.getTotalPaymentAmount());
        System.out.println(rateOption.getMonthlyInterestRate());
        System.out.println(rateOption.getAnualInterestRate());
        System.out.println(rateOption.getAdditionalFee());

        DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
        System.out.println(dueDetail.getAmount());
        System.out.println(dueDetail.getDate());
        System.out.println(dueDetail.getRateType());

        // The following is only returned if you are implementing virtual credit card solution
        System.out.println(invoiceCreatedResponse.getCreditCard().getAccountHolder());
        System.out.println(invoiceCreatedResponse.getCreditCard().getCardNumber());
        System.out.println(invoiceCreatedResponse.getCreditCard().getSecurityCode());
        System.out.println(invoiceCreatedResponse.getCreditCard().getExpirationDate());
        System.out.println(invoiceCreatedResponse.getCreditCard().getActivationDate());
    }
}
<?php
$invoiceRequest = InvoiceCreatedFactory::create();
$invoiceRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');

$invoice = $invoiceRequest->getInvoice();

$invoice->setDeliveryDelayInDays(0)
    ->isPartialActivation(1)
    ->setMerchantInvoiceNumber('INV551202291');

$invoice->getShipping()
    ->setName('shipping')
    ->setPriceGross('1000')
    ->setPriceNet('950')
    ->setTrackingNumber('ABZ12398892131');

$invoice->getCart()
    ->setOrderAmountGross('23000')
    ->setOrderAmountNet('19327')
    ->setCurrencyIso3('EUR')
    ->createAndAddRebate()
        ->setPriceGross('2000')
        ->setPriceNet('1681');

$invoiceRequest->getInvoice()->getCart()->createAndAddArticle()
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->setName('Hose')
    ->setQuantity('1')
    ->setId('2345')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Ralph Lauren');

// send the request to BillPay and retrieve the response
$invoiceResponse = $invoiceRequest->send();

// get data out of the response
echo $invoiceResponse->getErrorCode();
echo $invoiceResponse->getMerchantMessage();
echo $invoiceResponse->getDeveloperMessage();
echo $invoiceResponse->getCustomerMessage();

// The following is only returned for invoice as the payment method.

$bankAccount = $invoiceResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();

$invoiceNumber = $invoiceResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();

// The following is only returned if instalments is the chosen payment method

$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

// The following is only returned if transaction credit is the chosen payment method

$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

Cancel

<?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="1519088641" 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("1519088641")
        .setCurrencyIso3("EUR")
        .setOrderAmountGross(43000);

    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());
    }
}
<?php
$cancelRequest = CancelFactory::create();

$cancelRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password')
    ->setReference('1519088641');

$cancelRequest->getCart()
    ->setOrderAmountGross(43000)
    ->setCurrencyIso3('EUR');

// send the request to BillPay and retrieve the response
$cancelResponse = $cancelRequest->send();

// get data out of the response
echo $cancelResponse->getErrorCode();
echo $cancelResponse->getMerchantMessage();
echo $cancelResponse->getDeveloperMessage();
echo $cancelResponse->getCustomerMessage();

Edit Cart

1 unit of article “1234” was returned. The articlequantity was reduced and the orderamountnet and orderamountgross values are adjusted accordingly.

<?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="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="26050" orderamountgross="31000" currency="EUR" reference="976692924" trackingnumber="ABZ12398892131" />
    <article_data>
        <article articleid="1234" articlequantity="1" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </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("Express Versand")
        .setPriceNet(840)
        .setPriceGross(1000);

    editCartContentRequest.getCart().createAndAddArticle()
        .setId("1234")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setCategory("Clothing")
        .setFirstSubCategory("Van Laack")
        .setPriceNet(10084)
        .setPriceGross(12000);     

    editCartContentRequest.getCart().createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setCategory("Clothing")
        .setFirstSubCategory("Ralph Lauren")
        .setPriceNet(16807)
        .setPriceGross(20000);    

    editCartContentRequest.getCart()
        .setOrderAmountNet(26050)
        .setOrderAmountGross(31000)
        .setCurrencyIso3("EUR")
        .setReference("1519088641")
        .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

     EditCartContentResponse editCartContentResponse = editCartContentRequest.send();   

     if (requestResponse.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());
    }
}
<?php
$editCartContentRequest = EditCartContentFactory::create();
$editCartContentRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');

$editCartContentRequest->setReference('1519088641');

$editCartContentRequest->getShipping()
    ->setName('Express Versand')
    ->setPriceGross(1000)
    ->setPriceNet(840)
    ->setTrackingNumber('12345');

$editCartContentRequest->getCart()
    ->setOrderAmountNet('26050')
    ->setOrderAmountGross('31000')
    ->setCurrencyIso3('EUR');

$editCartContentRequest->getCart()->createAndAddRebate()
    ->setPriceGross(2000)
    ->setPriceNet(1681);                       

$editCartContentRequest->getCart()->createAndAddArticle()
        ->setId("1234")
        ->setQuantity(1)
        ->setType(ArticleType.OTHER)
        ->setName("Shirt")
        ->setCategory("Clothing")
        ->setFirstSubCategory("Van Laack")
        ->setPriceNet(10084)
        ->setPriceGross(12000);     

$editCartContentRequest->getCart()->createAndAddArticle()
        ->setId("2345")
        ->setQuantity(1)
        ->setType(ArticleType.OTHER)
        ->setName("Hose")
        ->setCategory("Clothing")
        ->setFirstSubCategory("Ralph Lauren")
        ->setPriceNet(16807)
        ->setPriceGross(20000);     

// send the request to BillPay and retrieve the response
$editCartContentResponse = $editCartContentRequest->send();

// get data out of the response
echo $editCartContentResponse->getErrorCode();
echo $editCartContentResponse->getMerchantMessage();
echo $editCartContentResponse->getDeveloperMessage();
echo $editCartContentResponse->getCustomerMessage();

$invoiceNumber = $editCartContentResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();

// The following is only returned if instalments is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

// The following is only returned if transaction credit is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

Edit Cart: partial shipment

The second partial shipment (merchantinvoicenumber 234567) was delivered containing 2 units of article 1234. 1 unit of article 1234 was returned so the articlequantity in the main order article_data as well as in the invoice_list is reduced to 1 and the orderamountnet / orderamountgross and invoiceamountnet / invoiceamountgross are adjusted accordingly in the main (article_data node) and suborder (invoice node).

<?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="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="26050" orderamountgross="31000" currency="EUR" reference="1773673332" />
    <article_data>
        <article articleid="1234" articlequantity="1" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <invoice_list>
        <invoice merchantinvoicenumber="1234567">
            <invoice_params invoiceamountnet="15966" invoiceamountgross="19000" rebatenet="1681" rebategross="2000"
 shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" currency="EUR" reference="1773673332" trackingnumber="ABZ12398892131" />
             <article_data>
                <article articleid="2345" articlequantity="1" articlename="Hose" articlepricenet="16807" articlepricegross="20000" />
            </article_data>   
        </invoice>
        <invoice merchantinvoicenumber="234567">
            <invoice_params invoiceamountnet="10084" invoiceamountgross="12000" rebatenet="0" rebategross="0"
 shippingname="Express Versand" shippingpricenet="0" shippingpricegross="0" currency="EUR" reference="1773673332" trackingnumber="ABZ13498892131" />
             <article_data>
                <article articleid="1234" articlequantity="1" articlename="Shirt" articlepricenet="10084" articlepricegross="12000" />
            </article_data>   
        </invoice>
    </invoice_list>  
</data>
private void EditCartContentPartialActivationExample() {
    //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("Express Versand")
        .setPriceNet(840)
        .setPriceGross(1000);  

    Invoice invoice1 = editCartContentRequest.createAndAddInvoice("1234567")
        .setTotalPriceNet(15966)
        .setTotalPriceGross(19000)
        .setShippingPriceNet(840)
        .setShippingPriceGross(1000)
        .setShippingName("shipping name")
        .setRebateNet(1681)
        .setRebateGross(2000);

    invoice1.createAndAddArticle()
        .setId("2345")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Hose")
        .setPriceNet(16807)
        .setPriceGross(20000);

    Invoice invoice2 = editCartContentRequest.createAndAddInvoice("234567")
        .setTotalPriceNet(10084)
        .setTotalPriceGross(12000)
        .setShippingPriceNet(0)
        .setShippingPriceGross(0)
        .setShippingName("shipping name")
        .setRebateNet(0)
        .setRebateGross(0);

    invoice2.createAndAddArticle()
        .setId("1234")
        .setQuantity(1)
        .setType(ArticleType.OTHER)
        .setName("Shirt")
        .setPriceNet(10084)
        .setPriceGross(12000); 

    editCartContentRequest.getCart()
        .setOrderAmountNet(26050)
        .setOrderAmountGross(31000)
        .setCurrencyIso3("EUR")
        .setReference("1519088641")
        .createAndAddRebate()
            .setRebateNet(1681)
            .setRebateGross(2000);

     EditCartContentResponse editCartContentResponse = editCartContentRequest.send();   

     if (requestResponse.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());
    }
}
<?php
$editCartContentRequest = EditCartContentFactory::create();
$editCartContentRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');

$editCartContentRequest->setReference('1519088641');

$editCartContentRequest->getShipping()
    ->setName('Express Versand')
    ->setPriceGross(1000)
    ->setPriceNet(840)
    ->setTrackingNumber('12345');

$editCartContentRequest->getCart()
    ->setOrderAmountNet('26050')
    ->setOrderAmountGross('31000')
    ->setCurrencyIso3('EUR');

$editCartContentRequest->getCart()->createAndAddRebate()
    ->setPriceGross(2000)
    ->setPriceNet(1681); 

$editCartContentRequest->getCart()->createAndAddArticle()
        ->setId("1234")
        ->setQuantity(1)
        ->setType(ArticleType.OTHER)
        ->setName("Shirt")
        ->setCategory("Clothing")
        ->setFirstSubCategory("Van Laack")
        ->setPriceNet(10084)
        ->setPriceGross(12000);                          

$editCartContentRequest->getCart()->createAndAddArticle()
    ->setId(2345)
    ->setQuantity(1)
    ->setName('Hose')
    ->setCategory('Clothing')
    ->setFirstSubCategory('Ralph Lauren')
    ->setPriceGross('16807')
    ->setPriceNet('20000');

$invoice1 = $editCartContentRequest->createAndAddInvoice()
    ->setMerchantInvoiceNumber('1234567');

$invoice1->getCart()
    ->setOrderAmountNet('15966')
    ->setOrderAmountGross('19000')
    ->setCurrencyIso3('EUR');

$invoice1->getShipping()
    ->setName('shipping name')
    ->setPriceGross('1000')
    ->setPriceNet('840')
    ->setTrackingNumber('ABZ12398892131');

$invoice1->getCart()->createAndAddArticle()
    ->setId(2345)
    ->setQuantity(1)
    ->setName('Hose')
    ->setPriceGross('20000')
    ->setPriceNet('16807')
    ->appendTo($editCartContentRequest->getCart()); // append to ecc request cart as well

$invoice1->getCart()->createRebate()
    ->setPriceGross(2000)
    ->setPriceNet(1681)
    ->appendTo($invoice1->getCart()); 

$invoice2 = $editCartContentRequest->createAndAddInvoice()
    ->setMerchantInvoiceNumber('234567');

$invoice2->getCart()
    ->setOrderAmountNet('15966')
    ->setOrderAmountGross('19000')
    ->setCurrencyIso3('EUR');

$invoice2->getShipping()
    ->setName('shipping name')
    ->setPriceGross('1000')
    ->setPriceNet('840')
    ->setTrackingNumber('ABZ12398892131');

$invoice2->getCart()->createAndAddArticle()
    ->setId(1234)
    ->setQuantity(1)
    ->setName('Shirt')
    ->setPriceGross('10084')
    ->setPriceNet('12000')
    ->appendTo($editCartContentRequest->getCart()); // append to ecc request cart as well


// send the request to BillPay and retrieve the response
$editCartContentResponse = $editCartContentRequest->send();

// get data out of the response
echo $editCartContentResponse->getErrorCode();
echo $editCartContentResponse->getMerchantMessage();
echo $editCartContentResponse->getDeveloperMessage();
echo $editCartContentResponse->getCustomerMessage();

$invoiceNumber = $editCartContentResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();

// The following is only returned if instalments is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

// The following is only returned if transaction credit is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();

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

Update Order

<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="UPDATE_ORDER" apiversion="2.0.0">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <update_params transactionid="b61648a3-46a1-4771-834f-903b89510ed9" reference="1591605922_updated" />
    <id_update_list>
        <id_update articleid="1234" updateid="1234_mod" />
        <id_update articleid="2345" updateid="2345_mod" />
    </id_update_list>
</data>
private void updateOrderExample() {
    //building the request
    UpdateOrderRequest updateOrderRequest = new UpdateOrderRequest();
    updateOrderRequest
        .setMerchantId(1234)
        .setPortalId(9999)
        .setApiPassword("clear text password")
        .setSessionId("clear text session id");

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

    updateOrderRequest.setReference("1591605922_updated");
    updateOrderRequest.setTransactionId("b61648a3-46a1-4771-834f-903b89510ed9");
    updateOrderRequest.createAndAddUpdateOrder()
        .setNewId("1234")
        .setOldId("1234_mod");
    updateOrderRequest.createAndAddUpdateOrder()
        .setNewId("2345")
        .setOldId("2345_mod");    

    UpdateOrderResponse requestResponse = updateOrderRequest.send();

     if (requestResponse.hasError()) {
        System.out.println(requestResponse.getErrorCode());
        System.out.println(requestResponse.getMerchantMessage());
        System.out.println(requestResponse.getDeveloperMessage());
        System.out.println(requestResponse.getCustomerMessage());
    } 
}
<?php
$updateOrderRequest = UpdateOrderFactory::create();
$updateOrderRequest
    ->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password');

$updateOrderRequest
    ->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
    ->setReference('1591605922_updated');

$updateOrderRequest->getCart()->createAndAddArticleUpdate()
    ->setId('1234')
    ->setNewId('1234_mod');

$updateOrderRequest->getCart()->createAndAddArticleUpdate()
    ->setId('2345')
    ->setNewId('2345_mod');

// send the request to BillPay and retrieve the response
$updateOrderResponse = $updateOrderRequest->send();

// get data out of the response
echo $updateOrderResponse->getErrorCode();
echo $updateOrderResponse->getMerchantMessage();
echo $updateOrderResponse->getDeveloperMessage();
echo $updateOrderResponse->getCustomerMessage();

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="1519088641" />
</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("1519088641");

    GetBillPayBankDataResponse requestResponse = getBillPayBankDataRequest.send();

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

        DueDate dueDate = requestResponse.getDueDates().get(0);
        System.out.println(dueDate.getDuedate());
        System.out.println(dueDate.getInvoiceid());
    }
}
<?php
$bankDataRequest = GetBillPayBankDataFactory::create();
$bankDataRequest->setMerchantId(1234)
    ->setPortalId(9999)
    ->setApiPassword('clear text password')
    ->setReference('1519088641');

// send the request to BillPay and retrieve the response
$bankDataResponse = $bankDataRequest->send();

// get data out of the response
echo $bankDataResponse->getErrorCode();
echo $bankDataResponse->getMerchantMessage();
echo $bankDataResponse->getDeveloperMessage();
echo $bankDataResponse->getCustomerMessage();

$bankAccount = $bankDataResponse->getInvoiceBankAccount();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();

$dueDate = $bankDataResponse->getDueDates();
echo $dueDate->getDuedate();
echo $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

API Value Label Displayed Germany Austria Switzerland
ag (Aktiengesellschaft) x x x
ag_co_kg AG & Co KG x x
e_ges einfache Gesellschaft x
eg (eingetragene Genossenschaft) x x x
eu eingetragener Einzelunternehmer x
ek (eingetragener Kaufmann) x x
ev e.V. (eingetragener Verein) x x x
einzel Einzelfirma x x
ewiv Europäische wirtschaftliche Interessenvereinigung x x
freelancer Freiberufler/Kleingewerbetreibender/Handelsvertreter x x x
foundation Stiftung x x x
gbr GbR/BGB (Gesellschaft bürgerlichen Rechts) x x
gmbh GmbH (Gesellschaft mit beschränkter Haftung) x x x
gmbh_ig GmbH in Gründung x
gmbh_co_kg GmbH & Co. KG x x
inv_kk Investmentgesellschaft für kollektive Kapitalanlagen x
kg (Kommanditgesellschaft) x x x
kgaa Kommanditgesellschaft auf Aktien x x
k_ges Kollektivgesellschaft x
ltd Limited x x
ltd_co_kg Limited & Co. KG x x
misc sonstige Personengesellschaft x x x
misc_capital sonstige Kapitalgesellschaft x x x
og offene Gesellschaft x
ohg OHG (offene Handelsgesellschaft) x x
public_inst öffentliche Einrichtung x x x
ug UG (Unternehmensgesellschaft haftungsbeschränkt) x x

When is the field “registerNumber and "holderName” mandatory?

API Value registernumber holdername
DEU AUT CHE DEU AUT CHE
ag x x x
ag_co_kg x x
eg x
einzel x
ek x
e_ges x
eu x
foundation x
freelancer x x x
gbr x x
gmbh x x x
gmbh_co_kg x x
kg x x x
kgaa x
k_ges x
ltd x
ltd_co_kg x
ohg x x
ug x

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:

  • PDF
  • CSV

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.