For developers

introduction

XML API

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 itself will consist of an error code, as well as a message to be displayed in the frontend (“customer message”) and a message to be logged by the merchant (“merchant 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 problem with the transaction.

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

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

Reserved Character	Escape Sequence
&	&
“	"
’	'
<	&lt;
>	&gt;

Webservice URL

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

Base URLs

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

Overview: Frontend XMLs service requests

classical scoring

XML service	Meaning	Time of execution	Service URL	Required	Back Office	Response
Authorization	An identity and credit check will be performed	During the checkout process; after the customer has selected the payment method	[Base-URL]/preauthorize	Y	N	Status of the credit check ("APPROVED” / “DENIED”) and the normalized customer address

Prescoring

XML service	Meaning	Time of execution	Service URL	Required	Back Office	Response
Prescoring	An identity and credit check will be performed	During the checkout process; before the customer has selected the payment method	[Base-URL]/prescore	Y	N	All authorized payment methods for this customer
Authorization (auto capture mode)	Creation of the order in the BillPay system	After finishing the checkout process	[Base-URL]/preauthorize	Y	N	Error code and message

Overview: Backend XML service requests

XML service	Meaning	Time of execution	Service URL	Required	Back Office	Response
Activation	Invoice: Setting of the payment due date (20 / 30 days); 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	Y	Y	Invoice: BillPay bank account data and payment due date; Direct Debit/PayLater: -
Cancellation	A full cancellation of the existing debt.	Usually this action is triggered by a backend workflow or scheduled task/cron job.	[Base-URL]/cancel	N	Y	-
Editing the Cart	Any change in the content of the existing cart or the included fees/rebates of the order.	Usually is triggered when items were returned by the customer or the order has been adjusted before shipping.	[Base-URL]/editCartContent	N	N	-
Update Order	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	N	N	-
Get Bank Details	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	N	N	BillPay bank account and payment due date for the invoice.
Report of a direct customer payment	Only invoice: the merchant reports a direct payment made by the customer to his/her account.	From the backend, after accounting has discovered that there has been a direct transfer of funds to the merchant bank account.	[Basis-URL]/reportCustomerPayment	N	Y	-

JavaScript-Widget

introduction: The BillPay JavaScript Widget

The core of all shop integrations is the BillPay JavaScript widget which will display all payment methods in a conversion optimized and standardized fashion. This way, the BillPay brand can be recognized throughout various shops and customers will trust the payment method.

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 of The JavaScript Widget

Step 1: Loading the JavaScript

In order to use the BillPay JavaScript widget, the following snippet needs to be included in the shop template:

<!-- Initialization & Configuration -->
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');

The function billpayCheckout is now available to use.

Step 2:Configuration

In order to configure the JavaScript widget the billpayCheckout function is called and given the first parameter “options” and a JSON object containing customer and shop information as the second parameter.

billpayCheckout('options', {
    "checkout": {"form": "#payment_form"},
    "shop": {
        "apiKey": "710290a938e6b4770000005552",
        "live": false
    },
    "order": {
        "cartAmount": 161.94, // Total cart value without shipping or additional fees
        "orderAmount": 166.94, // Total cart 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", // TThe 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 lagugage 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]"
            }
        }
    }
});

Variable	Explanation
checkout.form	jQuery selector for the checkout from HTML element
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 shopping cart (Just 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	ISO 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	ISO Code of the customer address country
customer.billing.countryIso3	ISO Code of the customer address country
customer.billing.dayOfBirth	Customer’s date of birth
customer.language	Language of the customer
customer.identifier	Unique token used for fraud prevention (e.g. hash of session ID)
customer.customerGroup	“private” for B2C Customers oder “business” für 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 or 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

Finally, the function billpayCheckout is called with the argument “run”. A second argument can be passed that contains a JSON object which defines the container for the BillPay payment methods that will be displayed.

billpayCheckout('run', {"container": ".bpy-checkout-container"});

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

Step 4: Validating the widget on submit

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

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

Full Example of The Widget Implementation

<!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', {
        "checkout": {"form": "#payment_form"},
        "shop": {
            "apiKey": "710290a938e6b4770000005552",
            "live": false
        },
        "order": {
            "cartAmount": 161.94, // Total cart value without shipping or additional fees
            "orderAmount": 166.94, // Total cart 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": "Dieter", // 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", // TThe 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>

XML API

Generic Parameters

Generic parameter for all XML requests

Some parameters are required in all XML requests no matter what endpoint is addressed. (e.g. the merchant credentials to authorize the requests)

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

Request

XML Header

<?xml version="1.0" encoding="UTF-8"?>
<data apiversion="2">
    <default_params mid="2" pid="3" passwordhash="0d48732f425b6df88c58244d6882369e" />
    <!-- additional request specific data -->
</data>

<?php
$request
    ->setMerchantId(2)
    ->setPortalId(3)
    ->setApiPassword('some password');

Response

Generic Parameter for all XML responses

The following parameters are returned with every XML service response:

Attribute	Required	Format	Info
errorcode	+	non-negative integer	Numerical error code - the standard value is “0” (no error)
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

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

<?xml version="1.0" encoding="UTF-8"?>
<data apiversion="2" 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." errorcode="32">
    <!-- additional request specific data -->
</data>

Prescore

Using Billpay Payment Method Pre-scoring, merchants can filter the payment options shown to each customer before they are displayed. This helps to prevent the end user from being presented a negative alert message, enabling 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.

Only one scoring method, pre- or post-selection of the payment method, can be used at a time.

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

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data
        requesttype="PRESCORE"
        apiversion="2"
        originofsale="o">
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	PRESCORE	Type of request
apiversion	int	2	BillPay API Version
originofsale	string	u: unknown o: online shop p: offline / pos t: telesales / call center	identifier for the point of origin of the purchase.

Default Params Node (Merchant Credentials)

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

Customer Details Node (customer billing address)

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

Attribute	Required	Format	Values	Info
customerid	-	string	AN.40	Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/)
customertype	-	string	g: Guest, e: Existing Customer, n: New Customer	Type of customer
salutation	+	string	Default: See addendum Saluations	Salutation
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	ISO3166 (aplha-3)	Customer country code (e.g. “DEU”)
email	+	string	AN..40 (excl. non-valid special characters)	Email address
phone	-*	string	AN..40	Phone number
cellphone	-	string	AN..40	Mobile number
dateofbirth	-*	string	YYYYMMDD	Date of Birth - optional for business customers
language	+	string	ISO639-1 (aplha-2)	Customer language (e.g. “de”)
ipaddress	+	string	IPv4 & IPv6	IP address of the client
customergroup	+	string	p: Private, b: Business	customer group

phone is mandatory when the country is NLD.

dateofbirth is a mandatory field for private customers (customergroup = “p”)

Shipping Details Node (customer shipping address)

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

*All fields for the alternate shipping address only need to be populated if the parmater usebillingaddress is set to “0”

*see addendum defaults for business customers

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

Attribute	Required	Format	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 Saluations	Salutation
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	ISO3166 (aplha-3)	Customer country code (e.g. “DEU”)
phone	-	string	AN..40	Phone number
cellphone	-	string	AN..40	Mobile number

Company Details Node (Details about business customers)

In case you are shipping to business customers (`customertype´ = “b”), additional information needs to be collected about the business.

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

Attribute	Required	Format	Values	Info
name	+	string	AN..200	Registered name of the company
legalform	+	string	Defaults: see addendum legal forms	Company legal form
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 ordered articles) All information concerning 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"
            articlename="Shirt"
            articlecategory="Clothing"
            articlesubcategory1="Van Laack"
            articlepricenet="10084"
            articlepricegross="12000" />
    <article
            articleid="2345"
            articlequantity="1"
            articlename="Hose"
            articlecategory="Clothing"
            articlesubcategory1="Ralph Lauren"
            articlepricenet="16807"
            articlepricegross="20000" />
</article_data>

Attribute	Required	Format	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)
articlecategory	-	string	AN..50	Article Category
articlecategory1	-	string	AN..50	Article Sub-Category
articlecategory2	-	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"
        reference="123456"
        trackingnumber="ABZ12398892131"
        />

Attribute	Required	Format	Values	Info
shippingname	+	string	AN..50	Shipping method name (e.g. “Express”)
shippingpricenet	+	non-negative int	N..7	net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross	+	non-negative int	N..7	gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
rebatenet	+	non-negative int	N..7	positive net value 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 of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
orderamountnet	+	positive int	N..7	net value of the order total (1,00 EUR = 100)
orderamountgross	+	positive int	N..7	gross value of the order total (1,00 EUR = 100)
currency	+	string	ISO4217	3-digit currency code of the order (e.g. “EUR”)
reference	-	string	AN..40	([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"/>

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

Full XML example

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PRESCORE" apiversion="2" originofsale="o">
    <trace trace_id="5efba73acc901f0414e66bcc74953869bcb68dba" />
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="36134" orderamountgross="43000" currency="EUR" reference="123456" trackingnumber="ABZ12398892131" />
    <article_data>
        <article articleid="1234" articlequantity="2" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Response

** Data Node (Result of the identity and credit check) **

The data node contains all relevant information about the scoring result. In addition to the plain text 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="PRESCORE"
        errorcode="0"
        customermessage=""
        merchantmessage=""
        status="APPROVED"
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337">
    <!-- weitere Antwortdaten -->
</data>

Attribute	Required	Format	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
status	-	string	“APPROVED” / “DENIED”	Status of the identity and credit check
transactionid	-	string	AN..50	Unique BillPay transaction ID

Corrected Address Node (Optional: Normalized customer address)

This node returns the normalized customer address.

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

Attribute	Required	Format	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	ISO3166 (alpha-3)	Normalized country code (e.g. “DEU”)

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. This is a matter that is discussed during the sales process and may be required for your project, depending upon your product segment and other specifics that relate to your integration.

<customer_restriction
        shippingtypeobligation="IDENTITY_SHIPPING" />    

**Attribute** | **Required** | **Format** | **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.

```xml
<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>
    </payment_method>
</allowed_methods>

Attribute	Required	Format	Values	Info
name	+	string	AN..50	Account holder
customer_group	+	string	“p”: private customer (B2C), “b”: business customer (B2B)	Customer group
payment_type	+	string	1: Invoice, 2: Direct Debit, 3: Transaction Credit, 4: PayLater	ID of chosen payment method

Preauthorize

The preauthorization 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.

In the case of a positive authorization, the order will be created in the BillPay system based upon the unique ID sent in the parameter “reference”. From a legal viewpoint, this is the moment BillPay acquires the debt for this specific customer and order.

Request

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data
        requesttype="PREAUTHORIZE"
        tcaccepted="1"
        expecteddaystillshipping="0"
        manualcapture="0"
        paymenttype="1"
        apiversion="2"
        originofsale="o">
    <!-- Request Daten -->
</data>

Attribute	Required	Format	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		Payment Type 7, 8 and 9: Amount of days until the customer will depart for their trip.
manualcapture	+	bool	0/1	Boolean flag that indicates if the preauthorization is done in manualcapture (flag set to “0”) mode or if a capture request is required (1).
paymenttype	+	int	7: PayLater Collateral Promise 8: Invoice Collateral Promise 9: Direct Debit Collateral Promise	Id of the desired payment method
apiversion	+	int	2	BillPay API Version
originofsale	+	string	u: unknown o: online shop p: offline / pos t: telesales / call center	identifier for the point of origin of the purchase.

Default Params Node - merchant credentials

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

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" />

Parameters specific to the Payment Method Pre-scoring	Required	Format	Values	details
isprescored	+	bool	0/1	Value indicates if a prescore request was sent previously. Please note: If the Payment Method Pre-scoring is activated, the value “1” has to be sent.
transactionid	+	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 - the customer’s billing address

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

Attribute	Required	Format	Values	Info
customerid	-	string	AN.40	Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/)
customertype	-	string	g: Guest, e: Existing Customer, n: New Customer	Type of customer
salutation	+	string	Default: See addendum Saluations	Salutation
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	ISO3166 (aplha-3)	Customer country code (e.g. “DEU”)
email	+	string	AN..40 (excl. non-valid special characters)	Email address
phone	-*	string	AN..40	Phone number
cellphone	-	string	AN..40	Mobile number
dateofbirth	-*	string	YYYYMMDD	Date of Birth - optional for business customers
language	+	string	ISO639-1 (aplha-2)	Customer language (e.g. “de”)
ipaddress	+	string	IPv4 & IPv6	IP address of the client
customergroup	+	string	p: Private, b: Business	customer group

phone is mandatory when the country is NLD.

dateofbirth is a mandatory field for private customers (customergroup = “p”)

Shipping Details Node (customer shipping address)

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

*All fields for the alternate shipping address only need to be populated if the parmater usebillingaddress is set to “0”

*see addendum defaults for business customers

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

Attribute	Required	Format	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 Saluations	Salutation
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	ISO3166 (aplha-3)	Customer country code (e.g. “DEU”)
phone	-	string	AN..40	Phone number
cellphone	-	string	AN..40	Mobile number

Company Details Node

In case you are shipping to business customers (`customertype´ = “b”), additional information needs to be collected about the business.

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

Attribute	Required	Format	Values	Info
name	+	string	AN..200	Registered name of the company
legalform	+	string	Defaults: see addendum legal forms	Company legal form
registernumber	-	string	AN..20	Company register number
holdername	-	string	AN..100 (if entered string length needs to be >= 5	Owner’s full name
taxnumber	-	string	valid tax ID (DEXXXXXXXXX)

Article Data Node - list of all ordered articles All information concerning 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"
            articlename="Shirt"
            articlecategory="Clothing"
            articlesubcategory1="Van Laack"
            articlepricenet="10084"
            articlepricegross="12000" />
    <article
            articleid="2345"
            articlequantity="1"
            articlename="Hose"
            articlecategory="Clothing"
            articlesubcategory1="Ralph Lauren"
            articlepricenet="16807"
            articlepricegross="20000" />
</article_data>

Attribute	Required	Format	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)
articlecategory	-	string	AN..50	Article Category
articlecategory1	-	string	AN..50	Article Sub-Category
articlecategory2	-	string	AN..50	Article Sub-Category

Bank Account Node - customer bank info

The bank account data is only processed in case direct debit or PayLater - transaction credit payment is selected. This is the case if parameter „paymenttype“ has values “2”, “3”, “4”. Otherwise the bank data is ignored.

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

Attribute	Required	Format	Values	Info
accountholder	+ (if paymentType in {2,3,4})	string	AN..100	First and Lastname of account holder
accountnumber	+ (if paymentType in {2,3,4})	int	AN..30	international Bank Account Number
sortcode	+ (if paymentType in {2,3,4}) AND LAND NOT DE	int	AN..11	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="123456"
        merchantinvoicenumber="1234567"
        trackingnumber="ABZ12398892131" />

Attribute	Required	Format	Values	Info
shippingname	+	string	AN..50	Shipping method name (e.g. “Express”)
shippingpricenet	+	non-negative int	N..7	net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross	+	non-negative int	N..7	gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
rebatenet	+	non-negative int	N..7	positive net value 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 of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
orderamountnet	+	positive int	N..7	net value of the order total (1,00 EUR = 100)
orderamountgross	+	positive int	N..7	gross value of the order total (1,00 EUR = 100)
currency	+	string	ISO4217	3-digit currency code of the order (e.g. “EUR”)
reference	-	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_)*
merchantinvoicenumber	-	string	AN..40	([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"/>

Attribute	Required	Format	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=“3” / paymenttype=“4” / paymenttype=“7”) some additional parameters have to be passed to the BillPay system. These additional parameters describe the installment 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 in our widget and proceeds through your checkout.

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

Attribute	Required	Format	Values	Info
ratecount	+	int	N..2	Count of installments to be paid during the term
terminmonths	+*	int	N..2	Term of the installment plan
totalamountgross	+	positive int	N..7	Total amount of the installments plan including the transaction credit interest / PayLater fee

Async Capture Request Node - for our prepayment process

For the payment methods PayLater and Transaction Credit, BillPay offers a unique “prepayment” feature, which lets customers pay a small percentage of the order total upfront (via the Giropay online banking gateway) and increase their credit score for the authorization request.

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>

Attribute	Required	Format	Values	Info
redirect_url	+	string	AN	Shop-sided result page after successful / failed prepayment.
notify_url	+	string	AN	Shop-sided webservice URL for async BillPay response.

->Sample Requests

Sample XML: Invoice B2C

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Sample XML: Invoice B2B

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Sample XML: Direct Debit

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="2" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" 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>

Sample XML: PayLater/Transaction Credit

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="4" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <rate_request ratecount="6" terminmonths="6" totalamountgross="45520" />
    <bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
    <async_capture_request>
        <redirect_url><![CDATA[http://url1.de/redirect]]></redirect_url>
        <notify_url><![CDATA[http://url1.de/notify]]></notify_url>
    </async_capture_request>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Preauthorize Response

Data Node (Result of the identity and credit check)

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=""
        status="APPROVED"
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337">
    <!-- weitere Antwortdaten -->
</data>

Attribute	Required	Format	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
status	-	string	“APPROVED” / “DENIED”	Status of the identity and credit check
transactionid	-	string	AN..50	Unique BillPay transaction ID

Corrected Address Node (Optional: Normalized customer address)

This node returns the normalized customer address.

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

Attribute	Required	Format	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	ISO3166 (alpha-3)	Normalized country code (e.g. “DEU”)

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. This is a matter that is discussed during the sales process and may be required for your project, depending upon your product segment and other specifics that relate to your integration.

<customer_restriction
        shippingtypeobligation="DHL Ident Verfahren"/>    <-- fix this with an example

Attribute	Required	Format	Values	Info
shippingtypeobligation	-	string	AN..50	shipping method restrictions

Invoice Bank Account Node (only “Invoice” & “Transaction Credit CHE”, if manualcapture = “0”)

This node returns the BillPay bank account data to be used by the customer when paying for the order he/she placed. This information should be parsed and printed on the invoice document the customers receive with their package.

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

Attribute	Required	Format	Values	Info
accountholder	+	string	AN..255	Account holder
accountnumber	+	string	AN..40	BillPay IBAN
activationperformed	+	bool	0/1	Is the order activated (payment due date set)
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.

<invoice_numbers>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="Z2I8EB#1" />
</invoice_numbers>        

Attribute	Required	Format	Values	Info
invoice_number	+	Child node of the invoice_numbers node
-> invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
-> billpayinvoicenumber	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_|#|:|.)*

Instalment Details Node (only for PayLater and Transaction Credit)

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

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

Attribute	Required	Format	Values	Info
option	+	parent node - this node only appears for PM3 (Transaction Credit)
ratecount	+	positive int	N	Number of installments
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 surchage 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	Gross value of this rate (Smallest currency unit! E.g. 100,00 Euro = 10000)
—> date	+	DATE	YYYYMMDD	Due date of the installment
—> type	+	string	AN	Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)
instl_plan	+	parent node - this node only appears for PM4 (PayLater)
numinst	+	positive int	N	Number of installments
calc	+	child node of the instl_plan node
-> duration_in_months	+	int	N	Duration of the payment plan in months
-> fee_percent	+	decimal (between 0 and 100.0)	N	PayLater fee (%)
-> 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 (between 0 and 100.0)	N	Annual effective interest rate (%)
-> nominal	+	decimal (between 0 and 100.0)	N	Annual nominal interest rate (%)
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 installment
—> type	+	string	AN	Type of Installment („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>        

Attribute	Required	Format	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 returns the necessary information to display your shop visitors who’s 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>        

Attribute	Required	Format	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

Capture Request

The “Capture” request is used to complete a purchase when a two-step capture process is being implemented and the capturerequestnecessary 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.

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data 
    requesttype="CAPTURE" 
    apiversion="2">
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	CAPTURE	Type of request
apiversion	int	2	BillPay API Version

Default Params Node (Merchant Credentials)

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

capture_params node

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

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

Attribute	Required	Format	Values	Info
transactionid	+	string	AN..50	Unique BillPay transaction ID for this order
orderamountgross	+	positive int	N..7	gross value of the order total (1,00 EUR = 100)
currency	+	string	ISO4217	3-digit currency code of the order (e.g. “EUR”)
reference	-	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_)*
merchantinvoicenumber	-	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_|#|:|.)*
customerid	-	string	AN.40	Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/)

Full XML example

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

Capture Response

With the “Capture” response, you can determine whether or not the order has been successfully completed 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="">
</data>

Attribute	Required	Format	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

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. This is a matter that is discussed during the sales process and may be required for your project, depending upon your product segment and other specifics that relate to your integration.

<customer_restriction
        shippingtypeobligation="DHL Ident Verfahren"/>    <-- fix this with an example

Attribute	Required	Format	Values	Info
shippingtypeobligation	-	string	AN..50	shipping method restrictions

Invoice Bank Account Node (only for “Invoice” & “Transaction Credit CHE”)

This node returns the BillPay bank account data to be used by the customer when paying for the order he/she placed. This information should be parsed and printed on the invoice document the customers receive with their package.

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

Attribute	Required	Format	Values	Info
accountholder	+	string	AN..255	Account holder
accountnumber	+	string	AN..40	BillPay IBAN
activationperformed	+	bool	0/1	Is the order activated (payment due date set)
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.

<invoice_numbers>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="Z2I8EB#1" />
</invoice_numbers>        

Attribute	Required	Format	Values	Info
invoice_number	+	Child node of the invoice_numbers node
-> invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
-> billpayinvoicenumber	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_|#|:|.)*

Instalment Details Node (only for PayLater and Transaction Credit)

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

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

Attribute	Required	Format	Values	Info
option	+	parent node - this node only appears for PM3 (Transaction Credit)
ratecount	+	positive int	N	Number of installments
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 surchage 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	Gross value of this rate (Smallest currency unit! E.g. 100,00 Euro = 10000)
—> date	+	DATE	YYYYMMDD	Due date of the installment
—> type	+	string	AN	Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)
instl_plan	+	parent node - this node only appears for PM4 (PayLater)
numinst	+	positive int	N	Number of installments
calc	+	child node of the instl_plan node
-> duration_in_months	+	int	N	Duration of the payment plan in months
-> fee_percent	+	decimal (between 0 and 100.0)	N	PayLater fee (%)
-> 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 (between 0 and 100.0)	N	Annual effective interest rate (%)
-> nominal	+	decimal (between 0 and 100.0)	N	Annual nominal interest rate (%)
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 installment
—> type	+	string	AN	Type of Installment („immediate“, „first“, „date“, „fee“)

InvoiceCreated

InvoiceCreated Request

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.

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data
        requesttype="INVOICE_CREATED"
        apiversion="2">
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	INVOICE_CREATED	Type of request
apiversion	int	2	BillPay API Version

Default Params Node (Merchant Credentials)

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

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" 
    delayindays="0" 
    merchantinvoicenumber="1234567"
    trackingnumber="ABZ12398892131" />

Attribute	Required	Format	Possible values	Info
invoiceamountnet	-	positive int	N..7	net value of the order total (1,00 EUR = 100)
invoiceamountgross	+	positive int	N..7	gross value 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 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 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 of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross	-	non-negative int	N..7	gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
currency	+	string	ISO4217	3-digit currency code of the order (e.g. “EUR”)
reference	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_)*
merchantinvoicenumber	-	string	AN..40	([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>

Attribute	Required	Format	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

<invoice_params
        invoiceamountnet="19327"
        invoiceamountgross="23000"
        is_partial="1" 
        rebatenet="1681" 
        rebategross="2000"
        shippingname="Express Versand" 
        shippingpricenet="840" 
        shippingpricegross="1000" 
        currency="EUR" 
        reference="1773673332" 
        delayindays="0" 
        merchantinvoicenumber="1234567" />

Full XML example (activation of full cart)

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <invoice_params carttotalgross="43000" currency="EUR" reference="1773673332" delayindays="0" />
</data>

Full XML example (partial activation of article #1234)

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <invoice_params carttotalgross="23000" currency="EUR" reference="1773673332" delayindays="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>

InvoiceCreated 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 more static text (as seen in the invoice examples in the section “Downloads”) can be printed on the document.

Data Node (Result of the identity and credit check)

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

Attribute	Required	Format	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
status	-	string	“APPROVED” / “DENIED”	Status of the identity and credit check

Invoice Bank Account Node (only “Invoice” & “Transaction Credit CHE”)

This node returns the BillPay bank account data to be used by the customer when paying for the order he/she placed. This information should be parsed and printed on the invoice document the customers receive with their package.

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

Attribute	Required	Format	Values	Info
accountholder	+	string	AN..255	Account holder
accountnumber	+	string	AN..40	BillPay IBAN
activationperformed	+	bool	0/1	Is the order activated (payment due date set)
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.

<invoice_numbers>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="Z2I8EB#1" />
</invoice_numbers>        

Attribute	Required	Format	Values	Info
invoice_number	+	Child node of the invoice_numbers node
-> invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
-> billpayinvoicenumber	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_|#|:|.)*

Instalment Details Node (only for PayLater and Transaction Credit)

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

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

Attribute	Required	Format	Values	Info
option	+	parent node - this node only appears for PM3 (Transaction Credit)
ratecount	+	positive int	N	Number of installments
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 surchage 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	Gross value of this rate (Smallest currency unit! E.g. 100,00 Euro = 10000)
—> date	+	DATE	YYYYMMDD	Due date of the installment
—> type	+	string	AN	Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)
instl_plan	+	parent node - this node only appears for PM4 (PayLater)
numinst	+	positive int	N	Number of installments
calc	+	child node of the instl_plan node
-> duration_in_months	+	int	N	Duration of the payment plan in months
-> fee_percent	+	decimal (between 0 and 100.0)	N	PayLater fee (%)
-> 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 (between 0 and 100.0)	N	Annual effective interest rate (%)
-> nominal	+	decimal (between 0 and 100.0)	N	Annual nominal interest rate (%)
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 installment
—> type	+	string	AN	Type of Installment („immediate“, „first“, „date“, „fee“)

Cancel

Cancellation Request

Using the “Cancel” request, an existing order can be fully cancelled and the debt in will be closed. If the customer has already transferred money or the customer’s account was already debited, the funds will be returned and a notification email will be sent to the customer.

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data
        requesttype="CANCEL"
        apiversion="2">
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	CANCEL	Type of request
apiversion	int	2	BillPay API Version

Default Params Node (Merchant Credentials)

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

Cancel params node

<cancel_params
        reference="1773673332"
        orderamountgross="43000"
        currency="EUR" />

Attribute	Required	Format	Values	Info
reference	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_)*
orderamountgross	+	positive int	N..7	gross value of the order total (1,00 EUR = 100)
currency	+	string	ISO4217	3-digit currency code of the order (e.g. “EUR”)

Full XML example

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

Cancellation 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="">
</data>

Attribute	Required	Format	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

Edit Cart Content

EditCartContent request

Using the “EditCartContent” request, the content of an order can be adjusted (before or after the activation of the debt). Using this call, articles can be removed, fees reduced or increased.

Adding articles or increasing fees has to follow certain predefined rules:

• If the new cart value is lower than the old one, the edit will always succeed.
• If the new cart value is higher than the old one, BillPay will perform another risk check for the customer with the new value. If this check is successful, the edit will succeed. If the result is negative, the cart value will not be increased.

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

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data
        requesttype="EDIT_CART_CONTENT"
        apiversion="2"
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	EDIT_CART_CONTENT	Type of request
apiversion	int	2	BillPay API Version

Default Params Node - merchant credentials

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

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="26050"
        orderamountgross="31000"
        currency="EUR"
        reference="976692924" />

Attribute	Required	Format	Values	Info
shippingname	+	string	AN..50	Shipping method name (e.g. “Express”)
shippingpricenet	+	non-negative int	N..7	net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross	+	non-negative int	N..7	gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
rebatenet	+	non-negative int	N..7	positive net value 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 of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
orderamountnet	+	positive int	N..7	net value of the order total (1,00 EUR = 100)
orderamountgross	+	positive int	N..7	gross value of the order total (1,00 EUR = 100)
currency	+	string	ISO4217	3-digit currency code of the order (e.g. “EUR”)
reference	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_)*
trackingnumber	-	string	AN..40	Tracking ID for this order shipment (if not partially activated)

Article Data Node (List of all ordered articles)

All information concerning the pruchased 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"
            articlename="Hose"
            articlecategory="Clothing"
            articlesubcategory1="Ralph Lauren"
            articlepricenet="16807"
            articlepricegross="20000" />
</article_data>

Attribute	Required	Format	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)

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. (see examples below)

Invoice List Node

<invoice_list>
    <invoice merchantinvoicenumber="1234567">
        <invoice_params
            invoiceamountnet="19327"
            invoiceamountgross="23000"
            is_partial="1" 
            rebatenet="1681" 
            rebategross="2000"
            shippingname="Express Versand" 
            shippingpricenet="840" 
            shippingpricegross="1000" 
            currency="EUR" 
            reference="1773673332" 
            delayindays="0" 
            trackingnumber="ABZ12398892131" />
         <article_data>
            <article
                    articleid="2345"
                    articlequantity="1"
                    articlename="Hose"
                    articlecategory="Clothing"
                    articlesubcategory1="Ralph Lauren"
                    articlepricenet="16807"
                    articlepricegross="20000" />
        </article_data>   
    </invoice>
</invoice_list>            

Attribute	Required	Format	Possible values	Info
merchantinvoicenumber	-	string	AN..40	([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 of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
-> shippingpricegross	-	non-negative int	N..7	gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
-> rebatenet	-	non-negative int	N..7	positive net value 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 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 of the order total (1,00 EUR = 100)
-> invoiceamountgross	+	positive int	N..7	gross value 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)

Full XML example - no partial shipments

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">
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
</data>

Full XML example - including a 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 and suborder.

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="EDIT_CART_CONTENT" apiversion="2">
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <invoice_list>
        <invoice merchantinvoicenumber="1234567">
            <invoice_params invoiceamountnet="15966" invoiceamountgross="19000" is_partial="1" rebatenet="1681" rebategross="2000"
 shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" currency="EUR" reference="1773673332" delayindays="0" trackingnumber="ABZ12398892131" />
             <article_data>
                <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
            </article_data>   
        </invoice>
        <invoice merchantinvoicenumber="234567">
            <invoice_params invoiceamountnet="10084" invoiceamountgross="12000" is_partial="1" rebatenet="0" rebategross="0"
 shippingname="Express Versand" shippingpricenet="0" shippingpricegross="0" currency="EUR" reference="1773673332" delayindays="0" trackingnumber="ABZ13498892131" />
             <article_data>
                <article articleid="1234" articlequantity="1" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="10084" articlepricegross="12000" />
            </article_data>   
        </invoice>
    </invoice_list>  
</data>

EditCartContent Response

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

Data Node

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

Attribute	Required	Format	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

Invoice Numbers Node

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

<invoice_numbers>
    <invoice_number
        invoiceid="REBP1234/1700186R1"
        billpayinvoicenumber="Z2I8EB#1" />
</invoice_numbers>        

Attribute	Required	Format	Values	Info
invoice_number	+	Child node of the invoice_numbers node
-> invoiceid	+	string	AN..255	Unique ID number that appears on the invoice that is sent to the customer.
-> billpayinvoicenumber	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_|#|:|.)*

Instalment Details Node (only for PayLater and Transaction Credit)

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

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

Attribute	Required	Format	Values	Info
option	+	parent node - this node only appears for PM3 (Transaction Credit)
ratecount	+	positive int	N	Number of installments
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 surchage 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	Gross value of this rate (Smallest currency unit! E.g. 100,00 Euro = 10000)
—> date	+	DATE	YYYYMMDD	Due date of the installment
—> type	+	string	AN	Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“)
instl_plan	+	parent node - this node only appears for PM4 (PayLater)
numinst	+	positive int	N	Number of installments
calc	+	child node of the instl_plan node
-> duration_in_months	+	int	N	Duration of the payment plan in months
-> fee_percent	+	decimal (between 0 and 100.0)	N	PayLater fee (%)
-> 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 (between 0 and 100.0)	N	Annual effective interest rate (%)
-> nominal	+	decimal (between 0 and 100.0)	N	Annual nominal interest rate (%)
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 installment
—> type	+	string	AN	Type of Installment („immediate“, „first“, „date“, „fee“)

Update Order

Update Order Request

Using the UpdateOrder request, the unique order reference can be changed. Attention! When changing this reference, the transaction purpose for the bank transfer will also change. If the customer has already received an invoice, another corrected invoice has to be sent. (The new bank information can be retrieved sending another “invoiceCreated” request)

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data 
    requesttype="UPDATE_ORDER" 
    apiversion="2">
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	UPDATE_ORDER	Type of request
apiversion	int	2	BillPay API Version

Default Params Node (Merchant Credentials)

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

update_params node

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

<update_params
        transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337"
        reference="Bestellnummer321" />

Attribute	Required	Format	Values	Info
transactionid	+	string	AN..50	Unique BillPay transaction ID for this order
reference	+	string	AN..40	([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="54321" updateid="12345"/>
</id_update_list>

Attribute	Required	Format	Values	Info
articleid	+	string	AN..40	The original article ID
updateid	+	string	AN..40	The new article ID

Full XML example

<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="UPDATE_ORDER" apiversion="2">
    <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>

Update Order Response

Data Node

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

Attribute	Required	Format	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

Get BillPay Bank Data Request

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.

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

<data 
    requesttype="GET_BILLPAY_BANK_DATA" 
    apiversion="2">
    <!-- Request Daten -->
</data>

Attribute	Format	Values	Info
requesttype	string	GET_BILLPAY_BANK_DATA	Type of request
apiversion	int	2	BillPay API Version

Default Params Node (Merchant Credentials)

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

Attribute	Required	Format	Info
mid	+	positive integer	Merchant ID
pid	+	positive integer	Portal ID
passwordhash	+	string	MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)

Order params node

 <order_params reference="2032322603" />

Attribute	Required	Format	Values	Info
reference	+	string	AN..40	([A-Z]|[a-z]|[0-9]|-|_)*

Full XML example

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

Get BillPay Bank Data Response

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

Data Node (Result of the identity and credit check)

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
        responsetype="GET_BILLPAY_BANK_DATA"
        errorcode="0"
        customermessage=""
        merchantmessage="">
    <!-- weitere Antwortdaten -->
</data>

Attribute	Required	Format	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
status	-	string	“APPROVED” / “DENIED”	Status of the identity and credit check

Bank Account Node (only “Invoice” & “Transaction Credit CHE”)

This node returns the BillPay bank account data to be used by the customer when paying for the order he/she placed. This information should be parsed and printed on the invoice document the customers receive with their package.

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

Attribute	Required	Format	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_numbers>        

Attribute	Required	Format	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	([A-Z]|[a-z]|[0-9]|-|_|#|:|.)*

Sample Requests

Prescore

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PRESCORE" apiversion="2" originofsale="o">
    <trace trace_id="5efba73acc901f0414e66bcc74953869bcb68dba" />
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="36134" orderamountgross="43000" currency="EUR" reference="123456" trackingnumber="ABZ12398892131" />
    <article_data>
        <article articleid="1234" articlequantity="2" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Preauthorize - Invoice B2C

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Preauthorize - Invoice B2B

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Preauthorize - Direct Debit

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="2" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" 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>

Preauthorize - PayLater/Transaction Credit

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="4" apiversion="2" originofsale="o">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzerstrasse" 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="p" />
    <shipping_details usebillingaddress="1" />
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <rate_request ratecount="6" terminmonths="6" totalamountgross="45520" />
    <bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
    <async_capture_request>
        <redirect_url><![CDATA[http://url1.de/redirect]]></redirect_url>
        <notify_url><![CDATA[http://url1.de/notify]]></notify_url>
    </async_capture_request>
    <fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Capture

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

Invoice Created - full cart

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <invoice_params carttotalgross="43000" currency="EUR" reference="1773673332" delayindays="0" />
</data>

Invoice Created - partial shipment

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2">
    <default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
    <invoice_params carttotalgross="23000" currency="EUR" reference="1773673332" delayindays="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>

Cancel

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

Edit Cart - no partial shipments

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">
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
</data>

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 and suborder.

<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="EDIT_CART_CONTENT" apiversion="2">
    <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" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="10084" articlepricegross="12000" />
        <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
    </article_data>
    <invoice_list>
        <invoice merchantinvoicenumber="1234567">
            <invoice_params invoiceamountnet="15966" invoiceamountgross="19000" is_partial="1" rebatenet="1681" rebategross="2000"
 shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" currency="EUR" reference="1773673332" delayindays="0" trackingnumber="ABZ12398892131" />
             <article_data>
                <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
            </article_data>   
        </invoice>
        <invoice merchantinvoicenumber="234567">
            <invoice_params invoiceamountnet="10084" invoiceamountgross="12000" is_partial="1" rebatenet="0" rebategross="0"
 shippingname="Express Versand" shippingpricenet="0" shippingpricegross="0" currency="EUR" reference="1773673332" delayindays="0" trackingnumber="ABZ13498892131" />
             <article_data>
                <article articleid="1234" articlequantity="1" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="10084" articlepricegross="12000" />
            </article_data>   
        </invoice>
    </invoice_list>  
</data>

Update Order

<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="UPDATE_ORDER" apiversion="2">
    <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>

Get Bank Data

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

Core Library

PHP

Preauthorize

Placing a Customer Order at BillPay

Create the ipl_preauthorize_request instance

<?php
require_once 'api/ipl_xml_api.php';
require_once 'api/php5/ipl_preauthorize_request.php';

$req = new ipl_preauthorize_request($apiUrl, IPL_CORE_PAYMENT_TYPE_INVOICE);

Set the merchant access credentials

<?php
$req->set_default_params(
$merchantId,
$portalId,
$securityKey
);

Add the customer information

<?php
$req->set_customer_details(
$id,
$type,
$salutation,
$title,
$firstName,
$lastName,
$addressStreet,
$addressStreetNo,
$addressAddition,
$zip,
$city,
$country,
$email,
$phoneNo,
$mobilePhoneNo,
$dayOfBirth,
$language,
$ip,
$customerGroup
);

Add additional parameters like the fraud detection session id

<?php$req->set_shipping_details(true);
$req->set_fraud_detection(sha(session_id()));

Add the complete/main order details

<?php$req->set_total(
$rebate,
$rebateGross,
$shippingName,
$shippingPrice,
$shippingPriceGross,
$cartTotalPrice,
$cartTotalPriceGross,
$currency,
$reference,
$reference2
);

Add the shopping cart items

<?php$req->add_article(
$articleid,
$articlequantity,
$articlename,
$articledescription,
$article_price,
$article_price_gross
);

Add the customer’s order history

<?php$req->add_order_history(
$historyOrderId,
$historyOrderDate,
$historyOrderAmount,
$historyOrderCurrency,
$historyOrderPaymentType,
$historyOrderStatus
);

The customer has accepted the Ts&Cs

<?php$req->set_terms_accepted($termsAccepted);

Send the request to BillPay

<?phptry {
$req->send();
} catch (Exception $e) {
echo $e->getMessage();
}

InvoiceCreated

Shipping notification to set the payment due date for the order

Create the ipl_invoice_created_request instance

<?phprequire_once 'api/ipl_xml_api.php';
require_once 'api/php5/ipl_invoice_created_request.php';

$req = new ipl_invoice_created_request($apiUrl);

Set the merchant access credentials

<?php$req->set_default_params(
$merchantId,
$portalId,
$securityKey
);

Set the order details

Total price: 274,55 EUR

Currency: EUR

Order number: $ref

Delay the payment due date (in days): 0

<?php$req->set_invoice_params(27455, "EUR", $ref, 0);

Send the request to BillPay

<?phptry {
$req->send();

if (!$req->has_error()) {
// Abfangen der Zahlungsinformationen
$accountHolder = $req->get_account_holder();
$accountNumber = $req->get_account_number();
$bankCode = $req->get_bank_code();
$bankName = $req->get_bank_name();
$invoiceReference = $req->get_invoice_reference();
$dueDate = $req->get_invoice_duedate();
$activationPerformed = $req->get_activation_performed();

if (count($req->get_dues()) > 0) {
}

} else {
$errorCode = $req->get_errorcode();
$merchantMessage = utf8_decode($req->get_merchant_error_message());
$customerMessage = utf8_decode($req->get_customer_error_message());
}
}
catch(Exception $e) {
echo $e->getMessage();
}

Cancellation

Registering complete order cancellations

Create the ipl_cancel_request instance

<?phprequire_once 'api/ipl_xml_api.php';
require_once 'api/php5/ipl_cancel_request.php';

$req = new ipl_cancel_request($apiUrl);

Set the merchant access credentials

<?php$req->set_default_params(
$merchantId,
$portalId,
$securityKey
);

Set the order details

Total price: 274,55 EUR

Currency: EUR

Order number: $ref

<?php$req->set_cancel_params($ref, 27455, "EUR");

Senden der Anfrage an BillPay

<?phptry {
$req->send();
if ($req->has_error()) {
$errorCode = $req->get_errorcode();
$merchantMessage = utf8_decode($req->get_merchant_error_message());
$customerMessage = utf8_decode($req->get_customer_error_message());
}
else {
// SUCCESS
}
}
catch(Exception $e) {
echo $e->getMessage();
}

Edit Cart

Modifying an existing order. Here it is possible to register partial returns or other changes to the order relating to the contents or related fees.

Create the ipl_edit_cart_content_request instance

<?phprequire_once 'api/ipl_xml_api.php';
require_once 'api/php5/ipl_edit_cart_content_request.php';

$req = new ipl_edit_cart_content_request($apiUrl);

Set the merchant access credentials

<?php$req->set_default_params(
$merchantId,
$portalId,
$securityKey
);

Set the order details

Shipping costs net/gross: 5,00 EUR/5,95 EUR

Shipping type: “Express-Versand”

Rebate net/gross: 5,00 EUR/ 5,95 EUR

Total price net/gross: 53,00 EUR / 79,05 EUR

Total price net/gross: 53,00 EUR / 79,05 EUR

Currency: EUR

Order number: $ref

<?php$req->set_total(500, 595, "Express-Versand", 500, 595, 4917, 5850, "EUR", $ref);

Set the new order contents

Article ID: “article003”

Article quantity: 3

Article name: “Kaffeetasse 07/11”

Article description: “Die tolle Kaffeetasse”

<?php$req->add_article("article003", 3, "Kaffetasse 07/11", "Die tolle Kaffeetasse", 1639, 1950);

Send the request to BillPay

<?php
try {
$req->send();

if ($req->has_error()) {
$errorCode = $req->get_errorcode();
$merchantMessage = utf8_decode($req->get_merchant_error_message());
$customerMessage = utf8_decode($req->get_customer_error_message());
} else {
// SUCCESS
}
}
catch(Exception $e) {
echo $e->getMessage();
}

DotNET

The .NET Core Library contains notation in the code that describes the functions.

Java

The Java Core Library contains notation in the code that describes the functions.

Addendum

Possible 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

Allowed values for the field „legalForm“ in the business to business authorization requests.

Value for the API	Description / Identifier to be displayed	DEU	CHE
ag / AG	(Aktiengesellschaft)	X	X
eg / eG	(eingetragene Genossenschaft)	X	X
einzel	Einzelfirma	X
ek / EK	(eingetragener Kaufmann)	X
e_ges	Einfache Gesellschaft	X
ev	e.V. (eingetragener Verein)	X	X
freelancer	Freiberufler/Kleingewerbetreibender/Handelsvertreter	X	X
gbr	GbR/BGB (Gesellschaft bürgerlichen Rechts)	X
gmbh	GmbH (Gesellschaft mit beschränkter Haftung)	X	X
gmbh_ig	GmbH in Gründung	X
gmbh_co_kg	GmbH & Co. KG	X
inv_kk	Investmentgesellschaft für kollektive Kapitalanlagen	X
kgKG	(Kommanditgesellschaft)	X	X
kgaa	Kommanditgesellschaft auf Aktien	X	X
k_ges	Kollektivgesellschaft	X
ltd	Limited	X	X
ltd_co_kg	Limited & Co. KG	X
ohg	OHG (offene Handelsgesellschaft)	X
public_inst	Öffentliche Einrichtung	X	X
misc_capital	Sonstige Kapitalgesellschaft	X	X
misc	Sonstige Personengesellschaft	X	X
foundation	Stiftung	X	X
ug	UG (Unternehmensgesellschaft haftungsbeschränkt)	X

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

	registerNumber		holderName
API Value	DEU	CHE	DEU	CHE
ag	X	X
eg		X
einzel				X
ek	X
e_ges				X
ev
freelancer			X	X
gbr			X
gmbh	X	X
gmbh_ig
gmbh_co_kg	X
inv_kk
kg	X	X
kgaa		X
k_ges				X
ltd
ltd_co_kg	X
ohg	X
public_inst
misc_capital
misc
foundation		X
ug	X

API Error Codes

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

Error Code	Message Audience	Message
1	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
1	Merchant Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
2	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
2	Merchant Message	Fehler: Die Händler-ID ist falsch.
3	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
3	Merchant Message	Fehler: Die Portal-ID ist falsch.
4	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
4	Merchant Message	Fehler: API Authentifizierung fehlgeschlagen.
5	Customer Message	Fehler: Sie müssen die Billpay AGB bestätigen, um diese Zahlart von Billpay nutzen zu können.
5	Merchant Message	Fehler: Sie müssen die Billpay AGB bestätigen, um diese Zahlart von Billpay nutzen zu können.
7	Customer Message	Fehler: Der Pflicht-Parameter [parameter] wurde nicht übergeben.
7	Merchant Message	Fehler: Der Pflicht-Parameter [parameter] wurde nicht übergeben.
8	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
8	Merchant Message	Fehler: Der Parameter [parameter] hat das falsche Datenformat.
9	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Vorname Ihrer Rechnungsadresse muss aus mind. 2 Buchstaben bestehen.
9	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Vorname Ihrer Rechnungsadresse muss aus mind. 2 Buchstaben bestehen.
11	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Straße Ihrer Rechnungsadresse muss aus mind. 2 Buchstaben bestehen.
11	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Straße Ihrer Rechnungsadresse muss aus mind. 2 Buchstaben bestehen.
12	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Hausnummer Ihrer Rechnungsadresse muss aus mind. 1 Ziffer bestehen.
12	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Hausnummer Ihrer Rechnungsadresse muss aus mind. 1 Ziffer bestehen.
13	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die PLZ Ihrer Rechnungsadresse muss aus genau [length] Ziffern bestehen.
13	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die PLZ Ihrer Rechnungsadresse muss aus genau [length] Ziffern bestehen.
14	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Ort Ihrer Rechnungsadresse muss aus mind. 2 Buchstaben bestehen.
14	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Ort Ihrer Rechnungsadresse muss aus mind. 2 Buchstaben bestehen.
15	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Telefonnummer Ihrer Rechnungsadresse ist nicht korrekt.
15	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Telefonnummer Ihrer Rechnungsadresse ist nicht korrekt.
16	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Handynummer Ihrer Rechnungsadresse ist nicht korrekt.
16	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Handynummer Ihrer Rechnungsadresse ist nicht korrekt.
17	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Ihre E-Mail-Adresse ist nicht korrekt.
17	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Ihre E-Mail-Adresse ist nicht korrekt.
18	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Ihr Geburtsdatum darf nicht in der Zukunft liegen.
18	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Ihr Geburtsdatum darf nicht in der Zukunft liegen.
19	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart. Sie müssen mind. 18 Jahre alt sein, um diese Zahlart von Billpay zu nutzen.
19	Merchant Message	Fehler: Bitte wählen Sie eine andere Zahlart. Sie müssen mind. 18 Jahre alt sein, um diese Zahlart von Billpay zu nutzen.
21	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Nachname Ihrer Lieferadresse muss aus mind. 2 Buchstaben bestehen.
21	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Nachname Ihrer Lieferadresse muss aus mind. 2 Buchstaben bestehen.
22	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Straße Ihrer Lieferadresse muss aus mind. 2 Buchstaben bestehen.
22	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Straße Ihrer Lieferadresse muss aus mind. 2 Buchstaben bestehen.
23	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Hausnummer Ihrer Lieferadresse muss aus mind. 1 Ziffer bestehen.
23	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Hausnummer Ihrer Lieferadresse muss aus mind. 1 Ziffer bestehen.
24	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die PLZ Ihrer Lieferadresse muss aus genau 5 Ziffern bestehen.
24	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die PLZ Ihrer Lieferadresse muss aus genau 5 Ziffern bestehen.
25	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Ort Ihrer Lieferadresse muss aus mind. 2 Buchstaben bestehen.
25	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Ort Ihrer Lieferadresse muss aus mind. 2 Buchstaben bestehen.
26	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Telefonnummer Ihrer Lieferadresse ist nicht korrekt.
26	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Telefonnummer Ihrer Lieferadresse ist nicht korrekt.
27	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Handynummer Ihrer Lieferadresse ist nicht korrekt.
27	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Handynummer Ihrer Lieferadresse ist nicht korrekt.
28	Customer Message	Fehler: Sie können diese Zahlart von Billpay derzeit nur nutzen, wenn die Liefer- und Rechnungsadresse in ‘Deutschland’ liegen.
28	Merchant Message	Fehler: Sie können diese Zahlart von Billpay derzeit nur nutzen, wenn die Liefer- und Rechnungsadresse in 'Deutschland’ liegen.
29	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
29	Merchant Message	Bitte wählen Sie eine andere Zahlart. Die IP-Adresse kommt aus einem Land, das auf der Blacklist steht.
31	Customer Message	Fehler: Ihre Rechnungs- oder Lieferadresse darf keine Packstation sein.
31	Merchant Message	Fehler: Ihre Rechnungs- oder Lieferadresse darf keine Packstation sein.
32	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
32	Merchant Message	Bitte wählen Sie eine andere Zahlart. Der Kunde wurde aufgrund fehlgeschlagener Identitäts- bzw. Bonitätsprüfung abgelehnt.
33	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
33	Merchant Message	Fehler: Der Bestellwert passt nicht zur Transaktions-ID.
34	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
34	Merchant Message	Fehler: Es wurde keine Transaktions-ID übergeben
35	Customer Message	Fehler: Es ist ein Fehler aufgetreten
35	Merchant Message	Fehler: Die übergebene Transaktions-ID ist ungültig
36	Customer Message	Fehler: Bitte wählen Sie eine Anrede aus.
36	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Das Pflichtfeld [parameter] muss den Wert -Herr- oder -Frau- haben
37	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
37	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Der Parameter [parameter] muss eine gültige IP-Adresse enthalten.
38	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
38	Merchant Message	Fehler: Der Pflicht-Parameter [customerType] wurde nicht übergeben oder hat einen ungültigen Wert.
39	Customer Message	Fehler: Der Wert für das Feld [parameter] muss ganzzahlig numerisch sein.
39	Merchant Message	Fehler: Der Wert für das Feld [parameter] muss ganzzahlig numerisch sein.
41	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
41	Merchant Message	Fehler: Von der IP-Adresse wurden zu viele Anfragen gesendet
42	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
42	Merchant Message	Fehler: Der Kunde hat offene Forderungen
43	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
43	Merchant Message	Fehler: Das Rechnungslimit des Kunden bei Billpay ist erreicht
44	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
44	Merchant Message	Fehler: Der Kunde hat offene Forderungen beim Händler
45	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
45	Merchant Message	Externe Identitäts- oder Bonitätsprüfung fehlgeschlagen
46	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
46	Merchant Message	Fehler: Wenn die Rechnungsadresse als Lieferadresse verwendet wird, muss die Lieferadresse leer sein [parameter]
47	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Hausnummer muss mit einer Zahl beginnen [parameter]
47	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die Hausnummer muss mit einer Zahl beginnen [parameter]
48	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
48	Merchant Message	Fehler: Es wurden keine zu stornierenden Artikel übergeben
49	Customer Message	Fehler: Der Warenkorb wurde geändert. Bitte starten Sie den Bestellprozess erneut.
49	Merchant Message	Fehler: Der Betrag der Bestellung bei der Bestätigung hat sich gegenüber der Vorauthorisierung geändert
51	Customer Message	Fehler: Der Wert für das Feld [parameter] muss mindestens [minLength] Zeichen lang sein
51	Merchant Message	Fehler: Der Wert für das Feld [parameter] muss mindestens [minLength] Zeichen lang sein
52	Customer Message	Fehler: Der Wert für das Feld [parameter] darf höchstens [maxLength] Zeichen lang sein
52	Merchant Message	Fehler: Der Wert für das Feld [parameter] darf höchstens [maxLength] Zeichen lang sein
53	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
53	Merchant Message	Fehler: Die übergebenen Bestelldaten sind ungültig
54	Customer Message	Fehler: Der Wert für das Feld [parameter] muss einem der folgenden Werte entsprechen: [string]
54	Merchant Message	Fehler: Der Wert für das Feld [parameter] muss einem der folgenden Werte entsprechen: [string]
55	Customer Message	Fehler: Die zu stornierende Menge ist höher als die Bestellmenge eines Artikels
55	Merchant Message	Fehler: Die zu stornierende Menge ist höher als die Bestellmenge eines Artikels
56	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
56	Merchant Message	Fehler: Das übergebene XML ist ungültig
57	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
57	Merchant Message	Fehler: Die Bestellung wurde bereits erfasst
58	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
58	Merchant Message	Fehler: Der Betrag der Bestellung bei der Stornierung hat sich gegenüber der Vorauthorisierung geändert
59	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
59	Merchant Message	Fehler: Teilstornierung ist nicht erlaubt
61	Customer Message	Fehler: Die manuelle Aktivierung der Forderung ist nicht erlaubt
61	Merchant Message	Fehler: Die manuelle Aktivierung der Forderung ist nicht erlaubt
62	Customer Message	Fehler: Der Betrag der Bestellung bei der manuellen Aktivierung der Forderung hat sich gegenüber der Vorauthorisierung geändert
62	Merchant Message	Fehler: Der Betrag der Bestellung bei der manuellen Aktivierung der Forderung hat sich gegenüber der Vorauthorisierung geändert
63	Customer Message	Fehler: Der Betrag der Teilstornierung darf den Gesamtwert der Bestellung nicht überschreiten.
63	Merchant Message	Fehler: Der Betrag der Teilstornierung darf den Gesamtwert der Bestellung nicht überschreiten.
64	Customer Message	Fehler: Bei Teilstornierung aller verbleibenden Artikel darf der Gesamtbetrag nicht vom Bestellwert abweichen.
64	Merchant Message	Fehler: Bei Teilstornierung aller verbleibenden Artikel darf der Gesamtbetrag nicht vom Bestellwert abweichen.
65	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
65	Merchant Message	Fehler: Der übergebene Wert [parameter
66	Customer Message	Fehler: Diese Zahlart von Billpay wird für Bestellungen mit einem Wert von
66	Merchant Message	Fehler: Diese Zahlart von Billpay wird für Bestellungen mit einem Wert von
67	Customer Message	Fehler: Die übergebene BLZ ist ungültig
67	Merchant Message	Fehler: Die übergebene BLZ ist ungültig
68	Customer Message	Fehler: Die übergebene Kontonummer ist ungültig
68	Merchant Message	Fehler: Die übergebene Kontonummer ist ungültig
69	Customer Message	Fehler: Die übergebene Bankverbindung ist ungültig
69	Merchant Message	Fehler: Die übergebene Bankverbindung ist ungültig
71	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
71	Merchant Message	Authorisierung fehlgeschlagen
72	Customer Message	Fehler: Der übergebene Wert für den Parameter [parameter] muss einem der folgenden Werte entsprechen: [list]
72	Merchant Message	Fehler: Der übergebene Wert für den Parameter [parameter] muss einem der folgenden Werte entsprechen: [list]
73	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
73	Merchant Message	Fehler: Bei der Teilstornierung dürfen nur positive zu stornierende Artikelmengen übergeben werden (Parameter [parameter])
74	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
74	Merchant Message	Fehler: Die Konsistenzprüfung für die für den Ratenkauf übergebenen Werte ist fehlgeschlagen.
75	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
75	Merchant Message	Fehler: Die Verzögerung der Aktivierung darf maximal [baseValue] Tage betragen
76	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
76	Merchant Message	Fehler: Die übergebene Anzahl Raten ist ungültig.
77	Customer Message	Fehler: Der Wert für den Parameter [parameter] muss größer als [baseValue] sein
77	Merchant Message	Fehler: Der Wert für den Parameter [parameter] muss größer als [baseValue] sein
78	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
78	Merchant Message	Fehler: Es wurde keine Artikelliste übergeben oder die Artikelliste ist leer.
79	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
79	Merchant Message	Fehler: Die übergebene IP-Adresse stammt aus einem lokalen Netzwerk
81	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
81	Merchant Message	Fehler: Für diesen Shop ist die Zahlart [parameter] nicht erlaubt.
82	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
82	Merchant Message	Fehler: Für diesen Shop sind Geschäftskundenanfragen mit der Zahlart [parameter] nicht aktiviert.
83	Customer Message	Fehler: Der Wert für den Parameter [parameter] muss größer oder gleich [baseValue] sein
83	Merchant Message	Fehler: Der Wert für den Parameter [parameter] muss größer oder gleich [baseValue] sein
84	Customer Message	Fehler: Der Wert für den Parameter [parameter] muss kleiner oder gleich [baseValue] sein
84	Merchant Message	Fehler: Der Wert für den Parameter [parameter] muss kleiner oder gleich [baseValue] sein
85	Customer Message	Fehler: Es wurde keine Liste mit Fälligkeitsdaten übergeben oder die XML-Struktur der Liste ist falsch
85	Merchant Message	Fehler: Es wurde keine Liste mit Fälligkeitsdaten übergeben oder die XML-Struktur der Liste ist falsch
86	Customer Message	Fehler: Das Datum für Parameter [parameter] muss in der Zukunft liegen
86	Merchant Message	Fehler: Das Datum für Parameter [parameter] muss in der Zukunft liegen
87	Customer Message	Fehler: Bestellungen aus dem Land [address.country] sind nicht erlaubt
87	Merchant Message	Fehler: Bestellungen aus dem Land [address.country] sind nicht erlaubt
88	Customer Message	Fehler: Die Währung [currency] wird nicht unterstützt
88	Merchant Message	Fehler: Die Währung [currency] wird nicht unterstützt
89	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
89	Merchant Message	Fehler: Das Portal ist deaktiviert.
91	Customer Message	Fehler: Für Kunden aus dem Land [parameter] stehen die Billpay Zahlarten leider nicht zur Verfügung
91	Merchant Message	Fehler: Für Kunden aus dem Land [parameter] stehen die Billpay Zahlarten leider nicht zur Verfügung.
92	Customer Message	Fehler: Der minimale Bestellwert für Bestellungen mit dieser Zahlart von Billpay wurde unterschritten. Bitte erhöhen Sie Ihren Warenkorb
92	Merchant Message	Fehler: Der minimale Bestellwert für Bestellungen mit dieser Zahlart von Billpay wurde unterschritten. Bitte erhöhen Sie Ihren Warenkorb
93	Customer Message	Fehler: Der maximale Bestellwert für Bestellungen mit dieser Zahlart von Billpay wurde überschritten.
93	Merchant Message	Fehler: Der maximale Bestellwert für Bestellungen mit dieser Zahlart von Billpay wurde überschritten.
94	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
94	Merchant Message	Fehler: Die übergebene Währung hat sich gegenüber der Vorauthorisierung geändert
95	Customer Message	Fehler: Das Land [country] wird nicht unterstützt.
95	Merchant Message	Fehler: Das Land [country] wird nicht unterstützt.
96	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten
96	Merchant Message	Fehler: Ungültiger Bestellstatus für diese Operation.
97	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die ausgewählte Rechtsform ist ungültig für das Land [country]
97	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die ausgewählte Rechtsform ist ungültig für das Land [country]
98	Customer Message	Fehler: Bitte geben Sie einen Wert für das Feld [parameter] ein
98	Merchant Message	Fehler: Bitte geben Sie einen Wert für das Feld [parameter] ein
99	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Ihre Eingabe für das Feld [parameter] enthält ungültige Zeichen.
99	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Ihre Eingabe für das Feld [parameter] enthält ungültige Zeichen.
111	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
111	Merchant Message	Fehler: Die Kundendaten dürfen sich bei der Zahlartensteuerung nicht ändern.
112	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
112	Merchant Message	Fehler: Ungültige Vorauthorisierung. Für das aktuelle Portal ist die Zahlartensteuerung aktiviert.
113	Customer Message	Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
113	Merchant Message	Fehler: Die Anfrage wurde wegen Betrugsverdacht abgelehnt.
114	Customer Message	Fehler: Es ist ein Fehler aufgetreten
114	Merchant Message	Fehler: Bestellung wurde bereits teilaktiviert
115	Customer Message	Fehler: Es ist ein Fehler aufgetreten
115	Merchant Message	Fehler: Der Aktivierungsbetrag für die Liefergebühren überschreitet den Wert der Liefergebühren.
116	Customer Message	Fehler: Es ist ein Fehler aufgetreten
116	Merchant Message	Fehler: Negativer Gesamtbetrag
117	Customer Message	Fehler: Es ist ein Fehler aufgetreten
117	Merchant Message	Fehler: Leere Aktivierung
118	Customer Message	Fehler: Es ist ein Fehler aufgetreten
118	Merchant Message	Fehler: Keine Unterbestellungen gefunden
119	Customer Message	Fehler: Es ist ein Fehler aufgetreten
119	Merchant Message	Fehler: Artikel wurde bereits aktiviert
121	Customer Message	Fehler: Es ist ein Fehler aufgetreten
121	Merchant Message	Fehler: Teilaktivierung nicht erlaubt
122	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
122	Merchant Message	Fehler: Die Operation ist für diese Zahlart nicht erlaubt.
123	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
123	Merchant Message	Fehler: Rechnungsnummer ist bereits vorhanden.
124	Customer Message	Fehler: Es ist ein Fehler aufgetreten
124	Merchant Message	Fehler: Referenz darf kein Rautensymbol (#) beinhalten
125	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
125	Merchant Message	Fehler: Die Bestellung wurde noch nicht abgeschlossen.
126	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
126	Merchant Message	Fehler: Die Erhöhung des Bestellwertes ist für den aktuellen Status der Bestellung nicht erlaubt
127	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
127	Merchant Message	Fehler: Die übergebene Ratenzahl ist ungültig.
128	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
128	Merchant Message	Fehler: Die Erhöhung des Bestellwertes ist für den aktuellen Status der Bestellung nicht erlaubt
129	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
129	Merchant Message	Fehler: Der Teilaktivierungsbetrag überschreitet den Gesamtwert der Bestellung.
131	Customer Message	Fehler: Die Bestellnummer wurde nicht gefunden.
131	Merchant Message	Fehler: Die Bestellnummer wurde nicht gefunden.
132	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die übergebene IBAN ist ungültig.
132	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die übergebene IBAN ist ungültig.
133	Customer Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die übergebene BIC ist ungültig.
133	Merchant Message	Fehler: Bitte überprüfen Sie Ihre Daten. Die übergebene BIC ist ungültig.
134	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart. Das SEPA-Mandat für dieses Konto wurde widerrufen.
134	Merchant Message	Fehler: Das SEPA-Mandat für dieses Konto wurde vom Kunden widerrufen.
135	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart oder versuchen es später erneut. Es ist ein interner Fehler aufgetreten.
135	Merchant Message	Fehler: Anfragen mit dieser Zahlart Konfiguration können nur im Auto-Capture Modus ausgeführt werden.
136	Customer Message	Die BIC und IBAN Ländercodes stimmen nicht überein.
136	Merchant Message	Die BIC und IBAN Ländercodes stimmen nicht überein.
137	Customer Message	Fehler: Bitte geben Sie einen Kontoinhaber an.
137	Merchant Message	Fehler: Bitte geben Sie einen Kontoinhaber an.
138	Customer Message	Fehler: Der Wert für den Kontoinhaber enthält ungültige Zeichen.
138	Merchant Message	Fehler: Der Wert für den Kontoinhaber enthält ungültige Zeichen.
139	Customer Message	Fehler: Die Anfrage wird bereits verarbeitet. Bitte warten Sie, bis die Verarbeitung abgeschlossen ist.
139	Merchant Message	Fehler: Die Anfrage wird bereits verarbeitet. Bitte warten Sie, bis die Verarbeitung abgeschlossen ist.
141	Customer Message	Fehler: Es ist ein interner Fehler aufgetreten. Bitte versuchen Sie es später erneut.
141	Merchant Message	Fehler: Die Anfrage ist nicht mehr gültig da für diesen Kunden eine weitere Anfrage durchgeführt wurde.
142	Customer Message	Fehler: Bitte wählen Sie eine andere Zahlart. Leider können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten.
142	Merchant Message	Fehler: Der Wert für das Feld expecteddaystillshipping ist kleiner als das erlaubte Minimum.
143	Customer Message	Fehler: Die Liefergebühren dürfen nicht in der Bestellungen verbleiben wenn der Rest der Bestellung storniert wird.
143	Merchant Message	Fehler: Die Liefergebühren dürfen nicht in der Bestellungen verbleiben wenn der Rest der Bestellung storniert wird.
144	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
144	Merchant Message	Fehler: Der für die Änderung der Bestellung übergebene Warenkorb ist inkonsistent (Summe der Artikelpreise + Versandkosten - Rabatte muss gleich dem Gesamtwert der Bestellung sein).
145	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
145	Merchant Message	Fehler: Mindestens einer der für eine Rechnung übergebenen Artikel existiert nicht in dieser Bestellung.
146	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
146	Merchant Message	Fehler: Die in der Anfrage übergebenen Informationen zu den Rechnungen sind entweder ungültig für diese Zahlart oder stimmen nicht mit den existierenden Rechnungen überein.
147	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
147	Merchant Message	Fehler: Die in der Anfrage übergebenen Informationen zur Änderung einer Rechnung sind ungültig für den Ratenkauf.
148	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
148	Merchant Message	Fehler: Mindestens eine der in der Anfrage übergebenen Rechnungen existiert nicht für diese Bestellung.
149	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
149	Merchant Message	Fehler: Der für die Änderung einer Rechnung übergebene Warenkorb ist inkonsistent (Summe der Artikelpreise + Versandkosten - Rabatte muss gleich dem Gesamtwert der Bestellung sein).
151	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
151	Merchant Message	Fehler: Die Menge eines Artikels einer Rechnung überschreitet die Menge dieses Artikels in der Bestellung.
152	Customer Message	Fehler: Fehler: Der Bertrag der gemeldeten Kundenzahlung überschreitet den aktuell offenen Forderungsbetrag.
152	Merchant Message	Fehler: Fehler: Der Bertrag der gemeldeten Kundenzahlung überschreitet den aktuell offenen Forderungsbetrag.
153	Customer Message	Fehler: Bitte versuchen Sie es später erneut. Es ist ein interner Fehler aufgetreten.
153	Merchant Message	Fehler: Die Validierung der XML-Anfrage ist fehlgeschlagen.

Possible Values for the field “error_field” from the BillPay server response.

Error Field	XML element of the authorization request (XPath)
tcaccepted	//data/@tcaccepted
address_gender	//data/customer_details/@salutation
address_title	//data/customer_details/@title
address_firstname	//data/customer_details/@firstName
address_lastname	//data/customer_details/@lastName
address_street	//data/customer_details/@street
address_streetno	//data/customer_details/@streetNo
address_zip	//data/customer_details/@zip
address_city	//data/customer_details/@city
address_phone	//data/customer_details/@phone
address_cell	phone//data/customer_details/@cellPhone
address_email	//data/customer_details/@email
address_dateofbirth	//data/customer_details/@dateofbirth
address_country	//data/customer_details/@country
shippingaddress_gender	//data/shipping_details/@salutation
shippingaddress_title	//data/shipping_details/@title
shippingaddress_firstname	//data/shipping_details/@firstName
shippingaddress_lastname	//data/shipping_details/@lastName
shippingaddress_street	//data/shipping_details/@street
shippingaddress_streetno	//data/shipping_details/@streetNo
shippingaddress_zip	//data/shipping_details/@zip
shippingaddress_city	//data/shipping_details/@city
shippingaddress_phone	//data/shipping_details/@phone
shippingaddress_cellphone	//data/shipping_details/@cellPhone
shippingaddress_country	//data/shipping_details/@country
bankaccount_accountholder	//data/bank_account/@accountholder
bankaccount_accountnumber	//data/bank_account/@accountnumber
bankaccount_sortcode	//data/bank_account/@sortcode
raterequest_ratecount	//data/rate_request/@ratecount
companydetails_name	//data/company_details/@name
companydetails_legalform	//data/company_details/@legalForm
companydetails_registernumber	//data/company_details/@registerNumber
companydetails_holdername	//data/company_details/@holderName
companydetails_taxnumber	//data/company_details/@taxNumber