E-Commerce Solutions
Getting Started
This documentation covers integrating BillPay e-commerce payment solutions and the BillPay XML API with your shop and order management systems. An overview of the payment methods on offer and general information about BillPay can be found here.
BillPay offers programming libraries in various languages to help simplify your integration. Before getting started, please consult the versioning table to ensure that the BillPay programming library you have is compatible with the current API version. If you are not using one of our libraries, and plan on integrating our XML API, we recommend you take a look at the request specific XSD files in the following table:
API Call | Purpose | XSD Links |
---|---|---|
prescore | Placing an order | Request / Response |
preauthorize | Placing an order | Request / Response |
capture | Placing an order | Request / Response |
invoiceCreated | Managing an order | Request / Response |
cancel | Managing an order | Request / Response |
editCartContent | Managing an order | Request / Response |
updateOrder | Managing an order | Request / Response |
getBillPayBankData | Managing an order | Request / Response |
Front-end Integration
The JavaScript Widget
The core of all integrations is the BillPay JavaScript widget, which displays all BillPay payment method relevant fields and information in a conversion optimized and standardized fashion. Implementing the BillPay widget helps your shop benefit from BillPay brand recognition and improved customer satisfaction.
For integration projects where the shop system is developed in-house or BillPay does not offer a plug-in, it is a requirement to implement the BillPay Widget for the display of the BillPay payment methods.
Configuration
Step 1: Loading the JavaScript
In order to load the JavaScript widget upon the selection of a BillPay payment method in your checkout, the following snippet needs to be included in the shop template:
<!-- Initialization & Configuration -->
<script type="application/javascript">
var bpyReq = {},
appPath = '//widgetcdn.billpay.de/checkout/1.x.x/';
(function(win, doc, appPath, objectName) {
bpyReq = {
"deps": ['main'],
"baseUrl": appPath,
"skipDataMain": true,
"callback": function() {}
};
win['BillPayCheckout'] = objectName;
win[objectName] = win[objectName] || function() {
(win[objectName].queue = win[objectName].queue || []).push(arguments)
};
var requireJs = doc.createElement('script');
requireJs.src = appPath + 'require.js';
doc.getElementsByTagName('head')[0].appendChild(requireJs);
})(window, document, appPath, 'billpayCheckout');
</script>
The function billpayCheckout
is now available to use.
Step 2:Configuration
In order to configure the JavaScript widget the billpayCheckout
function is called, with the first parameter options
and a second JSON object containing customer and shop information as the second parameter. The container
variable identifies the container (e.g. div) where the BillPay widget should be rendered. The checkout.form
variable is the jQuery identifier of the checkout form, to which the values entered into the fields generated by the BillPay widget will be appended. Upon submission of the checkout form, these values will be available for server-side processing and the eventual submission to the BillPay XML API.
<script type="application/javascript">
billpayCheckout('options', {
"container":".bpy-checkout-container",
"checkout": {
"form": "#payment_form"
},
"shop": {
"apiKey": "710290a938e6b4770000005552",
"live": false
},
"order": {
"cartAmount": 161.94, // Total order value without shipping or additional fees
"orderAmount": 166.94, // Total order value including shipping and additional fees
"currency": "EUR" // the currency to be used for checkout
},
"customer": {
"billing": {
"salutation": "", // The customer's salutation. If this field is empty, the salutation input will be shown in the checkout widget.
"firstName": "Thomas", // The customer's first name
"lastName": "Testkunde", // The customer's last name
"street": "Zinnowitzer Str.", // The customer's street (billing address)
"streetNo": "1", // The customer's house number (billing address)
"zip": "10115", // The customer's zip code (billing address)
"city": "Berlin", // The customer's city (billing address)
"phoneNumber": "3254234234234", // The customer's phone number. If this field is empty, the phone number input will be shown in the checkout widget.
"countryIso2": "DE", // 2-digit country code of the customer's invoice address
"countryIso3": "deu", // 3-digit country code of the customer's invoice address
"dayOfBirth": "1970-01-15" // customer's date of birth in YYYY-MM-DD format. If this field is set, it won't be requested in the checkout widget.
},
"language": "de", // 2-digit language code for the checkout session
"identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // unique session ID hash
"customerGroup": "private", // private or business customer
"forceCustomerGroup": true // true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false if you do not have this value
},
"inputNames": {
"order": {
"cartAmount": "billpay[cart_amount]",
"orderAmount": "billpay[order_amount]",
"currency": "billpay[currency]"
},
"customer": {
"salutation": "billpay[customer_salutation]",
"phoneNumber": "billpay[customer_phone_number]",
"dayOfBirth": "billpay[customer_day_of_birth]",
"language": "billpay[customer_language]",
"companyName": "billpay[company_name]",
"companyHolder": "billpay[company_holder]",
"legalForm": "billpay[company_legal_form]",
"registerNumber": "billpay[company_register_number]",
"taxNumber": "billpay[company_tax_number]",
"bankAccount": {
"iban": "billpay[customer_iban]",
"bic": "billpay[customer_bic]"
},
"accountHolder": "billpay[account_holder]"
},
"paymentMethods": {
"invoice": {
"customerGroup": "billpay[invoice_customer_group]",
"termsOfService": "billpay[invoice_toc]"
},
"directDebit": {
"customerGroup": "billpay[direct_debit_customer_group]",
"termsOfService": "billpay[direct_debit_toc]"
},
"transactionCredit": {
"customerGroup": "billpay[transaction_credit_customer_group]",
"duration": "billpay[transaction_credit_duration]",
"instalmentsCount": "billpay[transaction_credit_instalments_count]",
"instalmentAmount": "billpay[transaction_credit_instalment_amount]",
"firstInstalmentAmount": "billpay[transaction_credit_first_instalment_amount]",
"totalAmount": "billpay[transaction_credit_total_amount]",
"feeAbsolute": "billpay[transaction_credit_fee_absolute]",
"feePercentage": "billpay[transaction_credit_fee_percentage]",
"processingFee": "billpay[transaction_credit_processing_fee_absolute]",
"annualPercentageRate": "billpay[transaction_credit_annual_percentage_rate]",
"termsOfService": "billpay[transaction_credit_toc]"
},
"paylater": {
"customerGroup": "billpay[paylater_customer_group]",
"duration": "billpay[paylater_duration]",
"instalmentsCount": "billpay[paylater_instalments_count]",
"instalmentAmount": "billpay[paylater_instalment_amount]",
"feeAbsolute": "billpay[paylater_fee_absolute]",
"totalAmount": "billpay[paylater_total_amount]",
"termsOfService": "billpay[paylater_toc]"
}
}
}
});
</script>
Variable | Explanation |
---|---|
container | jQuery selector that defines the container for the BillPay widget to be rendered. (in this example: “.bpy-checkout-container”) |
checkout.form | jQuery selector (id) of the checkout form where the widget fields will be included for processing upon submission. |
shop.apiKey | Public API Key; generated and delivered by BillPay for your portal. |
shop.live | Defines if the widget is running in “test” or “live” mode. |
order.cartAmount | Value of the total order (article value excl. shipping cost or any other additional fees.) |
order.orderAmount | Total order value (incl. shipping cost or any other additional fees |
order.currency | ISO4217 Code for the currency |
customer.billing.salutation | Salutation |
customer.billing.firstName | First name of the customer |
customer.billing.lastName | Last name of the customer |
customer.billing.street | Street of the customer address |
customer.billing.zip | Zip code of the customer address |
customer.billing.city | City of the customer address |
customer.billing.phoneNumber | Phone number |
customer.billing.countryIso2 | ISO3166-1 (alpha-2) 2-digit country code of the customer address country |
customer.billing.countryIso3 | ISO3166 (alpha-3) 3-digit country code of the customer address country |
customer.billing.dayOfBirth | Customer’s date of birth |
customer.language | ISO3166-1 (alpha-2) Language of the customer |
customer.identifier | Unique identifier of the user session. This token is used for fraud prevention (e.g. hash of session ID) |
customer.customerGroup | private for B2C Customers business for B2B Customers |
customer.forceCustomerGroup | true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown false: when the value is not provided in the customerGroup |
inputNames | IDs of the hidden input fields that will be generated inside the checkout.form jQuery selector by the JavaScript widget. (e.g.: billpay[NAME_OF_THE_FORM_FIELD]) |
inputNames.order | Input fields for the order data |
inputNames.customer | Input fields for the customer data |
inputNames.paymentMethods | Input fields for payment specific information |
request | JSON object, which contains request information (e.g. json_encode($_REQUEST);) |
Step 3: Execution
When calling run
, the BillPay widget is rendered in the container identified in the options
call container
variable.
It is also possible to supply the container
as a second parameter (json object) when calling run
. Doing so allows you to render multiple checkout widgets on one page.
<script type="application/javascript">
billpayCheckout('run');
</script>
If you choose to define the container
when calling run
, you would leave the container
variable out of the options
array and include it in the run
call as follows:
<script type="application/javascript">
billpayCheckout('run', {"container": ".bpy-checkout-container"});
</script>
Variable | Info |
---|---|
container | jQuery selector defining the container for the BillPay payment methods to be displayed. (in this example: “.bpy-checkout-container”) |
Step 4: Validating the widget on submit
<script type="application/javascript">
$("#payment_form").submit(function( event ) {
if(!billpayCheckout('isValid')){
event.preventDefault();
}
});
</script>
Variable | Info |
---|---|
’#payment_form’ | jQuery selector defining the ID of the checkout form that contains the payment methods and is being submitted (in this example: “#payment_form”) |
Full Example
<!DOCTYPE html>
<html>
<head></head>
<body>
<!-- Initialisierung & Konfiguration -->
<script type="application/javascript">
var bpyReq = {},
appPath = '//widgetcdn.billpay.de/checkout/1.x.x/';
(function(win, doc, appPath, objectName) {
bpyReq = {
"deps": ['main'],
"baseUrl": appPath,
"skipDataMain": true,
"callback": function() {}
};
win['BillPayCheckout'] = objectName;
win[objectName] = win[objectName] || function() {
(win[objectName].queue = win[objectName].queue || []).push(arguments)
};
var requireJs = doc.createElement('script');
requireJs.src = appPath + 'require.js';
doc.getElementsByTagName('head')[0].appendChild(requireJs);
})(window, document, appPath, 'billpayCheckout');
billpayCheckout('options', {
"container":".bpy-checkout-container",
"checkout": {
"form": "#payment_form"
},
"shop": {
"apiKey": "710290a938e6b4770000005552",
"live": false
},
"order": {
"cartAmount": 161.94, // Total order value without shipping or additional fees
"orderAmount": 166.94, // Total order value including shipping and additional fees
"currency": "EUR" // the currency to be used for checkout
},
"customer": {
"billing": {
"salutation": "", // The customer's salutation. If this field is empty, the salutation input will be shown in the checkout widget.
"firstName": "Thomas", // The customer's first name
"lastName": "Testkunde", // The customer's last name
"street": "Zinnowitzer Str.", // The customer's street (billing address)
"streetNo": "1", // The customer's house number (billing address)
"zip": "10115", // The customer's zip code (billing address)
"city": "Berlin", // The customer's city (billing address)
"phoneNumber": "3254234234234", // The customer's phone number. If this field is empty, the phone number input will be shown in the checkout widget.
"countryIso2": "DE", // 2-digit country code of the customer's invoice address
"countryIso3": "deu", // 3-digit country code of the customer's invoice address
"dayOfBirth": "1970-01-15" // customer's date of birth in YYYY-MM-DD format. If this field is set, it won't be requested in the checkout widget.
},
"language": "de", // 2-digit language code for the checkout session
"identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // unique session ID hash
"customerGroup": "private", // private or business customer
"forceCustomerGroup": true // true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false if you do not have this value
},
"inputNames": {
"order": {
"cartAmount": "billpay[cart_amount]",
"orderAmount": "billpay[order_amount]",
"currency": "billpay[currency]"
},
"customer": {
"salutation": "billpay[customer_salutation]",
"phoneNumber": "billpay[customer_phone_number]",
"dayOfBirth": "billpay[customer_day_of_birth]",
"language": "billpay[customer_language]",
"companyName": "billpay[company_name]",
"companyHolder": "billpay[company_holder]",
"legalForm": "billpay[company_legal_form]",
"registerNumber": "billpay[company_register_number]",
"taxNumber": "billpay[company_tax_number]",
"bankAccount": {
"iban": "billpay[customer_iban]",
"bic": "billpay[customer_bic]"
},
"accountHolder": "billpay[account_holder]"
},
"paymentMethods": {
"invoice": {
"customerGroup": "billpay[invoice_customer_group]",
"termsOfService": "billpay[invoice_toc]"
},
"directDebit": {
"customerGroup": "billpay[direct_debit_customer_group]",
"termsOfService": "billpay[direct_debit_toc]"
},
"transactionCredit": {
"customerGroup": "billpay[transaction_credit_customer_group]",
"duration": "billpay[transaction_credit_duration]",
"instalmentsCount": "billpay[transaction_credit_instalments_count]",
"instalmentAmount": "billpay[transaction_credit_instalment_amount]",
"firstInstalmentAmount": "billpay[transaction_credit_first_instalment_amount]",
"totalAmount": "billpay[transaction_credit_total_amount]",
"feeAbsolute": "billpay[transaction_credit_fee_absolute]",
"feePercentage": "billpay[transaction_credit_fee_percentage]",
"processingFee": "billpay[transaction_credit_processing_fee_absolute]",
"annualPercentageRate": "billpay[transaction_credit_annual_percentage_rate]",
"termsOfService": "billpay[transaction_credit_toc]"
},
"paylater": {
"customerGroup": "billpay[paylater_customer_group]",
"duration": "billpay[paylater_duration]",
"instalmentsCount": "billpay[paylater_instalments_count]",
"instalmentAmount": "billpay[paylater_instalment_amount]",
"feeAbsolute": "billpay[paylater_fee_absolute]",
"totalAmount": "billpay[paylater_total_amount]",
"termsOfService": "billpay[paylater_toc]"
}
}
}
});
</script>
<!-- Container -->
<form id="payment_form">
<h1>Rechnungskauf</h1>
<div class="bpy bpy-checkout-container" bpy-pm="invoice"></div>
<h1>Lastschrift</h1>
<div class="bpy bpy-checkout-container" bpy-pm="directDebit"></div>
<h1>PayLater</h1>
<div class="bpy bpy-checkout-container" bpy-pm="paylater"></div>
</form>
<!-- run the widget -->
<script type="application/javascript">
billpayCheckout('run', {"container": ".bpy-checkout-container"});
$("#payment_form").submit(function( event ) {
if(!billpayCheckout('isValid')){
event.preventDefault();
}
});
</script>
</body>
</html>
Legal Texts and Logos
In addition to the integration of the BillPay javascript widget, merchants are required to include BillPay related text passages in the terms and conditions and privacy pages of their website. These passages will be provided to you by BillPay.
Should you display payment method logos in the footer of your website or in the payment method selection portion of your checkout, it is required to also include the relevant BillPay logos. These can be found and downloaded in either png or svg format via the following url:
https://www.billpay.de/en/shopintegration/downloads/
XML API Overview
Every XML service request consists of an XML document, which is sent to the service URL specifically for each request type using the POST method. The BillPay server response contains an error code, as well as a message to be displayed in the frontend (“customer message”), a message to be logged by the merchant (“merchant message”), and potentially a message in the case of an XSD validation error (“developer_message”). The transaction can only be seen as successful after receiving an error code value of “0”. All other error codes imply that there has been some kind of issue with the request.
All XML data must be UTF-8 encoded and all server responses from BillPay will be too.
The schema of all XML service requests is based on the use of attributes. Please make sure, that all reserved characters are escaped according to the following table:
Reserved Character | Escape Sequence |
---|---|
& | & |
“ | " |
’ | ' |
< | < |
> | > |
Web service URL
The URL for every XML service is constructed using the base URL followed by an identifier for the specific request.
Base URLs
- Live System: https://api.billpay.de/v2/xml
- Test System: https://test-api.billpay.de/v2/xml/offline
Generic Parameters
Generic parameters for all XML requests
Some parameters are required in all XML requests no matter which endpoint is addressed. (e.g. the merchant API credentials to authorize your connection). The merchant API credentials are generated and sent by BillPay.
<?xml version="1.0" encoding="UTF-8"?>
<data apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<!-- additional request specific data -->
</data>
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Response
Generic Parameter for all XML responses
The following parameters are returned with every XML service response:
<?xml version="1.0" encoding="UTF-8"?>
<data apiversion="2.0.0" customermessage="Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction." merchantmessage="Bitte wählen Sie eine andere Zahlart. Der Kunde wurde aufgrund fehlgeschlagener Identitäts- bzw. Bonitätsprüfung abgelehnt." developermessage="" errorcode="32">
<!-- additional request specific data -->
</data>
Attribute | Required | Data Type | Info |
---|---|---|---|
errorcode | + | non-negative int | Numerical error code - the standard value is "0” (no error). List of error codes |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only |
customermessage | + | string | Detailed error message to be displayed to the customer |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. |
Please note that we may make changes to the API error messages that are returned for customers and merchants. In addition, new error codes and error messages can be added at any time.
Placing an Order
Process Overview
Prescoring
Using the “prescore” scoring model, the identity and credit check of the customer is performed before the payment method options are displayed. The results of the check are then used to display or hide the available payment methods accordingly. This eliminates the negative purchasing experience of a “rejection”.
“One-Step Order Creation”
Using the “One-Step” order model, the identity and credit check of the customer takes place after they have chosen a BillPay payment method and attempt to finalize their order. In the case of a an approval (status
=“APPROVED”) from BillPay, the order can be placed. In the case of a rejection (status
=“DENIED”), the customer is to be presented with the appropriate message in the front-end (customermessage
in the BillPay response) and offered of an alternate payment method.
XML Requests Used | Meaning | Time of execution | Service URL |
---|---|---|---|
preauthorize (manualcapture =“0”) |
An identity and credit check will be performed | After the customer has selected the payment method and clicked to finalize their order. When approved, the order is finalized with this request. | [Base-URL]/preauthorize |
“Two Step Order Creation”
Using the “Two-Step” order model, the identity and credit check of the customer is performed after they have chosen a BillPay payment method and before their order is finalized. In this scenario, you can check to see if the customer can pay using BillPay before they attempt to finalize their order. In the case of a rejection (status
=“DENIED”), the customer is to be presented with the appropriate message in the front-end (customermessage
in the BillPay response) and offered of an alternate payment method. In the case of an approval (status
=“APPROVED”) from BillPay, the customer can proceed to the order overview page to finalize their order. If a customer has the ability to make any changes to their order that impact the order value on the order overview page - like entering a coupon code or changing the shipping method, in the event of such a change, a new preauthorize request must be sent.
XML service | Meaning | Time of execution | Service URL |
---|---|---|---|
preauthorize (manualcapture =“1”) |
An identity and credit check will be performed | After the customer has selected the payment method in the order process. When approved, the order is not finalized with this request. | [Base-URL]/preauthorize |
capture | Creation of the order in the BillPay system | After the final order | [Base-URL]/capture |
PayLater with a Downpayment
In order for customers to improve their credit score, we offer a special feature with our “PayLater” (DEU) payment method. Customers have the ability to make a “down payment” via our partner giropay. By offering this option, the acceptance rate for PayLater increases.
Customers that are conditionally accepted if they make a downpayment, are redirected to the giropay banking gateway, where they can use their known and trusted online banking environment to transfer a portion of the order total in real-time. Following the successful transfer, the customer returns to the checkout and the order can be finalized.
Prescore
With the prescore request, merchants can filter the payment options shown to their customers before they are displayed. This prevents the customer from being presented a negative alert message in the case of a rejection, allowing for a more positive user-experience and dramatically increasing the conversion rate. This option requires every customer to undergo a credit and identity check before landing on the payment method selection page. This service can be viewed as an alternative to scoring a customer after he/she has chosen to use a Billpay payment method. It is necessary for the customer to actively accept an opt-in (check a check box), acknowledging they have read and accept the BillPay terms and conditions, privacy statement, and consent to an identity and credit check.
Only one scoring method, prior to or post selection of the payment method can be used at a time for a given portal.
The response parameters are only valid as long as all of the input parameters sent with the prescore request remain unchanged. As soon as the customer changes his or her personal data or the cart content, the prescore request must be sent again.
Request
Data Node
<data
requesttype="PRESCORE"
apiversion="2.0.0"
originofsale="o">
<!-- additional request specific data -->
</data>
prescoreRequest prescoreRequest = new PrescoreRequest();
prescoreRequest
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PrescoreFactory;
$prescoreRequest = PrescoreFactory::create();
$prescoreRequest
->setOriginOfSaleOnline();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
requesttype | + | string | PRESCORE | Type of request |
tcaccepted | + | bool | 0/1 | Boolean flag that indicates if the customer has accepted the BillPay terms of service / the data protection policy |
apiversion | + | string | 2.0.0 | BillPay API Version |
originofsale | + | string | A..1 | Identifier for the point of origin of the purchase. u: Unknown o: Online shop p: Offline / POS t: Telesales / Call Center |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
prescoreRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
<?php
$prescoreRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Customer Details Node (customer billing address)
<customer_details
customerid="123456"
customertype="e"
salutation="Herr"
title=""
firstname="Thomas"
lastname="Testkunde"
street="Tinnowitzer Straße 1"
streetnumber=""
addressaddition=""
zipcode="10115"
city="Berlin"
country="DEU"
email="anyone@anymail.de"
phone="03012345678"
cellphone=""
dateofbirth="19741012"
language="de"
ipaddress="80.111.120.1"
customergroup="p" />
prescoreRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
.setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1975/10/12"))
.setEmail("anymail@gmx.de")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Tinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
<?php
$customer = $prescoreRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
customerid | - | string | AN..40 | Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/). This ID is displayed in the merchant settlement file. |
customertype | - | string | A..1 | Type of customer g: Guest e: Existing Customer n: New Customer |
salutation | + | string | Default: See addendum Salutations |
|
title | - | string | AN..20 | Academic title (e.g. “Dr.”) |
firstname | + | string | AN..40 | First name |
lastname | + | string | AN..40 | Last name |
street | + | string | AN..40 | Street |
streetnumber | - | string | AN..7 | House number |
addressaddition | - | string | AN..40 | Address addition |
zipcode | + | string | AN..7 | ZIP code |
city | + | string | AN..40 | City |
country | + | string | A..3 | Customer country code (e.g. “DEU”): ISO3166 (alpha-3) |
+ | string | AN..40 (excl. non-valid special characters) | Email address | |
phone | -* | string | AN..40 | Phone number |
cellphone | - | string | AN..40 | Mobile number |
dateofbirth | + | string | YYYYMMDD | Date of Birth - optional for business customers |
language | + | string | A..2 | Customer language (e.g. “de”): ISO3166-1 (alpha-2) |
ipaddress | + | string | IPv4 or IPv6 (IPv4-Embedded IPv6 Address) | IP address of the client |
customergroup | + | string | A..1 | Customer group p: Private b: Business |
*phone
is a mandatory field for:
1. PayLater (paymenttype
= “4”)
2. for invoice (paymenttype
= “1”) when the customer’s billing address is in the Netherlands (country
=“NLD”), and
3. for all payment methods where the customer’s billing address is in Switzerland (country
=“CHE”).
Shipping Details Node (customer shipping address)
This node contains either the boolean flag usebillingaddress
set to “true” (1) or the flag set to “false” (0) with the full alternate shipping address.
<shipping_details
usebillingaddress="1"
salutation=""
title=""
firstname=""
lastname=""
street=""
streetnumber=""
addressaddition=""
zipcode=""
city=""
country=""
phone=""
cellphone="" />
prescoreRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Tinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
<?php
/*
if the shipping address is the same as the billing address, you do not need to do anything here. If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
usebillingaddress | + | bool | 0/1 | 0: Use deviating shipping address 1: Use the given billing address identifier that indicates if the shipping address is equal to the billing address |
salutation | - | string | Default: See addendum Salutations |
|
title | - | string | AN..20 | Academic title (e.g. “Dr.”) |
firstname | - | string | AN..40 | First name |
lastname | - | string | AN..40 | Last name |
street | - | string | AN..40 | Street |
streetnumber | - | string | AN..7 | House number |
addressaddition | - | string | AN..40 | Address addition |
zipcode | - | string | AN..7 | ZIP code |
city | - | string | AN..40 | City |
country | - | string | A..3 | Customer country code (e.g. “DEU”): ISO3166 (alpha-3) |
phone | - | string | AN..40 | Phone number |
cellphone | - | string | AN..40 | Mobile number |
Company Details Node (Details about business customers)
In case you are offering goods to business customers (customertype
= “b”), additional information about the business customer needs to be sent in your request.
<company_details
name="Testfirma"
legalform="GmbH"
registernumber="HRB 122 029 B"
holdername="Testinhaber Owner"
taxnumber="DE268874183" />
prescoreRequest.getCustomer().createCompany()
.setName("Testfirma")
.setLegalForm("GmbH")
.setRegisterNumber("HRB 122 029 B")
.setTaxNumber("DE268874183")
.setCompanyProprietor("Testinhaber Owner");
<?php
$company = $customer->getCompany();
$company->setLegalFormGmbh()
->setName('Testfirma')
->setRegisterNumber('HRB 122 029 B')
->setCompanyProprietor('Testinhaber Owner')
->setTaxNumber('DE268874183');
Attribute | Required | Format | Values | Info |
---|---|---|---|---|
name | + | string | AN..200 | Registered name of the company |
legalform | + | string | Company legal form Defaults: see addendum legal forms |
|
registernumber | - | string | AN..20 | Company register number |
holdername | - | string | AN..100 | Owner’s full name |
taxnumber | - | string | Valid tax ID (DEXXXXXXXXX) |
Article Data Node (list of all order positions)
All information relating to the purchased products are collected in the article_data
node. Every unique article is represented by an individual “article” XML tag.
<article_data>
<article
articleid="1234"
articlequantity="2"
articletype="0"
articlename="Shirt"
articlecategory="Clothing"
articlesubcategory1="Van Laack"
articlepricenet="10084"
articlepricegross="12000" />
<article
articleid="2345"
articlequantity="1"
articletype="0"
articlename="Hose"
articlecategory="Clothing"
articlesubcategory1="Ralph Lauren"
articlepricenet="16807"
articlepricegross="20000" />
</article_data>
prescoreRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
prescoreRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
<?php
$cart = $prescoreRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
articleid | + | string | AN..20 | Unique article ID |
articlename | + | string | AN..50 | Article name |
articletype | + | non-negative int | N..1 | Item classification: 0: Default |
articlequantity | + | Positive int | N..7 | Article quantity |
articlepricenet | + | int | N..7 | Article net price (excluding taxes in the smallest currency unit; 1,00 EUR = 100) |
articlepricegross | + | int | N..7 | Article gross price (including taxes in the smallest currency unit; 1,00 EUR = 100) |
articlecategory | - | string | AN..50 | Article Category |
articlesubcategory1 | - | string | AN..50 | Article Sub-Category |
articlesubcategory2 | - | string | AN..50 | Article Sub-Category |
Total Node
The total
node contains the total values and order related reference information.
<total
shippingname="Express Versand"
shippingpricenet="840"
shippingpricegross="1000"
rebatenet="1681"
rebategross="2000"
orderamountnet="36134"
orderamountgross="43000"
currency="EUR" />
prescoreRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000);
prescoreRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
<?php
$shipping = $prescoreRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
shippingname | + | string | AN..50 | Shipping method name (e.g. “Express”, “Email”, etc.) |
shippingpricenet | + | non-negative int | N..7 | Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0 |
shippingpricegross | + | non-negative int | N..7 | Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0 |
rebatenet | + | non-negative int | N..7 | Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100), if none please use 0 |
rebategross | + | non-negative int | N..7 | Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100), if none please use 0 |
orderamountnet | + | Positive int | N..7 | Net value (excluding taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricenet) + shippingpricenet - rebatenet] |
orderamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross] |
currency | + | string | A..3 | 3-digit currency code of the order (e.g. “EUR”): ISO4217 |
reference | - | string | AN..40 | Unique order ID from the merchant system. This number is used as an identifier in the settlement file, as well as in subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
trackingnumber | - | string | AN..40 | Tracking number for shipment |
Fraud Detection Node
This node contains the session ID parameter that is used to identify fraudulent customers/sessions and prevent them from using the BillPay payment methods.
This serves to prevent fraud in your shop and must always have the same value as the identifier
designated in the configuration of the JavaScript widget.
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
prescoreRequest
.setSessionId("clear text session ID");
<?php
$prescoreRequest->setSessionId('session id');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
sessionid | + | string | AN..100 | A session ID (must be equal to the session ID set in the JavaScript widget configuration script) |
Response
Data Node
The data
node contains all relevant information about the scoring result. In addition to the simple decision (“APPROVED” / “DENIED”) it contains a unique BillPay transaction ID (transactionid
) that identifies the the request and result.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="PRESCORE"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage=""
status="APPROVED"
transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337">
<!-- additional response specific data -->
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
System.out.println(requestResponse.getAuthorizationStatus());
System.out.println(requestResponse.getTransactionId());
<?php
// send the request to BillPay and retrieve the response
$prescoreResponse = $prescoreRequest->send();
// get data out of the response
if ($prescoreResponse->isError()) {
echo $prescoreResponse->getStatus();
echo $prescoreResponse->getErrorCode();
echo $prescoreResponse->getMerchantMessage();
echo $prescoreResponse->getDeveloperMessage();
echo $prescoreResponse->getCustomerMessage();
} else {
echo $prescoreResponse->getStatus();
echo $prescoreResponse->getTransactionId();
}
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | PRESCORE | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. | |
status | - | string | “APPROVED” / “DENIED” | Status of the identity and credit check. Can be empty in the case of a validation error. |
transactionid | - | string | AN..50 | Unique BillPay transaction ID |
Corrected Address Node (Normalized customer address)
This node returns the normalized customer address.
<corrected_address
street="Zinnowitzer Str."
streetnumber="1"
zipcode="10115"
city="Berlin"
country="DEU" />
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
<?php
echo $prescoreResponse->getNormalizedAddress()->getStreet();
echo $prescoreResponse->getNormalizedAddress()->getStreetNumber();
echo $prescoreResponse->getNormalizedAddress()->getZipCode();
echo $prescoreResponse->getNormalizedAddress()->getCity();
echo $prescoreResponse->getNormalizedAddress()->getCountry();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
street | + | string | AN..50 | Normalized street |
streetnumber | + | string | AN..15 | Normalized house number |
zipcode | + | string | AN..7 | Normalized ZIP code |
city | + | string | AN..50 | Normalized city |
country | + | string | A..3 | Normalized country code (e.g. “DEU”): ISO3166 (alpha-3) |
Customer Restriction Node (Optional)
This node returns customer specific restrictions in relation to the order as described in the request. The inclusion of this node in the response must be enabled by BillPay.
<customer_restriction
shippingtypeobligation="IDENTITY_SHIPPING" />
System.out.println(requestResponse.getCustomerRestriction().getShippingTypeObligation());
<?php
echo $prescoreResponse->getCustomerRestriction();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
shippingtypeobligation | - | string | AN..50 | Shipping method restrictions |
Allowed Methods Node
This node contains information relating to the allowed payment methods in the case of positive response. Every unique payment method is represented by an individual “payment_method” XML node.
<allowed_methods>
<payment_method>
<name>
INVOICE_B2C
</name>
<customer_group>
p
</customer_group>
<payment_type>
1
</payment_type>
<additional_data/>
</payment_method>
<payment_method>
<name>
DIRECT_DEBIT_B2C
</name>
<customer_group>
p
</customer_group>
<payment_type>
2
</payment_type>
<additional_data/>
</payment_method>
</allowed_methods>
System.out.println(requestResponse.getAllowedPaymentOptions();
<?php
$allowed = $prescoreResponse->getAllowedPaymentMethods();
foreach($allowed as $billpaypm){
echo $billpaypm->getCustomerGroup();
echo $billpaypm->getPaymentId();
echo $billpaypm->getName();
}
Attribute | Mandatory | Type | Possible Values | Details |
---|---|---|---|---|
name | + | String | AN..50 | Payment method name |
customer_group | + | String | A..1 | Customer group p: Consumer (B2C) b: Business customer (B2B) |
payment_type | + | String | N..1 | ID of chosen payment method 1: Invoice 2: Direct Debit 3: Transaction Credit 4: PayLater |
Preauthorize
The preauthorize request is used to transmit all necessary information to perform the identity and credit check on the customer. The result of this check (either “APPROVED” or “DENIED”) will be sent back to your system in realtime and will determine whether or not the customer can use the selected BillPay payment method.
When the manualcapture
flag is set to false, in the case of a positive authorization, the order will be created in the BillPay system with the unique ID sent in the reference
parameter.
From a legal viewpoint, this is the moment BillPay acquires the rights to the debt for this specific customer and order.
Request
Data Node
<data
requesttype="PREAUTHORIZE"
tcaccepted="1"
expecteddaystillshipping="0"
manualcapture="0"
paymenttype="1"
apiversion="2.0.0"
originofsale="o">
<!-- additional request specific data -->
</data>
preauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
preauthorizeRequest
.setTermsAndConditionAccepted(true)
.setManualCapture(false)
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
preauthorizeRequest.getPaymentDetails()
.setPaymentType(PaymentType.INVOICE);
preauthorizeRequest.getShipping()
.setDaysTillShipping(0);
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PreauthorizeFactory;
$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
->acceptTermsOfUse();
$preauthorizeRequest
->setOriginOfSaleOnline()
->disableManualCapture();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
requesttype | + | string | PREAUTHORIZE | Type of request |
tcaccepted | + | bool | 0/1 | Boolean flag that indicates if the customer has accepted the BillPay terms of service / the data protection policy |
expecteddaystillshipping | + | non-negative int | Expected number days until the goods are shipped. | |
manualcapture | + | bool | 0/1 | Boolean flag that indicates if the booking is captured with the preauthorize request (flag set to “0”) or if a separate capture request is required to complete the booking (flag set to “1”). |
paymenttype | + | Positive int | N..1 | ID of the desired payment method 1: Invoice 2: Direct Debit 3: Transaction Credit 4: PayLater |
apiversion | + | string | 2.0.0 | BillPay API Version |
originofsale | + | string | A..1 | Identifier for the point of origin of the purchase. u: Unknown o: Online shop p: Offline / POS t: Telesales / Call Center |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
preauthorizeRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
<?php
$preauthorizeRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Preauth Params
This node is only required if your portal makes use of the prescoring request. If you have not contractually agreed to the implementation of prescoring, than you can ignore this data.
<preauth_params
isprescored="1"
transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337" />
preauthorizeRequest
.setPrescore("true", "1aa2fb2d-2b78-4393-bf06-be0012dda337");
<?php
$preauthorizeRequest
->setPrescoreTransactionId($transactionId);
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
isprescored | + | bool | 0/1 | Value indicates if a prescore request was previously sent for this order. 0: Request was not prescored. 1: Request was prescored. Please note: prescoring must be activated for your portal. |
transactionid | + | string | AN…50 | BillPay transaction number The transaction number is sent in the response to the prescore-request. It is used to match prescore- and preauthorize-requests. |
Customer Details Node (customer billing address)
<customer_details
customerid="123456"
customertype="e"
salutation="Herr"
title=""
firstname="Thomas"
lastname="Testkunde"
street="Tinnowitzer Straße 1"
streetnumber=""
addressaddition=""
zipcode="10115"
city="Berlin"
country="DEU"
email="anyone@anymail.de"
phone="03012345678"
cellphone=""
dateofbirth="19741012"
language="de"
ipaddress="80.111.120.1"
customergroup="p" />
preauthorizeRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
.setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1974/10/12"))
.setEmail("anyone@anymail.de")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Tinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
<?php
$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
customerid | - | string | AN..40 | Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/). This ID is displayed in the merchant settlement file. |
customertype | - | string | A..1 | Type of customer g: Guest e: Existing Customer n: New Customer |
salutation | + | string | Default: See addendum Salutations |
|
title | - | string | AN..20 | Academic title (e.g. “Dr.”) |
firstname | + | string | AN..40 | First name |
lastname | + | string | AN..40 | Last name |
street | + | string | AN..40 | Street |
streetnumber | - | string | AN..7 | House number |
addressaddition | - | string | AN..40 | Address addition |
zipcode | + | string | AN..7 | ZIP code |
city | + | string | AN..40 | City |
country | + | string | A..3 | Customer country code (e.g. “DEU”): ISO3166 (alpha-3) |
+ | string | AN..40 (excl. non-valid special characters) | Email address | |
phone | -* | string | AN..40 | Phone number |
cellphone | - | string | AN..40 | Mobile number |
dateofbirth | + | string | YYYYMMDD | Date of Birth - optional for business customers |
language | + | string | A..2 | Customer language (e.g. “de”): ISO3166-1 (alpha-2) |
ipaddress | + | string | IPv4 or IPv6 (IPv4-Embedded IPv6 Address) | IP address of the client |
customergroup | + | string | A..1 | Customer group p: Private b: Business |
*phone
is a mandatory field for PayLater (paymenttype
= “4”), for invoice (paymenttype
= “1”) when the customer’s billing address is in the Netherlands (country
=“NLD”), and for all payment methods where the customer’s billing address is in Switzerland (country
=“CHE”).
Shipping Details Node (customer shipping address)
This node contains either the boolean flag usebillingaddress
set to “true” (1) or the flag set to “false” (0) with the full alternate shipping address.
<shipping_details
usebillingaddress="1"
salutation=""
title=""
firstname=""
lastname=""
street=""
streetnumber=""
addressaddition=""
zipcode=""
city=""
country=""
phone=""
cellphone="" />
preauthorizeRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Tinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
<?php
/*
if the shipping address is the same as the billing address, you do not need to do anything here. If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
usebillingaddress | + | bool | 0/1 | 0: Use deviating shipping address 1: Use the given billing address identifier that indicates if the shipping address is equal to the billing address |
salutation | - | string | A..12 | Default: See addendum Salutations |
title | - | string | AN..20 | Academic title (e.g. “Dr.”) |
firstname | - | string | AN..40 | First name |
lastname | - | string | AN..40 | Last name |
street | - | string | AN..40 | Street |
streetnumber | - | string | AN..7 | House number |
addressaddition | - | string | AN..40 | Address addition |
zipcode | - | string | AN..7 | ZIP code |
city | - | string | AN..40 | City |
country | - | string | A..3 | Customer country code (e.g. “DEU”): ISO3166 (alpha-3) |
phone | - | string | AN..40 | Phone number |
cellphone | - | string | AN..40 | Mobile number |
Company Details Node (Details about business customers)
In case you are offering goods to business customers (customertype
= “b”), additional information about the business customer needs to be collected.
<company_details
name="Testfirma"
legalform="GmbH"
registernumber="HRB 122 029 B"
holdername="Testinhaber Owner"
taxnumber="DE268874183" />
preauthorizeRequest.getCustomer().createCompany()
.setName("Testfirma")
.setLegalForm("GmbH")
.setRegisterNumber("HRB 122 029 B")
.setTaxNumber("DE268874183")
.setCompanyProprietor("Testinhaber Owner");
<?php
$company = $customer->getCompany();
$company->setLegalFormGmbh()
->setName('Testfirma')
->setRegisterNumber('HRB 122 029 B')
->setCompanyProprietor('Testinhaber Owner')
->setTaxNumber('DE268874183');
Attribute | Required | Format | Values | Info |
---|---|---|---|---|
name | + | string | AN..200 | Registered name of the company |
legalform | + | string | Company legal form Defaults: see addendum legal forms |
|
registernumber | - | string | AN..20 | Company register number |
holdername | - | string | AN..100 | Owner’s full name |
taxnumber | - | string | Valid tax ID (DEXXXXXXXXX) |
Article Data Node (list of all order positions)
All information relating to the purchased products are collected in the article_data
node. Every unique article is represented by an individual “article” XML tag.
<article_data>
<article
articleid="1234"
articlequantity="2"
articletype="0"
articlename="Shirt"
articlecategory="Clothing"
articlesubcategory1="Van Laack"
articlepricenet="10084"
articlepricegross="12000" />
<article
articleid="2345"
articlequantity="1"
articletype="0"
articlename="Hose"
articlecategory="Clothing"
articlesubcategory1="Ralph Lauren"
articlepricenet="16807"
articlepricegross="20000" />
</article_data>
preauthorizeRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
<?php
$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
articleid | + | string | AN..20 | Unique article ID |
articlename | + | string | AN..50 | Article name |
articletype | + | non-negative int | N..1 | Item classification: 0: Default |
articlequantity | + | Positive int | N..7 | Article quantity |
articlepricenet | + | int | N..7 | Article net price (excluding taxes in the smallest currency unit; 1,00 EUR = 100) |
articlepricegross | + | int | N..7 | Article gross price (including taxes in the smallest currency unit; 1,00 EUR = 100) |
articlecategory | - | string | AN..50 | Article Category |
articlesubcategory1 | - | string | AN..50 | Article Sub-Category |
articlesubcategory2 | - | string | AN..50 | Article Sub-Category |
Bank Account Node (Customer Bank Info)
The bank_account
node is only processed when direct debit or PayLater is the selected BillPay payment method. This is the case if parameter paymenttype
has values “2” or “4”. Otherwise the bank data is ignored.
<bank_account
accountholder="Thomas Testkunde"
accountnumber="DE12500105170648489890"
sortcode="" />
preauthorizeRequest.getPaymentDetails()
.createBankAccount()
.setAccountHolder("Thomas Testkunde")
.setAccountNumber("DE12500105170648489890");
<?php
$preauthorizeRequest->getBankAccount()
->setAccountHolder('Thomas Testkunde')
->setAccountNumber('DE12500105170648489890')
->setSortCode('');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
accountholder | + (if paymentType in {2,4) | string | AN..100 | First and last name of account holder |
accountnumber | + (if paymentType in {2,4}) | int | AN..30 | IBAN - International Bank Account Number |
sortcode | + (if paymentType in {2,4} AND the IBAN does not begin with DE ) | int | AN..11 | BIC - Bank Identifier Code |
Total Node
The total
node contains the total values and order related reference information.
<total
shippingname="Express Versand"
shippingpricenet="840"
shippingpricegross="1000"
rebatenet="1681"
rebategross="2000"
orderamountnet="36134"
orderamountgross="43000"
currency="EUR"
reference="1519088641"
merchantinvoicenumber="1234567"
trackingnumber="ABZ12398892131" />
preauthorizeRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000)
.setTrackingNumber("ABZ12398892131");
preauthorizeRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.setInvoiceNumber("1234567")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
<?php
$shipping = $preauthorizeRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
shippingname | + | string | AN..50 | Shipping method name (e.g. “Express”, “Email”, etc.) |
shippingpricenet | + | non-negative int | N..7 | Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0 |
shippingpricegross | + | non-negative int | N..7 | Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0 |
rebatenet | + | non-negative int | N..7 | Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100), if none please use 0 |
rebategross | + | non-negative int | N..7 | Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100), if none please use 0 |
orderamountnet | + | Positive int | N..7 | Net value (excluding taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricenet) + shippingpricenet - rebatenet] |
orderamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross] |
currency | + | string | A..3 | 3-digit currency code of the order (e.g. “EUR”): ISO4217 |
reference | - | string | AN..40 | Unique order ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
merchantinvoicenumber | - | string | AN..40 | Unique invoice number from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
trackingnumber | - | string | AN..40 | Tracking ID for this order shipment |
Fraud Detection Node
This node contains the session ID parameter that is used to identify fraudulent customers/sessions and prevent them from using the BillPay payment methods.
This serves to prevent fraud in your shop and must always have the same value as the identifier
designated in the configuration of the JavaScript widget.
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
preauthorizeRequest
.setSessionId("clear text session ID");
<?php
$preauthorizeRequest->setSessionId('session id');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
sessionid | + | string | AN..100 | A session ID (must be equal to the session ID set in the JavaScript widget configuration script) |
Rate Request Node
For the payment methods PayLater / Ratenkauf (paymenttype
=“4”) some additional parameters have to be passed to the BillPay system.
These additional parameters describe the instalment plan itself. The values are set and passed along in your checkout form by our widget when the customer
selects their preferred payment plan duration and proceeds through your checkout.
<rate_request ratecount="6" terminmonths="6" totalamountgross="46883" />
preauthorizeRequest.getPaymentDetails().createInstalment()
.setRateCount(6)
.setTermInMonths(6)
.setTotalAmountGross(46883);
<?php
$payment->setRateCount('6')
->setRateTerm('6')
->setTotal('46883');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
ratecount | + | int | N..2 | Number of instalments to be paid during the term. This is the billpay[paylater_instalments_count] value passed by the widget. |
terminmonths | + | int | N..2 | Term of the instalment plan. This is the billpay[paylater_duration] value passed by the widget. |
totalamountgross | + | Positive int | N..7 | Total amount of the instalments plan including the interest / PayLater fee. This is the billpay[paylater_total_amount] value passed by the widget. |
Async Capture Request Node - for our prepayment process
For the payment methods PayLater, BillPay offers a unique “prepayment” feature, which allows certain customers that would ordinarily be denied customers, the ability to complete their purchase, provided they pay a small percentage of the order total upfront (via the Giropay online banking gateway).
This node contains the URLs the customer will be redirected to to perform the online transfer as well as the URL for the asynchronous BillPay server response.
<async_capture_request>
<redirect_url><![CDATA[http://url1.de/redirect]]></redirect_url>
<notify_url><![CDATA[http://url1.de/notify]]></notify_url>
</async_capture_request>
preauthorizeRequest
.setRedirectUrl("http://url1.de/redirect")
.setNotifyUrl("http://url1.de/notify");
<?php
$payment->setRedirectUrl('www.redirect.de')
->setNotifyUrl('www.notify.de');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
redirect_url | + | string | AN | Shop-sided result page after successful / failed prepayment. |
notify_url | + | string | AN | Shop-sided web service URL for async BillPay response. |
Response
Data Node
The data
node contains all relevant information about the scoring result. In addition to the pure result (“APPROVED” / “DENIED”) it contains a unique
BillPay transaction ID (transactionid
) that identifies the the request and result.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="PREAUTHORIZE"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage=""
status="APPROVED"
transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337">
<!-- additional response specific data -->
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
System.out.println(requestResponse.getAuthorizationStatus());
System.out.println(requestResponse.getTransactionId());
<?php
// send the request to BillPay and retrieve the response
$preauthorizeResponse = $preauthorizeRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getErrorCode();
echo $preauthorizeResponse->getMerchantMessage();
echo $preauthorizeResponse->getDeveloperMessage();
echo $preauthorizeResponse->getCustomerMessage();
} else {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getTransactionId();
}
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | PREAUTHORIZE | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. | |
status | - | string | “APPROVED” / “DENIED” | Status of the identity and credit check. Can be empty in the case of a validation error. |
transactionid | - | string | AN..50 | Unique BillPay transaction ID |
Corrected Address Node (Normalized customer address)
This node returns the normalized customer address.
<corrected_address
street="Zinnowitzer Str."
streetnumber="1"
zipcode="10115"
city="Berlin"
country="DEU" />
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
<?php
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
street | + | string | AN..50 | Normalized street |
streetnumber | + | string | AN..15 | Normalized house number |
zipcode | + | string | AN..7 | Normalized ZIP code |
city | + | string | AN..50 | Normalized city |
country | + | string | A..3 | Normalized country code (e.g. “DEU”): ISO3166 (alpha-3) |
Customer Restriction Node - optional
This node returns customer specific restrictions in relation to the order as described in the request. The inclusion of this node in the response must be enabled by BillPay.
<customer_restriction
shippingtypeobligation="DHL Ident Verfahren"/>
System.out.println(requestResponse.getCustomerRestriction().getShippingTypeObligation());
<?php
echo $preauthorizeResponse->getCustomerRestriction();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
shippingtypeobligation | - | string | AN..50 | Shipping method restrictions |
Invoice Bank Account Node only for invoice (paymenttype
=“1”) and transaction credit in Switzerland (paymenttype
=“3”)
This node returns the BillPay bank account data to be used by the customer when paying for their order. This information must be parsed and printed on the invoice document the customers receive with their documents.
If it is not possible to save the invoice reference from the BillPay API response, it can also be produced according to the following schema: BP(Merchant’s order code was passed on to the API)/(Merchant-ID at BillPay) Example: BP1519088641/9999 The merchant’s order code is 1519088641 and ID for this merchant at BillPay is 9999.
<invoice_bank_account
activationperformed="0"
accountholder="BillPay GmbH"
accountnumber="DE07312312312312312"
bankcode="BELADEBEXXX"
bankname="Sparkasse Berlin"
invoiceduedate=""
invoicereference="BP1519088641/9999" />
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $preauthorizeResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
activationperformed | + | bool | 0/1 | If the order is activated (payment due date set) |
accountholder | + | string | AN..255 | Account holder |
accountnumber | + | string | AN..40 | BillPay IBAN - International Bank Account Number |
bankcode | + | string | AN..16 | BillPay BIC - Bank Identifier Code |
bankname | + | string | AN..255 | Name of the BillPay bank |
invoiceduedate | + | string | N..8 | Payment due date in the format: YYYYMMDD |
invoicereference | + | string | AN..255 | Transaction purpose |
esrreference | - | string | AN | Reference number for Swiss payment/deposit slips |
esrcodeline | - | string | AN | Bank code for Swiss payment/deposit slips |
Invoice Numbers Node
This node is returned if BillPay sends the invoice to customers for the merchants.
<assigned_invoice_number>
<invoice_number
invoiceid="REBP1234/1700186R1"
billpayinvoicenumber="1519088641#1" />
</assigned_invoice_number>
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);
System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
invoice_number | + | Child node of the assigned_invoice_number node | ||
↳invoiceid | + | string | AN..255 | Unique ID number that appears on the invoice that is sent to the customer. |
↳billpayinvoicenumber | + | string | AN..40 | Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
Instalment Details Node - only for Transction Credit (paymenttype
= “3”) and PayLater (paymenttype
= “4”)
In this node, BillPay returns information related to the instalment plan.
Paylater (paymenttype
= “4”)
<instalment_details>
<instl_plan numinst="6">
<calc>
<duration_in_months>
6
</duration_in_months>
<fee_percent>
6.00
</fee_percent>
<fee_total>
2520
</fee_total>
<total_pymt>
45520
</total_pymt>
<eff_anual>
24.21
</eff_anual>
<nominal>
20.57
</nominal>
</calc>
<instl_list>
<instl date="20160531" type="immediate">
3520
</instl>
<instl date="20160630" type="first">
7000
</instl>
<instl date="20160731" type="date">
7000
</instl>
<instl date="20160831" type="date">
7000
</instl>
<instl date="20160930" type="date">
7000
</instl>
<instl date="20161031" type="date">
7000
</instl>
<instl date="20161130" type="date">
7000
</instl>
</instl_list>
</instl_plan>
</instalment_details>
InstalmentPlan instalmentPlan = requestResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
<?php
$instalmentDetails = $preauthorizeResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
instl_plan | + | Parent node - this node only appears for paymenttype =“4” (PayLater) |
||
numinst | + | Positive int | N | Number of instalments |
calc | + | Child node of the instl_plan node | ||
↳duration_in_months | + | int | N | Duration of the payment plan in months |
↳fee_percent | + | decimal | PayLater fee (%): between 0.00 and 100.00 | |
↳fee_total | + | non-negative int | N | Total PayLater fees |
↳total_pymt | + | Positive int | N | Total amount of the PayLater order (including the fees) |
↳eff_anual | + | decimal | Annual effective interest rate (%) between 0.00 and 100.00 |
|
↳nominal | + | decimal | Annual nominal interest rate (%) between 0.00 and 100.00 |
|
instl_list | + (node) | Child node of the instl_plan node. | ||
↳instl | + (node) | Child node of the instl_list node. | ||
↳date | + | DATE | YYYYMMDD | Date of the instalment |
↳type | + | string | AN | Type of Installment („immediate“, „first“, „date“, „fee“) |
Transaction Credit (paymenttype
= “3”)
<instalment_details>
<option ratecount="6" term="6">
<calculation>
<base>
14345
</base>
<cart>
14444
</cart>
<surcharge>
420
</surcharge>
<intermediate>
14765
</intermediate>
<total>
15039
</total>
<interest>
49
</interest>
<anual>
1542
</anual>
<fee>
175
</fee>
</calculation>
<dues>
<due date="" type="first">
2739
</due>
<due date="" type="following">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
</dues>
</option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $preauthorizeResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
option | + | Parent node - this node only appears for paymenttype =“3” (Transaction Credit) |
||
ratecount | + | Positive int | N | Number of instalments |
terminmonths | + | Positive int | N | Duration of financing plan in months |
calculation | + | Child node of the option node | ||
↳base | + | Positive int | N | Portion of the order that is being financed (order value less shipping fees and other charges) |
↳cart | + | Positive int | N | Total value of the order including shipping, but excluding the financing interest |
↳surcharge | + | Positive int | N | Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000) |
↳intermediate | + | Positive int | N | Base amount plus the surcharge for the financing |
↳total | + | Positive int | N | Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000) |
↳interest | + | Positive int | N | Monthly interest surcharge in % (e.g: 59 = 0.59%) |
↳anual | + | Positive int | N | Annual percentage rate in % (e.g: 1614 = 16,14%) |
↳fee | + | Positive int | N | Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000) |
dues | + | Child node of the option node | ||
↳due | + | Child node of the option node. N…7 | ||
↳date | + | DATE | YYYYMMDD | Due date of the instalment |
↳type | + | string | AN | Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“) |
Async Capture Parameters Node - only relevant for PayLater
This node returns the necessary linking and redirects for the proper implementation of down-payments via GiroPay.
<async_capture_params>
<rate_plan_url></rate_plan_url>
<external_redirect_url></external_redirect_url>
</async_capture_params>
System.out.println(requestResponse.getForwardingDetails().getRatePlanUrl());
System.out.println(requestResponse.getForwardingDetails().getExternalRedirectUrl());
<?php
$asynchCapture = $preauthorizeResponse->getForwardingDetails();
echo $asynchCapture->getRatePlanUrl();
echo $asynchCapture->getExternalRedirectUrl();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
rate_plan_url | + | string | AN..255 | Link to rate plan. |
external_redirect_url | + | string | AN..40 | External link to GiroPay to execute pre-payment. |
Campaign Node (only relevant for PayLater and down-payments with GiroPay)
This node contains information to be displayed to your shop visitors if their PayLater order request has been approved on the condition of a down-payment via GiroPay.
<campaign>
<type></type>
<display_text></display_text>
<display_image_url></display_image_url>
</campaign>
System.out.println(requestResponse.getForwardingDetails().getType());
System.out.println(requestResponse.getForwardingDetails().getDisplayText());
System.out.println(requestResponse.getForwardingDetails().getImageUrl());
<?php
echo $asynchCapture->getType();
echo $asynchCapture->getText();
echo $asynchCapture->getImageUrl();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
type | + | string | AN..255 | Defines what the text and image are for |
display_text | + | string | AN | Text to be displayed to your customers informing them of the down-payment option. |
display_image_url | + | string | AN | Image to be displayed to your customers informing them of the down-payment option. |
Capture
The capture request is used to complete the order when a two-step capture process is being implemented (the manualcapture
attribute is set to 1 in the preauthorize request). Legally speaking, it is with the successful completion of the capture request, that the customer’s debt to the merchant is transferred from the merchant to BillPay.
Request
Data Node
<data
requesttype="CAPTURE"
apiversion="2.0.0">
<!-- Request Data -->
</data>
Attribute | Data Type | Values | Info |
---|---|---|---|
requesttype | string | CAPTURE | Type of request |
apiversion | string | 2.0.0 | BillPay API Version |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
captureRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
<?php
$captureRequest = CaptureFactory::create();
$captureRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Capture Params Node
This node contains the the unique BillPay transaction ID (retrieved from the original preauthorization server response) and the desired order reference.
<capture_params
transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337"
orderamountgross="43230"
currency="EUR"
reference="1519088641"
merchantinvoicenumber="1234567"
customerid="123456789" />
captureRequest
.setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
.setMerchantInvoiceNumber("1234567");
captureRequest.getCustomer()
.setCustomerId("123456789");
captureRequest.getCart()
.setReference("1519088641")
.setCurrencyIso3("EUR")
.setOrderAmountGross(43230);
<?php
$captureRequest->setReference('1519088641')
->setPortalId(9999)
->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
->setMerchantInvoiceNumber('1234567')
->getCart()
->setOrderAmountGross(43230)
->setCurrencyIso3('EUR')
->getCustomer()
->setId('123456789');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
transactionid | + | string | AN..50 | Unique BillPay transaction ID for this order - returned in the preauthorize response |
orderamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross] |
currency | + | string | A..3 | 3-digit currency code of the order (e.g. “EUR”): ISO4217 |
reference | - | string | AN..40 | Unique order ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
merchantinvoicenumber | - | string | AN..40 | Unique invoice number from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
customerid | - | string | AN.40 | Customer ID in the merchant system. This ID is displayed in the merchant settlement file. Allowed characters are: 0-9, a-z, A-Z, .,-,_,/ |
Response
With the capture response, you can determine whether or not the order has been successfully completed at BillPay based upon the returned error code. When the error_code
=“0”, the order has been placed in the BillPay system.
Data Node
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="CAPTURE"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage="">
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$captureResponse = $captureRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $captureResponse->getStatus();
echo $captureResponse->getErrorCode();
echo $captureResponse->getMerchantMessage();
echo $captureResponse->getDeveloperMessage();
echo $captureResponse->getCustomerMessage();
} else {
echo $captureResponse->getStatus();
}
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | CAPTURE | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. |
Customer Restriction Node - optional
This node returns customer specific restrictions in relation to the order as described in the request. The inclusion of this node in the response must be enabled by BillPay.
<customer_restriction
shippingtypeobligation="DHL Ident Verfahren"/>
System.out.println(requestResponse.getCustomerRestriction().getShippingTypeObligation());
<?php
echo $captureResponse->getCustomerRestriction();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
shippingtypeobligation | - | string | AN..50 | Shipping method restrictions |
Invoice Bank Account Node only for invoice (paymenttype
=“1”) and transaction credit in Switzerland (paymenttype
=“3”)
This node returns the BillPay bank account data to be used by the customer when paying for their order. This information must be parsed and printed on the invoice document the customers receive with their documents.
<invoice_bank_account
activationperformed="0"
accountholder="BillPay GmbH"
accountnumber="DE07312312312312312"
bankcode="BELADEBEXXX"
bankname="Sparkasse Berlin"
invoiceduedate="20170813"
invoicereference="BP1519088641/9999" />
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $captureResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
activationperformed | + | bool | 0/1 | If the order is activated (payment due date set) |
accountholder | + | string | AN..255 | Account holder |
accountnumber | + | string | AN..40 | BillPay IBAN |
bankcode | + | string | AN..16 | BillPay BIC |
bankname | + | string | AN..255 | Name of the BillPay bank |
invoiceduedate | + | string | N..8 | Payment due date in the format: YYYYMMDD |
invoicereference | + | string | AN..255 | Transaction purpose |
esrreference | - | string | AN | Reference number for Swiss payment/deposit slips |
esrcodeline | - | string | AN | Bank code for Swiss payment/deposit slips |
Invoice Numbers Node
This node is returned if BillPay sends the invoice to customers for the merchants.
<assigned_invoice_number>
<invoice_number
invoiceid="REBP1234/1700186R1"
billpayinvoicenumber="1519088641#1" />
</assigned_invoice_number>
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);
System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $captureResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
invoice_number | + | Child node of the assigned_invoice_number node | ||
↳invoiceid | + | string | AN..255 | Unique ID number that appears on the invoice that is sent to the customer. |
↳billpayinvoicenumber | + | string | AN..40 | Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
Instalment Details Node - only for Transction Credit (paymenttype
= “3”) and PayLater (paymenttype
= “4”)
In this node, BillPay returns information related to the instalment plan.
Paylater (paymenttype
= “4”)
<instalment_details>
<instl_plan numinst="6">
<calc>
<duration_in_months>
6
</duration_in_months>
<fee_percent>
6.00
</fee_percent>
<fee_total>
2520
</fee_total>
<total_pymt>
45520
</total_pymt>
<eff_anual>
24.21
</eff_anual>
<nominal>
20.57
</nominal>
</calc>
<instl_list>
<instl date="20160531" type="immediate">
3520
</instl>
<instl date="20160630" type="first">
7000
</instl>
<instl date="20160731" type="date">
7000
</instl>
<instl date="20160831" type="date">
7000
</instl>
<instl date="20160930" type="date">
7000
</instl>
<instl date="20161031" type="date">
7000
</instl>
<instl date="20161130" type="date">
7000
</instl>
</instl_list>
</instl_plan>
</instalment_details>
InstalmentPlan instalmentPlan = requestResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
<?php
$instalmentDetails = $captureResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
instl_plan | + | Parent node - this node only appears for paymenttype =“4” (PayLater) |
||
numinst | + | Positive int | N | Number of instalments |
calc | + | Child node of the instl_plan node | ||
↳duration_in_months | + | int | N | Duration of the payment plan in months |
↳fee_percent | + | decimal | PayLater fee (%) between 0.00 and 100.00 |
|
↳fee_total | + | non-negative int | N | Total PayLater fees |
↳total_pymt | + | Positive int | N | Total amount of the PayLater order (including the fees) |
↳eff_anual | + | decimal | Annual effective interest rate (%) between 0.00 and 100.00 |
|
↳nominal | + | decimal | Annual nominal interest rate (%) between 0.00 and 100.00 |
|
instl_list | + (node) | Child node of the instl_plan node. | ||
↳instl | + (node) | Child node of the instl_list node. | ||
↳date | + | DATE | YYYYMMDD | Date of the instalment |
↳type | + | string | AN | Type of Installment („immediate“, „first“, „date“, „fee“) |
Transaction Credit (paymenttype
= “3”)
<instalment_details>
<option ratecount="6" term="6">
<calculation>
<base>
14345
</base>
<cart>
14444
</cart>
<surcharge>
420
</surcharge>
<intermediate>
14765
</intermediate>
<total>
15039
</total>
<interest>
49
</interest>
<anual>
1542
</anual>
<fee>
175
</fee>
</calculation>
<dues>
<due date="" type="first">
2739
</due>
<due date="" type="following">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
</dues>
</option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $captureResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
option | + | Parent node - this node only appears for paymenttype =“3” (Transaction Credit) |
||
ratecount | + | Positive int | N | Number of instalments |
terminmonths | + | Positive int | N | Duration of financing plan in months |
calculation | + | Child node of the option node | ||
↳base | + | Positive int | N | Portion of the order that is being financed (order value less shipping fees and other charges) |
↳cart | + | Positive int | N | Total value of the order including shipping, but excluding the financing interest |
↳surcharge | + | Positive int | N | Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000) |
↳intermediate | + | Positive int | N | Base amount plus the surcharge for the financing |
↳total | + | Positive int | N | Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000) |
↳interest | + | Positive int | N | Monthly interest surcharge in % (e.g: 59 = 0.59%) |
↳anual | + | Positive int | N | Annual percentage rate in % (e.g: 1614 = 16,14%) |
↳fee | + | Positive int | N | Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000) |
dues | + | Child node of the option node | ||
↳due | + | Child node of the option node. N…7 | ||
↳date | + | DATE | YYYYMMDD | Due date of the instalment |
↳type | + | string | AN | Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“) |
Managing an Order
Request Overview
XML service | Meaning | Time of execution | Service URL |
---|---|---|---|
Activation | Invoice: Setting of the payment due date; Direct Debit/PayLater: Initialization of the debit process | When generating the invoice; usually this action is triggered by a backend workflow or scheduled task/cron job. | [Base-URL]/invoiceCreated |
Cancellation | A full cancellation of the existing order which leaves the order value at 0 €. | Usually this action is triggered by a backend workflow or scheduled task/cron job. | [Base-URL]/cancel |
Editing the order | Any change in the content of the existing order or the included fees/rebates of the order. | Usually triggered when elements of the order that impact the overall cost have changed or the order has been cancelled, but a cancellation fee remains. | [Base-URL]/editCartContent |
Updating the order ID | Update the order ID (reference number). Used in cases where the order is completed before the order reference number is available/known. | Order process; after the order is placed in the shop | [Basis-URL]/updateOrder |
Get the bank details for payment | Only for invoice orders. Retrieve the payment details for a given order for display on the order invoice | From the backend, in cases where the bank details can’t be used/saved from the capture/invoiceCreated response. | [Basis-URL]/getBillPayBankData |
Invoice Creation
The “invoiceCreated” request is used to set the customer’s payment due date (“invoice” and “transaction credit CHE”) / start the debit process (“Direct Debit” and “PayLater”). This process is called the “activation” of the debt and has to be triggered for each order prior to the invoice being printed. Only if the BillPay XML service response indicates no error (errorcode
=“0”), is all the necessary data for the invoice document available.
For the payment methods Direct Debit and PayLater, this process will set the debit date for the funds to be drawn from the customer’s bank account.
BillPay also offers merchants the ability to split ship their orders for the payment methods invoice and direct debit. This is an option that needs to be activated by BillPay.
Request
Data Node
<data
requesttype="INVOICE_CREATED"
apiversion="2.0.0">
<!-- Request Data -->
</data>
Attribute | Data Type | Values | Info |
---|---|---|---|
requesttype | string | INVOICE_CREATED | Type of request |
apiversion | string | 2.0.0 | BillPay API Version |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
invoiceCreatedRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
<?php
$invoiceRequest = InvoiceCreatedFactory::create();
$invoiceRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Invoice Params Node
<invoice_params
invoiceamountnet="19327"
invoiceamountgross="23000"
is_partial="0"
rebatenet="1681"
rebategross="2000"
shippingname="Express Versand"
shippingpricenet="840"
shippingpricegross="1000"
currency="EUR"
reference="1773673332"
deliverydelayindays="0"
merchantinvoicenumber="1234567"
trackingnumber="ABZ12398892131" />
invoiceCreatedRequest
.setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
.setMerchantInvoiceNumber("1234567")
.setIsPartial(0)
.setDeliveryDelayInDays(0);
invoiceCreatedRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000)
.setTrackingNumber("ABZ12398892131");
invoiceCreatedRequest.getCart()
.setReference("1519088641")
.setInvoiceNumber("1234567")
.setCurrencyIso3("EUR")
.setOrderAmountGross(23000)
.setOrderAmountNet(19327);
<?php
$invoice = $invoiceRequest->getInvoice();
$invoice->setDeliveryDelayInDays(0)
->isPartialActivation(0)
->setMerchantInvoiceNumber('1234567');
$invoice->getShipping()
->setName('shipping')
->setPriceGross('1000')
->setPriceNet('950')
->setTrackingNumber('ABZ12398892131');
$invoice->getCart()
->setOrderAmountGross('23000')
->setOrderAmountNet('19327')
->setCurrencyIso3('EUR')
->createAndAddRebate()
->setPriceGross('2000')
->setPriceNet('1681');
Attribute | Required | Data Type | Possible values | Info |
---|---|---|---|---|
invoiceamountnet | - | Positive int | N..7 | Net value (excluding taxes) of the order total (1,00 EUR = 100) |
invoiceamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) |
ispartial | + | boolean | 0/1 | 0: Shipping/Activation of the full order 1: Partial shipment / partial activation |
rebatenet | - | non-negative int | N..7 | Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100) |
rebategross | - | non-negative int | N..7 | Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100) |
shippingname | - | string | AN..50 | Shipping method name (e.g. “Express”) |
shippingpricenet | - | non-negative int | N..7 | Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100) |
shippingpricegross | - | non-negative int | N..7 | Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100) |
currency | + | string | A..3 | 3-digit currency code of the order (e.g. “EUR”): ISO4217 |
reference | + | string | AN..40 | Unique order ID from the merchant system. This number is used as an identifier in the settlement file, as well as subsequent requests to edit a order. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
merchantinvoicenumber | - | string | AN..40 | Unique invoice number from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
trackingnumber | - | string | AN..40 | Tracking ID for this order shipment |
deliverydelayindays | + | non-negative int | N..3 | Amount of days that will be added to the payment due date (e.g. in case of delayed shipping) |
Article Data Node - list of all sent articles
All information concerning the shipped products are collected in the article_data
node. Every unique article is represented by an individual “article” XML tag.
<article_data>
<article
articleid="2345"
articlequantity="1"
articlename="Hose"
articlecategory="Clothing"
articlesubcategory1="Ralph Lauren"
articlepricenet="16807"
articlepricegross="20000" />
</article_data>
invoiceCreatedRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
<?php
$invoice->getCart()->createAndAddArticle()
->setPriceGross('20000')
->setPriceNet('16807')
->setName('Hose')
->setQuantity('1')
->setId('2345')
->setCategory('Clothing')
->setFirstSubCategory('Ralph Lauren');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
articleid | + | string | AN..20 | Unique article ID |
articlename | + | string | AN..50 | Article name |
articlequantity | + | Positive int | N..7 | Article quantity |
articlepricenet | + | int | N..7 | Article net price (smallest currency unit; 1,00 EUR = 100) |
articlepricegross | + | int | N..7 | Article gross price (smallest currency unit; 1,00 EUR = 100) |
Partial Shipment / partial activation is only possible for the following payment methods:
Payment Method ID | Payment Method |
---|---|
1 | Invoice |
2 | Direct Debit |
Response
For the payment methods “invoice” and “transaction credit Switzerland”, the invoiceCreated response contains the BillPay bank account data and the payment due date to be printed on the invoice for the customer. This bank information, in combination with the payment due date and the transaction purpose, needs to be sent to the customer, so they can pay their invoice in a timely fashion.
For the payment methods “PayLater” and “Direct Debit”, these parameters have no meaning and can be ignored. Instead, a static text, as found in the “Customer Documents” must be printed on the document.
Data Node
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="INVOICE_CREATED"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage="">
<!-- weitere Antwortdaten -->
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$invoiceResponse = $invoiceRequest->send();
// get data out of the response
echo $invoiceResponse->getErrorCode();
echo $invoiceResponse->getMerchantMessage();
echo $invoiceResponse->getDeveloperMessage();
echo $invoiceResponse->getCustomerMessage();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | INVOICE_CREATED | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict |
Invoice Bank Account Node only for invoice (paymenttype
=“1”) and transaction credit in Switzerland (paymenttype
=“3”)
This node returns the BillPay bank account data to be used by the customer when paying for their order. This information should be
parsed and printed on the invoice document the customers receive with their shipment. In the case of partial activation (split shipping), the bank details and invoicereference
are the same for all invoices generated from a given order.
<invoice_bank_account
activationperformed="1"
accountholder="BillPay GmbH"
accountnumber="DE07312312312312312"
bankcode="BELADEBEXXX"
bankname="Sparkasse Berlin"
invoiceduedate="20170707"
invoicereference="BP555666777/9999"/>
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $invoiceResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
activationperformed | + | bool | 0/1 | Is the order activated (payment due date set) |
accountholder | + | string | AN..255 | Account holder |
accountnumber | + | string | AN..40 | BillPay IBAN |
bankcode | + | string | AN..16 | BillPay BIC |
bankname | + | string | AN..255 | Name of the BillPay bank |
invoiceduedate | + | string | N..8 | Payment due date in the format: YYYYMMDD |
invoicereference | + | string | AN..255 | Transaction purpose |
esrreference | - | string | AN | Reference number for Swiss payment/deposit slips |
esrcodeline | - | string | AN | Bank code for Swiss payment/deposit slips |
Invoice Numbers Node
This node is returned if BillPay sends the invoice to customers for the merchants.
<assigned_invoice_number>
<invoice_number
invoiceid="REBP1234/1700186R1"
billpayinvoicenumber="Z2I8EB#1" />
</assigned_invoice_number>
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);
System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $invoiceResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
invoice_number | + | Child node of the assigned_invoice_number node | ||
↳invoiceid | + | string | AN..255 | Unique ID number that appears on the invoice that is sent to the customer. |
↳billpayinvoicenumber | + | string | AN..40 | Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
Instalment Details Node - only for Transction Credit (paymenttype
= “3”) and PayLater (paymenttype
= “4”)
In this node, BillPay returns information related to the instalment plan.
Paylater (paymenttype
= “4”)
<instalment_details>
<instl_plan numinst="6">
<calc>
<duration_in_months>
6
</duration_in_months>
<fee_percent>
6.00
</fee_percent>
<fee_total>
2520
</fee_total>
<total_pymt>
45520
</total_pymt>
<eff_anual>
24.21
</eff_anual>
<nominal>
20.57
</nominal>
</calc>
<instl_list>
<instl date="20160531" type="immediate">
3520
</instl>
<instl date="20160630" type="first">
7000
</instl>
<instl date="20160731" type="date">
7000
</instl>
<instl date="20160831" type="date">
7000
</instl>
<instl date="20160930" type="date">
7000
</instl>
<instl date="20161031" type="date">
7000
</instl>
<instl date="20161130" type="date">
7000
</instl>
</instl_list>
</instl_plan>
</instalment_details>
InstalmentPlan instalmentPlan = requestResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
<?php
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
instl_plan | + | Parent node - this node only appears for paymenttype =“4” (PayLater) |
||
numinst | + | Positive int | N | Number of instalments |
calc | + | Child node of the instl_plan node | ||
↳duration_in_months | + | int | N | Duration of the payment plan in months |
↳fee_percent | + | decimal | PayLater fee (%) between 0.00 and 100.00 |
|
↳fee_total | + | non-negative int | N | Total PayLater fees |
↳total_pymt | + | Positive int | N | Total amount of the PayLater order (including the fees) |
↳eff_anual | + | decimal | Annual effective interest rate (%) between 0.00 and 100.00 |
|
↳nominal | + | decimal | Annual nominal interest rate (%) between 0.00 and 100.00 |
|
instl_list | + (node) | Child node of the instl_plan node. | ||
↳instl | + (node) | Child node of the instl_list node. | ||
↳date | + | DATE | YYYYMMDD | Date of the instalment |
↳type | + | string | AN | Type of Installment („immediate“, „first“, „date“, „fee“) |
Transaction Credit (paymenttype
= “3”)
<instalment_details>
<option ratecount="6" term="6">
<calculation>
<base>
14345
</base>
<cart>
14444
</cart>
<surcharge>
420
</surcharge>
<intermediate>
14765
</intermediate>
<total>
15039
</total>
<interest>
49
</interest>
<anual>
1542
</anual>
<fee>
175
</fee>
</calculation>
<dues>
<due date="" type="first">
2739
</due>
<due date="" type="following">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
</dues>
</option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
option | + | Parent node - this node only appears for paymenttype =“3” (Transaction Credit) |
||
ratecount | + | Positive int | N | Number of instalments |
terminmonths | + | Positive int | N | Duration of financing plan in months |
calculation | + | Child node of the option node | ||
↳base | + | Positive int | N | Portion of the order that is being financed (order value less shipping fees and other charges) |
↳cart | + | Positive int | N | Total value of the order including shipping, but excluding the financing interest |
↳surcharge | + | Positive int | N | Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000) |
↳intermediate | + | Positive int | N | Base amount plus the surcharge for the financing |
↳total | + | Positive int | N | Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000) |
↳interest | + | Positive int | N | Monthly interest surcharge in % (e.g: 59 = 0.59%) |
↳anual | + | Positive int | N | Annual percentage rate in % (e.g: 1614 = 16,14%) |
↳fee | + | Positive int | N | Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000) |
dues | + | Child node of the option node | ||
↳due | + | Child node of the option node. N…7 | ||
↳date | + | DATE | YYYYMMDD | Due date of the instalment |
↳type | + | string | AN | Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“) |
Cancel
Using the cancel request, an existing order can be fully cancelled and the debt in will be closed with a value of 0 €. If the customer has already transferred money or the customer’s account was already debited, the funds will be automatically returned and a notification email will be sent to the customer.
Request
Data Node
<data
requesttype="CANCEL"
apiversion="2.0.0">
<!-- Request Data -->
</data>
Attribute | Data Type | Values | Info |
---|---|---|---|
requesttype | string | CANCEL | Type of request |
apiversion | string | 2.0.0 | BillPay API Version |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
cancelRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
<?php
$cancelRequest = CancelFactory::create();
$cancelRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Cancel Params Node
<cancel_params
reference="1519088641"
orderamountgross="43000"
currency="EUR" />
cancelRequest.getCart()
.setReference("1519088641")
.setCurrencyIso3("EUR")
.setOrderAmountGross(43000);
<?php
$cancelRequest->setReference('1519088641');
$cancelRequest->getCart()
->setOrderAmountGross(43000)
->setCurrencyIso3('EUR');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
reference | + | string | AN..40 | Unique order ID from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
orderamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of all articlepricegross) + shippingpricegross - rebategross] |
currency | + | string | A..3 | 3-digit currency code of the order (e.g. “EUR”): ISO4217 |
Response
The BillPay server response for the cancel request will not return any additional fields besides the error code / error message.
Data Node
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="CANCEL"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage="">
</data>
System.out.println(cancelResponse.getErrorCode());
System.out.println(cancelResponse.getMerchantMessage());
System.out.println(cancelResponse.getDeveloperMessage());
System.out.println(cancelResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$cancelResponse = $cancelRequest->send();
// get data out of the response
echo $cancelResponse->getErrorCode();
echo $cancelResponse->getMerchantMessage();
echo $cancelResponse->getDeveloperMessage();
echo $cancelResponse->getCustomerMessage();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | CANCEL | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. |
Edit Cart Content
Using the editCartContent request, the content of an order can be adjusted. Using this call, articles can be removed or changed and fees can be reduced or increased.
Adding articles or increasing fees must follow certain predefined rules:
- If the new order value is lower than the old one, the edit will always succeed.
- If the new order value is higher than the old one, BillPay will perform a risk check for the new amount. If the risk check for the increased amount fails, the request will be rejected with the error code 105 and the order will not be adjusted.
- An increase for orders where PayLater is the payment method are not allowed.
The request itself contains the information for the new desired order. All differences between old and new order will then be added/removed.
Request
Data Node
<data
requesttype="EDIT_CART_CONTENT"
apiversion="2.0.0"
<!-- Request Data -->
</data>
Attribute | Data Type | Values | Info |
---|---|---|---|
requesttype | string | EDIT_CART_CONTENT | Type of request |
apiversion | string | 2.0.0 | BillPay API Version |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
editCartContentRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
<?php
$editCartContentRequest = EditCartContentFactory::create();
$editCartContentRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Total Node
The total
node contains all generic information about the order and all connected fees / rebates.
<total
shippingname="Express Versand"
shippingpricenet="840"
shippingpricegross="1000"
rebatenet="1681"
rebategross="2000"
orderamountnet="26050"
orderamountgross="31000"
currency="EUR"
reference="1519088641"
trackingnumber="12345" />
editCartContentRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000);
editCartContentRequest.getCart()
.setOrderAmountNet(26050)
.setOrderAmountGross(31000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
<?php
$editCartContentRequest->setReference('1519088641');
$editCartContentRequest->getShipping()
->setName('Express Versand')
->setPriceGross(1000)
->setPriceNet(840)
->setTrackingNumber('12345');
$editCartContentRequest->getCart()
->setOrderAmountNet('26050')
->setOrderAmountGross('31000')
->setCurrencyIso3('EUR');
$editCartContentRequest->getCart()->createAndAddRebate()
->setPriceGross(2000)
->setPriceNet(1681);
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
shippingname | + | string | AN..50 | Shipping method name (e.g. “Express”, “Email”, etc.) |
shippingpricenet | + | non-negative int | N..7 | Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0 |
shippingpricegross | + | non-negative int | N..7 | Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100), if none please use 0 |
rebatenet | + | non-negative int | N..7 | Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100), if none please use 0 |
rebategross | + | non-negative int | N..7 | Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100), if none please use 0 |
orderamountnet | + | Positive int | N..7 | Net value (excluding taxes) of the order total (1,00 EUR = 100) [(sum of the remaining articlepricenet) + shippingpricenet - rebatenet] |
orderamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) [(sum of the remaining articlepricegross) + shippingpricegross - rebategross] |
currency | + | string | A..3 | 3-digit currency code of the order (e.g. “EUR”): ISO4217 |
reference | + | string | AN..40 | Unique order ID from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
trackingnumber | - | string | AN..40 | Tracking ID for this order shipment |
Article Data Node (List of all ordered articles)
All information relating to the purchased products are collected in the article_data
node. Every unique article is represented by an individual XML tag.
<article_data>
<article
articleid="2345"
articlequantity="1"
articletype="0"
articlename="Hose"
articlecategory="Clothing"
articlesubcategory1="Ralph Lauren"
articlepricenet="16807"
articlepricegross="20000" />
</article_data>
editCartContentRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
<?php
$editCartContentRequest->getCart()->createAndAddArticle()
->setId(2345)
->setQuantity(1)
->setName('Hose')
->setCategory('Clothing')
->setFirstSubCategory('Ralph Lauren')
->setPriceGross('16807')
->setPriceNet('20000');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
articleid | + | string | AN..20 | Unique article ID |
articlename | + | string | AN..50 | Article name |
articlequantity | + | Positive int | N..7 | Article quantity |
articletype | + | non-negative int | N..1 | Item classification: 0: Default |
articlepricenet | + | int | N..7 | Article net price (smallest currency unit; 1,00 EUR = 100) |
articlepricegross | + | int | N..7 | Article gross price (smallest currency unit; 1,00 EUR = 100) |
Special Feature: Editing of partially shipped orders
In addition to the information described above, an invoice_list
has to be added when editing partially shipped orders.
This list references each individual partial invoice via the invoice_number
parameter. In each invoice node the details of the partial shipment are
described in an invoice_params
node. Here, total amount of the invoice, shipping costs and any kind of rebates are summed up.
It also contains the usual article_data
node to highlight what articles were shipped in that particular invoice. Please review the examples below.
Invoice List Node
<invoice_list>
<invoice merchantinvoicenumber="1234567">
<invoice_params
invoiceamountnet="19327"
invoiceamountgross="23000"
rebatenet="1681"
rebategross="2000"
shippingname="Express Versand"
shippingpricenet="840"
shippingpricegross="1000"
currency="EUR"
reference="1773673332"
trackingnumber="ABZ12398892131" />
<article_data>
<article
articleid="2345"
articlequantity="1"
articlename="Hose"
articlepricenet="16807"
articlepricegross="20000" />
</article_data>
</invoice>
</invoice_list>
Invoice invoice1 = editCartContentRequest.createAndAddInvoice("1234567")
.setTotalPriceNet(15966)
.setTotalPriceGross(19000)
.setShippingPriceNet(840)
.setShippingPriceGross(1000)
.setShippingName("shipping name")
.setRebateNet(1681)
.setRebateGross(2000);
invoice1.createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setName("Hose")
.setPriceNet(16807)
.setPriceGross(20000);
<?php
$invoice1 = $editCartContentRequest->createAndAddInvoice()
->setMerchantInvoiceNumber('1234567');
$invoice1->getCart()
->setOrderAmountNet('19327')
->setOrderAmountGross('23000')
->setCurrencyIso3('EUR');
$invoice1->getShipping()
->setName('shipping name')
->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('ABZ12398892131');
$invoice1->getCart()->createAndAddArticle()
->setId(2345)
->setQuantity(1)
->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->appendTo($editCartContentRequest->getCart()); // append to ecc request cart as well
$invoice1->getCart()->createRebate()
->setPriceGross(1010)
->setPriceNet(1009)
->appendTo($invoice1->getCart());
Attribute | Required | Data Type | Possible values | Info |
---|---|---|---|---|
merchantinvoicenumber | - | string | AN..40 | Unique invoice number from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
invoice_params | + | Child node of the invoice node | ||
↳shippingname | - | string | AN..50 | Shipping method name (e.g. “Express”) |
↳trackingnumber | - | string | AN..40 | Tracking ID for this order shipment |
↳shippingpricenet | - | non-negative int | N..7 | Net value (excluding taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100) |
↳shippingpricegross | - | non-negative int | N..7 | Gross value (including taxes) of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100) |
↳rebatenet | - | non-negative int | N..7 | Positive net value (excluding taxes) of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100) |
↳rebategross | - | non-negative int | N..7 | Positive gross value (including taxes) of all rebates, coupons and all other positions that affect the -> order total value (1,00 EUR = 100) |
↳invoiceamountnet | - | Positive int | N..7 | Net value (excluding taxes) of the order total (1,00 EUR = 100) |
↳invoiceamountgross | + | Positive int | N..7 | Gross value (including taxes) of the order total (1,00 EUR = 100) |
article_data | + | Child node of the invoice node | ||
↳article | + | Child element of the article_data node | ||
↳articleid | + | string | AN..20 | Unique article ID |
↳articlename | + | string | AN..50 | Article name |
↳articlequantity | + | Positive int | N..7 | Article quantity |
↳articlepricenet | + | int | N..7 | Article net price (smallest currency unit; 1,00 EUR = 100) |
↳articlepricegross | + | int | N..7 | Article gross price (smallest currency unit; 1,00 EUR = 100) |
Response
The server response to the editCartContent request delivers an error code (0 for success), as well as a message should the request fail.
Data Node
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="EDIT_CART_CONTENT"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage="">
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$editCartContentResponse = $editCartContentRequest->send();
// get data out of the response
echo $editCartContentResponse->getErrorCode();
echo $editCartContentResponse->getMerchantMessage();
echo $editCartContentResponse->getDeveloperMessage();
echo $editCartContentResponse->getCustomerMessage();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | EDIT_CART_CONTENT | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. |
Invoice Numbers Node
This node is returned if BillPay sends the invoice to customers for the merchants.
<assigned_invoice_number>
<invoice_number
invoiceid="REBP1234/1700186R1"
billpayinvoicenumber="1519088641#1" />
</assigned_invoice_number>
InvoiceNumber invoiceNumber = requestResponse.getInvoiceNumbers().get(0);
System.out.println(invoiceNumber.getBillpayInvoiceNumber());
System.out.println(invoiceNumber.getInvoiceId());
<?php
$invoiceNumber = $editCartContentResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
invoice_number | + | Child node of the assigned_invoice_number node | ||
↳invoiceid | + | string | AN..255 | Unique ID number that appears on the invoice that is sent to the customer. |
↳billpayinvoicenumber | + | string | AN..40 | Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
Instalment Details Node - only for Transction Credit (paymenttype
= “3”) and PayLater (paymenttype
= “4”)
In this node, BillPay returns information related to the instalment plan.
Paylater (paymenttype
= “4”)
<instalment_details>
<instl_plan numinst="6">
<calc>
<duration_in_months>
6
</duration_in_months>
<fee_percent>
6.00
</fee_percent>
<fee_total>
2520
</fee_total>
<total_pymt>
45520
</total_pymt>
<eff_anual>
24.21
</eff_anual>
<nominal>
20.57
</nominal>
</calc>
<instl_list>
<instl date="20160531" type="immediate">
3520
</instl>
<instl date="20160630" type="first">
7000
</instl>
<instl date="20160731" type="date">
7000
</instl>
<instl date="20160831" type="date">
7000
</instl>
<instl date="20160930" type="date">
7000
</instl>
<instl date="20161031" type="date">
7000
</instl>
<instl date="20161130" type="date">
7000
</instl>
</instl_list>
</instl_plan>
</instalment_details>
InstalmentPlan instalmentPlan = requestResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
<?php
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
instl_plan | + | Parent node - this node only appears for paymenttype =“4” (PayLater) |
||
numinst | + | Positive int | N | Number of instalments |
calc | + | Child node of the instl_plan node | ||
↳duration_in_months | + | int | N | Duration of the payment plan in months |
↳fee_percent | + | decimal | PayLater fee (%) between 0.00 and 100.00 |
|
↳fee_total | + | non-negative int | N | Total PayLater fees |
↳total_pymt | + | Positive int | N | Total amount of the PayLater order (including the fees) |
↳eff_anual | + | decimal | Annual effective interest rate (%) between 0.00 and 100.00 |
|
↳nominal | + | decimal | Annual nominal interest rate (%) between 0.00 and 100.00 |
|
instl_list | + (node) | Child node of the instl_plan node. | ||
↳instl | + (node) | Child node of the instl_list node. | ||
↳date | + | DATE | YYYYMMDD | Date of the instalment |
↳type | + | string | AN | Type of Installment („immediate“, „first“, „date“, „fee“) |
Transaction Credit (paymenttype
= “3”)
<instalment_details>
<option ratecount="6" term="6">
<calculation>
<base>
14345
</base>
<cart>
14444
</cart>
<surcharge>
420
</surcharge>
<intermediate>
14765
</intermediate>
<total>
15039
</total>
<interest>
49
</interest>
<anual>
1542
</anual>
<fee>
175
</fee>
</calculation>
<dues>
<due date="" type="first">
2739
</due>
<due date="" type="following">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
<due date="" type="date">
2460
</due>
</dues>
</option>
</instalment_details>
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
<?php
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
option | + | Parent node - this node only appears for paymenttype =“3” (Transaction Credit) |
||
ratecount | + | Positive int | N | Number of instalments |
terminmonths | + | Positive int | N | Duration of financing plan in months |
calculation | + | Child node of the option node | ||
↳base | + | Positive int | N | Portion of the order that is being financed (order value less shipping fees and other charges) |
↳cart | + | Positive int | N | Total value of the order including shipping, but excluding the financing interest |
↳surcharge | + | Positive int | N | Calculated surcharge for the financing (smallest currency unit! E.g. 100,00 Euro = 10000) |
↳intermediate | + | Positive int | N | Base amount plus the surcharge for the financing |
↳total | + | Positive int | N | Total payment amount (gross) for the customer (= cart + surcharge + fee) (Smallest currency unit! E.g. 100,00 Euro = 10000) |
↳interest | + | Positive int | N | Monthly interest surcharge in % (e.g: 59 = 0.59%) |
↳anual | + | Positive int | N | Annual percentage rate in % (e.g: 1614 = 16,14%) |
↳fee | + | Positive int | N | Fee for this transaction charged by Billpay (Smallest currency unit! E.g. 100,00 Euro = 10000) |
dues | + | Child node of the option node | ||
↳due | + | Child node of the option node. N…7 | ||
↳date | + | DATE | YYYYMMDD | Due date of the instalment |
↳type | + | string | AN | Position of the respective rate in the rate plan („immediate“, „first“, „date“, „fee“) |
Update Order
Request
Using the UpdateOrder request, the unique order reference can be changed. This request, if required, must be sent before the order is activated via the invoiceCreated request.
Data Node
<data
requesttype="UPDATE_ORDER"
apiversion="2.0.0">
<!-- Request Daten -->
</data>
Attribute | Data Type | Values | Info |
---|---|---|---|
requesttype | string | UPDATE_ORDER | Type of request |
apiversion | string | 2.0.0 | BillPay API Version |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
updateOrderRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
<?php
$updateOrderRequest = UpdateOrderFactory::create();
$updateOrderRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive integer | Merchant ID |
pid | + | Positive integer | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Update Params Node
This node contains the the unique BillPay transaction ID (retrieved from the original preauthorize server response) and the new desired order reference.
<update_params
transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337"
reference="1591605922_updated" />
updateOrderRequest
.setReference("1591605922_updated")
.setTransactionId("b61648a3-46a1-4771-834f-903b89510ed9");
<?php
$updateOrderRequest
->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
->setReference('1591605922_updated');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
transactionid | + | string | AN..50 | Unique BillPay transaction ID for this order |
reference | + | string | AN..40 | Unique order ID from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
ID Update List Node
This node contains all individual article IDs to be updated by the request.
<id_update_list>
<id_update articleid="2345" updateid="2345_mod"/>
</id_update_list>
updateOrderRequest.createAndAddUpdateOrder()
.setNewId("2345")
.setOldId("2345_mod");
<?php
$updateOrderRequest->getCart()->createAndAddArticleUpdate()
->setId('2345')
->setNewId('2345_mod');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
articleid | + | string | AN..40 | The original article ID |
updateid | + | string | AN..40 | The new article ID |
Response
Data Node
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="UPDATE_ORDER"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage="">
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$updateOrderResponse = $updateOrderRequest->send();
// get data out of the response
echo $updateOrderResponse->getErrorCode();
echo $updateOrderResponse->getMerchantMessage();
echo $updateOrderResponse->getDeveloperMessage();
echo $updateOrderResponse->getCustomerMessage();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | UPDATE_ORDER | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict |
Get Billpay Bank Data
Request
In the case of orders with invoice as the payment method (paymenttype
=“1”), the getBillPayBankData request will return the unique bank account information for the specified order. The response contains all information
needed for the customer to initiate their bank transfer. The response also contains the due date for the payment.
Data Node
<data
requesttype="GET_BILLPAY_BANK_DATA"
apiversion="2.0.0">
<!-- Request Data -->
</data>
Attribute | Data Type | Values | Info |
---|---|---|---|
requesttype | string | GET_BILLPAY_BANK_DATA | Type of request |
apiversion | string | 2.0.0 | BillPay API Version |
Default Params Node (Merchant Credentials)
The merchant API credentials are generated and provided by BillPay.
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
getBillPayBankDataRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
<?php
$bankDataRequest = GetBillPayBankDataFactory::create();
$bankDataRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
Attribute | Required | Data Type | Info |
---|---|---|---|
mid | + | Positive int | Merchant ID |
pid | + | Positive int | Portal ID |
passwordhash | + | string | MD5 hash of the security key generated for this portal. |
Order Params Node
<order_params reference="1519088641" />
getBillPayBankDataRequest.setReference("1519088641");
<?php
$bankDataRequest->setReference('1519088641');
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
reference | + | string | AN..40 | Unique order ID from the merchant system. Allowed characters are: 0-9, a-z, A-Z, -, Regex: ([A-Z]|[a-z]|[0-9]|-|)* |
Response
The XML service response for this request contains all the relevant information for the customer to pay their open debt.
Data Node
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data
responsetype="GET_BILLPAY_BANK_DATA"
errorcode="0"
customermessage=""
merchantmessage=""
developermessage="">
<!-- additional response specific data -->
</data>
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
<?php
// send the request to BillPay and retrieve the response
$bankDataResponse = $bankDataRequest->send();
// get data out of the response
echo $bankDataResponse->getErrorCode();
echo $bankDataResponse->getMerchantMessage();
echo $bankDataResponse->getDeveloperMessage();
echo $bankDataResponse->getCustomerMessage();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
responsetype | + | string | GET_BILLPAY_BANK_DATA | Identifies for which request type the response is |
errorcode | + | non-negative int | N..3 | Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list |
merchantmessage | + | string | Detailed error message to be displayed to the merchant only | |
customermessage | + | string | Detailed error message to be displayed to the customer | |
developermessage | + | string | Detailed error message for developers, detailing the issue with the data in the case of a XSD validation conflict. This is empty when the request XML validates against our XSD. |
Bank Account Node - only for invoice (paymenttype
=“1”) and transaction credit in Switzerland (paymenttype
=“3”)
This node returns the BillPay bank account data to be used by the customer when paying for their order. This information must be parsed and printed on the invoice document the customers receive with their documents.
<bank_account
accountholder="BillPay GmbH"
accountnumber="DE07312312312312312"
bankcode="BELADEBEXXX"
bankname="Sparkasse Berlin"
firstduedate="20170707"
invoicereference="BP1519088641/9999" />
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
<?php
$bankAccount = $bankDataResponse->getInvoiceBankAccount();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
accountholder | + | string | AN..255 | Account holder |
accountnumber | + | string | AN..40 | BillPay IBAN |
bankcode | + | string | AN..16 | BillPay BIC |
bankname | + | string | AN..255 | Name of the BillPay bank |
firstduedate | + | string | N..8 | Payment due date in the format: YYYYMMDD |
invoicereference | + | string | AN..255 | Transaction purpose |
Invoice List Node
This node returns the invoice number and invoice ID in the BillPay system.
<invoice_list>
<invoice
duedate="20170324"
invoiceid="1234567" />
</invoice_list>
DueDate dueDate = requestResponse.getDueDates().get(0);
System.out.println(dueDate.getDuedate());
System.out.println(dueDate.getInvoiceid());
<?php
$dueDate = $bankDataResponse->getDueDates();
echo $dueDate->getDuedate();
echo $dueDate->getInvoiceid();
Attribute | Required | Data Type | Values | Info |
---|---|---|---|---|
invoice | + | Child node of the invoice_list node | ||
↳duedate | + | string | N..8 | Payment due date in the format: YYYYMMDD |
↳invoiceid | - | string | AN..40 | Invoice number in the BillPay system. Allowed characters are: 0-9, a-z, A-Z, -, , #, ., : Regex: ([A-Z]|[a-z]|[0-9]|-||#|:|.)* |
Customer Documents
Another vital component of the integration of BillPay payment methods, is the inclusion of the payment relevant information in the order confirmation emails and invoices that are sent to your customers. This ensures a positive and seamless customer experience from purchase to payment. The following table outlines the required texts.
Sample Invoices
Invoice |
Direct Debit |
Instalments |
Transaction Credit |
Invoice Texts
Payment | German | English |
---|---|---|
Invoice | Vielen Dank, dass Sie sich für die BillPay Rechnung entschieden haben. Bitte überweisen Sie den Rechnungsbetrag innerhalb der Zahlungsfrist unter Angabe des Verwendungszwecks $$ Verwendungszweck $$ auf folgendes Konto: Kontoinhaber: $$ Kontoinhaber $$ IBAN: $$ IBAN $$ BIC: $$ BIC $$ Bank: $$ Geldinstitut $$ Fälligkeitsdatum: $$ Fälligkeitsdatum $$ Verwendungszweck: $$ Verwendungszweck $$ Bitte beachten Sie, dass Ihre Rechnung nur dann beglichen ist, wenn Ihre Zahlung auf das oben genannte Konto erfolgt. |
Thank you for choosing invoice with BillPay as your payment method. Please transfer the total amount due prior to the expiration of the payment due date using the reference $$ reference $$ to the following account: Account holder: $$ account holder $$ Bank: $$ financial institution $$ IBAN: $$ IBAN $$ BIC: $$ BIC $$ Due date: $$ due date $$ Reference: $$ reference $$ Please note, the invoice is only considered paid in full, when the total amount due is transferred to the above bank account. |
Direct Debit | Der fällige Gesamtbetrag wird in den nächsten Tagen von dem bei der Bestellung angegebenen Konto durch die BillPay GmbH abgebucht. | In the coming days, the total amount due will be debited from the account you submitted with your order by the BillPay GmbH. |
Instalments (DE, AT) | Sie haben sich für die Zahlungsweise PayLater entschieden. Bitte beachten Sie, dass zusätzlich zu dem auf dieser Rechnung genannten Rechnungsbetrag weitere Kosten im Zusammenhang mit dem Teilzahlungsgeschäft entstehen. Diese Kosten wurden Ihnen vor Abschluss der Bestellung und auf der Bestellbestätigungsseite angezeigt. Die vollständige Berechnung der zu leistenden Beträge im Zusammenhang mit dem Teilzahlungsgeschäft, sowie sämtliche dazugehörige Informationen werden Sie direkt per E-Mail von der BillPay GmbH erhalten. | You have chosen to pay for your order with a BillPay instalment plan. Please note that in addition to the total amount mentioned on this invoice, additional costs are incurred in connection with the instalment plan. These costs were displayed to you before the order was completed and on the order confirmation page. The full calculation of the amounts to be paid in connection with the instalment plan, as well as all related information, will be sent to you via e-mail by the BillPay GmbH. |
Transaction Credit (CH) | Sie haben sich für die Zahlungsweise Ratenkauf entschieden. Bitte beachten Sie, dass zusätzlich zu dem auf dieser Rechnung genannten Rechnungsbetrag weitere Kosten im Zusammenhang mit dem Ratenkauf entstehen. Diese Kosten wurden Ihnen vor Abschluss der Bestellung und auf der Bestellbestätigungsseite angezeigt. Die vollständige Berechnung der zu leistenden Beträge im Zusammenhang mit dem Ratenkauf, sowie sämtliche dazugehörige Informationen werden Sie direkt per E-Mail von der BillPay GmbH erhalten. | You have chosen to pay for your order with BillPay Transaction Credit. Please note that in addition to the total amount mentioned on this invoice, additional costs are incurred in connection with the rate plan. These costs were displayed to you before the order was completed and on the order confirmation page. The full calculation of the amounts to be paid in connection with the rate plan, as well as all related information, will be sent to you via e-mail by the BillPay GmbH. |
Sample Requests
Prescore
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PRESCORE" apiversion="2.0.0" originofsale="o">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
<shipping_details usebillingaddress="1" />
<total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="36134" orderamountgross="43000" currency="EUR" />
<article_data>
<article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000">
</article>
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000">
</article>
</article_data>
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>
private void prescoreExample() throws ParseException {
//build the request
PrescoreRequest prescoreRequest = new PrescoreRequest();
prescoreRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session ID");
prescoreRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
prescoreRequest
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
prescoreRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
.setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1975/10/12"))
.setEmail("anymail@example.org")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Tinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
prescoreRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Tinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
prescoreRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000);
prescoreRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
prescoreRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
prescoreRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
//sending the request to BillPay and retrieving the response
PrescoreResponse requestResponse = prescoreRequest.send();
//getting data out of the response
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getAllowedPaymentOptions();
System.out.println(requestResponse.getTransactionId());
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
}
}
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PrescoreFactory;
$prescoreRequest = PrescoreFactory::create();
$prescoreRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID')
->setOriginOfSaleOnline();
$customer = $prescoreRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
$company = $customer->getCompany();
$company->setLegalFormGmbh()
->setName('Testfirma')
->setRegisterNumber('HRB 122 029 B')
->setCompanyProprietor('Testinhaber Owner')
->setTaxNumber('DE268874183');
$cart = $prescoreRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
$shipping = $prescoreRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
$prescoreRequest->setSessionId('session id');
// send the request to BillPay and retrieve the response
$prescoreResponse = $prescoreRequest->send();
// get data out of the response
if ($prescoreResponse->isError()) {
echo $prescoreResponse->getStatus();
echo $prescoreResponse->getErrorCode();
echo $prescoreResponse->getMerchantMessage();
echo $prescoreResponse->getDeveloperMessage();
echo $prescoreResponse->getCustomerMessage();
} else {
echo $prescoreResponse->getStatus();
echo $prescoreResponse->getTransactionId();
echo $prescoreResponse->getCustomerRestriction();
$allowed = $prescoreResponse->getAllowedPaymentMethods();
foreach($allowed as $billpaypm){
echo $billpaypm->getCustomerGroup();
echo $billpaypm->getPaymentId();
echo $billpaypm->getName();
}
}
echo $prescoreResponse->getNormalizedAddress()->getStreet();
echo $prescoreResponse->getNormalizedAddress()->getStreetNumber();
echo $prescoreResponse->getNormalizedAddress()->getZipCode();
echo $prescoreResponse->getNormalizedAddress()->getCity();
echo $prescoreResponse->getNormalizedAddress()->getCountry();
Preauth: Invoice-B2C
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" apiversion="2.0.0" originofsale="o">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
<shipping_details usebillingaddress="1" />
<total shippingname="none" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="40204" orderamountgross="43230" currency="EUR" reference="1519088641" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131"/>
<article_data>
<article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
</article_data>
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>
private void preauthorizeInvoiceExample() throws ParseException {
//build the request
PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
preauthorizeRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session ID");
preauthorizeRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
preauthorizeRequest
.setTermsAndConditionAccepted(true)
.setManualCapture(false)
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
preauthorizeRequest.getPaymentDetails()
.setPaymentType(PaymentType.INVOICE);
preauthorizeRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
.setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
.setEmail("anymail@example.org")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000)
.setTrackingNumber("ABZ12398892131");
preauthorizeRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.setInvoiceNumber("1234567")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
//sending the request to BillPay and retrieving the response
PreauthorizeResponse requestResponse = preauthorizeRequest.send();
//getting data out of the response
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getTransactionId());
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
}
}
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PreauthorizeFactory;
$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
->acceptTermsOfUse();
$preauthorizeRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID')
->setOriginOfSaleOnline()
->disableManualCapture();
$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
/*
if the shipping address is the same as the billing address, you do not need to do anything here. If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU');
$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
$shipping = $preauthorizeRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
$preauthorizeRequest->setSessionId('session id');
// send the request to BillPay and retrieve the response
$preauthorizeResponse = $preauthorizeRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getErrorCode();
echo $preauthorizeResponse->getMerchantMessage();
echo $preauthorizeResponse->getDeveloperMessage();
echo $preauthorizeResponse->getCustomerMessage();
} else {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getTransactionId();
echo $preauthorizeResponse->getCustomerRestriction();
$bankAccount = $preauthorizeResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
$invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();
Preauth: Invoice-B2B
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="1" apiversion="2.0.0" originofsale="o">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anymail@gmx.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="b" />
<shipping_details usebillingaddress="1" />
<company_details name="Testfirma" legalform="GmbH" registernumber="HRB 122 029 B" holdername="Testinhaber" taxnumber="DE268874183" />
<total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="36134" orderamountgross="43000" currency="EUR" reference="123456" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131" />
<article_data>
<article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
</article_data>
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>
private void preauthorizeInvoiceExample() throws ParseException {
//build the request
PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
preauthorizeRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session ID");
preauthorizeRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
preauthorizeRequest
.setTermsAndConditionAccepted(true)
.setManualCapture(false)
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
preauthorizeRequest.getPaymentDetails()
.setPaymentType(PaymentType.INVOICE);
preauthorizeRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.BUSINESS_CLIENT)
.setEmail("anymail@example.org")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getCustomer().createCompany()
.setName("Testfirma")
.setLegalForm("GmbH")
.setRegisterNumber("HRB 122 029 B")
.setTaxNumber("DE268874183")
.setCompanyProprietor("Testinhaber Owner");
preauthorizeRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000)
.setTrackingNumber("ABZ12398892131");
preauthorizeRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.setInvoiceNumber("1234567")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
//sending the request to BillPay and retrieving the response
PreauthorizeResponse requestResponse = preauthorizeRequest.send();
//getting data out of the response
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getTransactionId());
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
}
}
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PreauthorizeFactory;
$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_INVOICE);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
->acceptTermsOfUse();
$preauthorizeRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID')
->setOriginOfSaleOnline()
->disableManualCapture();
$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
/*
if the shipping address is the same as the billing address, you do not need to do anything here. If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU');
$company = $customer->getCompany();
$company->setLegalFormGmbh()
->setName('Testfirma')
->setRegisterNumber('HRB 122 029 B')
->setCompanyProprietor('Testinhaber Owner')
->setTaxNumber('DE268874183');
$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
$shipping = $preauthorizeRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
$preauthorizeRequest->setSessionId('session id');
// send the request to BillPay and retrieve the response
$preauthorizeResponse = $preauthorizeRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getErrorCode();
echo $preauthorizeResponse->getMerchantMessage();
echo $preauthorizeResponse->getDeveloperMessage();
echo $preauthorizeResponse->getCustomerMessage();
} else {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getTransactionId();
echo $preauthorizeResponse->getCustomerRestriction();
$bankAccount = $preauthorizeResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
$invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();
Preauth: Direct Debit
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="2" apiversion="2.0.0" originofsale="o">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
<shipping_details usebillingaddress="1" />
<total shippingname="none" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="40204" orderamountgross="43230" currency="EUR" reference="1519088641" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131" />
<article_data>
<article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
</article_data>
<bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>
private void preauthorizeInvoiceExample() throws ParseException {
//build the request
PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
preauthorizeRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session ID");
preauthorizeRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
preauthorizeRequest
.setTermsAndConditionAccepted(true)
.setManualCapture(false)
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
preauthorizeRequest.getPaymentDetails()
.setPaymentType(PaymentType.DIRECT_DEBIT);
preauthorizeRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
.setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
.setEmail("anymail@example.org")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000)
.setTrackingNumber("ABZ12398892131");
preauthorizeRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.setInvoiceNumber("1234567")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
preauthorizeRequest.getPaymentDetails()
.createBankAccount()
.setAccountHolder("Thomas Testkunde")
.setAccountNumber("DE12500105170648489890");
//sending the request to BillPay and retrieving the response
PreauthorizeResponse requestResponse = preauthorizeRequest.send();
//getting data out of the response
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getTransactionId());
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
}
}
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PreauthorizeFactory;
$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_DIRECT_DEBIT);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
->acceptTermsOfUse();
$preauthorizeRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID')
->setOriginOfSaleOnline()
->disableManualCapture();
$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
/*
if the shipping address is the same as the billing address, you do not need to do anything here. If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU');
$preauthorizeRequest->getBankAccount()
->setAccountHolder('Thomas Testkunde')
->setAccountNumber('DE12500105170648489890')
->setSortCode('');
$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
$shipping = $preauthorizeRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
$preauthorizeRequest->setSessionId('session id');
// send the request to BillPay and retrieve the response
$preauthorizeResponse = $preauthorizeRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getErrorCode();
echo $preauthorizeResponse->getMerchantMessage();
echo $preauthorizeResponse->getDeveloperMessage();
echo $preauthorizeResponse->getCustomerMessage();
} else {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getTransactionId();
echo $preauthorizeResponse->getCustomerRestriction();
$invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();
Preauth: PayLater
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="PREAUTHORIZE" tcaccepted="1" expecteddaystillshipping="0" manualcapture="0" paymenttype="4" apiversion="2.0.0" originofsale="o">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<customer_details customerid="123456" customertype="e" salutation="Herr" title="" firstname="Thomas" lastname="Testkunde" street="Tinnowitzer Straße" streetnumber="1" addressaddition="" zipcode="10115" city="Berlin" country="DEU" email="anyone@anymail.de" phone="03012345678" cellphone="" dateofbirth="19741012" language="de" ipaddress="80.111.120.1" customergroup="p" />
<shipping_details usebillingaddress="1" />
<total shippingname="none" shippingpricenet="0" shippingpricegross="0" rebatenet="930" rebategross="1000" orderamountnet="40204" orderamountgross="43230" currency="EUR" reference="1519088641" merchantinvoicenumber="1234567" trackingnumber="ABZ12398892131" />
<article_data>
<article articleid="1234" articlequantity="2" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
</article_data>
<rate_request ratecount="6" terminmonths="6" totalamountgross="46883" />
<bank_account accountholder="Thomas Testkunde" accountnumber="DE12500105170648489890" sortcode="" />
<fraud_detection sessionid="97d3d1b1cc6b0686bbc1f19feec80e6c" />
<async_capture_request>
<redirect_url><![CDATA[http://url1.de/redirect]]></redirect_url>
<notify_url><![CDATA[http://url1.de/notify]]></notify_url>
</async_capture_request>
</data>
private void preauthorizeInvoiceExample() throws ParseException {
//build the request
PreauthorizeRequest preauthorizeRequest = new PreauthorizeRequest();
preauthorizeRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session ID");
preauthorizeRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
preauthorizeRequest
.setTermsAndConditionAccepted(true)
.setManualCapture(false)
.setOriginOfSale(OriginOfSale.ONLINE_SHOP);
preauthorizeRequest.getPaymentDetails()
.setPaymentType(PaymentType.PAYLATER);
preauthorizeRequest.getCustomer()
.setId("123456")
.setCustomerType(CustomerType.EXISTING_CUSTOMER)
.setCustomerGroup(CustomerGroup.PRIVATE_CLIENT)
.setDateOfBirth(new SimpleDateFormat("yyyy/MM/dd").parse("1980/10/14"))
.setEmail("anymail@example.org")
.setIpAddress("80.111.120.1")
.setLanguageIso2("de")
.getBillingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getCustomer().createShippingAddress()
.setSalutation("Herr")
.setFirstName("Thomas")
.setLastName("Testkunde")
.setStreet("Zinnowitzer Straße")
.setStreetNumber("1")
.setZipCode("10115")
.setCity("Berlin")
.setCountryIso3("DEU")
.setPhone("03012345678");
preauthorizeRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000)
.setTrackingNumber("ABZ12398892131");
preauthorizeRequest.getCart()
.setOrderAmountNet(36134)
.setOrderAmountGross(43000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.setInvoiceNumber("1234567")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(2)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
preauthorizeRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
preauthorizeRequest.getPaymentDetails()
.createBankAccount()
.setAccountHolder("Thomas Testkunde")
.setAccountNumber("DE12500105170648489890");
preauthorizeRequest.getPaymentDetails().createInstalment()
.setRateCount(6)
.setTermInMonths(6)
.setTotalAmountGross(46883);
//sending the request to BillPay and retrieving the response
PreauthorizeResponse requestResponse = preauthorizeRequest.send();
//getting data out of the response
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getTransactionId());
System.out.println(requestResponse.getCorrectedAddress().getStreet());
System.out.println(requestResponse.getCorrectedAddress().getStreetNumber());
System.out.println(requestResponse.getCorrectedAddress().getZipCode());
System.out.println(requestResponse.getCorrectedAddress().getCity());
System.out.println(requestResponse.getCorrectedAddress().getCountry());
}
}
<?php
use BillPay\Core\Commons\Constants;
use BillPay\Core\Requests\PreauthorizeFactory;
$preauthorizeRequest = preauthorizeRequest::create();
$preauthorizeRequest->payment()->setById(Constants::PAYMENT_METHOD_ID_PAYLATER);
$payment = $preauthorizeRequest->getPaymentMethod();
$payment->getPaymentMethod()
->acceptTermsOfUse();
$preauthorizeRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setSessionId('clear text session ID')
->setOriginOfSaleOnline()
->disableManualCapture();
$customer = $preauthorizeRequest->getCustomer();
$customer->setId('123456')
->setIsExistingCustomer()
->setIsPrivateCustomer()
->setDateOfBirth('1975-10-12')
->setEmail('anymail@gmx.de')
->setIpAddress('80.111.120.1')
->setLanguageIso2('de')
->getBillingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Tinnowitzer Straße')
->setStreetNumber('1')
->setZipCode('10115')
->setCity('Berlin')
->setCountryIso3('DEU')
->setPhone('03012345678');
/*
if the shipping address is the same as the billing address, you do not need to do anything here. If the shipping address is not the same as the billing address, the shipping address is set as follows:
*/
$customer->getShippingAddress()
->setSalutation('Herr')
->setFirstName('Thomas')
->setLastName('Testkunde')
->setStreet('Hardenberger Straße')
->setStreetNumber('1')
->setZipCode('10623')
->setCity('Berlin')
->setCountryIso3('DEU');
$preauthorizeRequest->getBankAccount()
->setAccountHolder('Thomas Testkunde')
->setAccountNumber('DE12500105170648489890')
->setSortCode('');
$cart = $preauthorizeRequest->getCart();
$cart->createAndAddArticle()->setName('Shirt')
->setPriceGross('12000')
->setPriceNet('10084')
->setQuantity('2')
->setCategory('Clothing')
->setFirstSubCategory('Van Laack')
->setId('1234');
$cart->createAndAddArticle()->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->setQuantity('1')
->setCategory('Hose')
->setFirstSubCategory('Ralph Lauren')
->setId('2345');
$shipping = $preauthorizeRequest->getShipping();
$shipping->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('123456')
->setName('Express Versand');
$rebate = $cart->createRebate();
$rebate->setPriceGross('2000')
->setPriceNet('1681');
$cart->setOrderAmountGross('43000')
->setOrderAmountNet('36134')
->setCurrencyIso3('EUR')
->addRebate($rebate);
$payment->setRateCount('6')
->setRateTerm('6')
->setTotal('46883');
$payment->setRedirectUrl('www.redirect.de')
->setNotifyUrl('www.notify.de');
$preauthorizeRequest->setSessionId('session id');
// send the request to BillPay and retrieve the response
$preauthorizeResponse = $preauthorizeRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getErrorCode();
echo $preauthorizeResponse->getMerchantMessage();
echo $preauthorizeResponse->getDeveloperMessage();
echo $preauthorizeResponse->getCustomerMessage();
} else {
echo $preauthorizeResponse->getStatus();
echo $preauthorizeResponse->getTransactionId();
echo $preauthorizeResponse->getCustomerRestriction();
$invoiceNumber = $preauthorizeResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
}
echo $preauthorizeResponse->getNormalizedAddress()->getStreet();
echo $preauthorizeResponse->getNormalizedAddress()->getStreetNumber();
echo $preauthorizeResponse->getNormalizedAddress()->getZipCode();
echo $preauthorizeResponse->getNormalizedAddress()->getCity();
echo $preauthorizeResponse->getNormalizedAddress()->getCountry();
Capture
<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="CAPTURE" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<capture_params transactionid="1aa2fb2d-2b78-4393-bf06-be0012dda337" orderamountgross="43230" currency="EUR" reference="1519088641" merchantinvoicenumber="1234567" customerid="123456789" />
</data>
private void captureExample(){
//building the request
CaptureRequest captureRequest = new CaptureRequest();
captureRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id")
.setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
.setMerchantInvoiceNumber("1234567");
captureRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
captureRequest.getCustomer()
.setCustomerId("123456789");
captureRequest.getCart()
.setReference("1519088641")
.setCurrencyIso3("EUR")
.setOrderAmountGross(43000);
CaptureResponse requestResponse = captureRequest.send();
if (requestResponse.hasError()){
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
// The following is only returned for invoice as the payment method.
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
// The following is only returned if instalments is the chosen payment method
InstalmentPlan instalmentPlan = requestResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
// The following is only returned if transaction credit is the chosen payment method
RateOption rateOption = requestResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
// The following is only returned if you are implementing virtual credit card solution
System.out.println(requestResponse.getCreditCard().getAccountHolder());
System.out.println(requestResponse.getCreditCard().getCardNumber());
System.out.println(requestResponse.getCreditCard().getSecurityCode());
System.out.println(requestResponse.getCreditCard().getExpirationDate());
System.out.println(requestResponse.getCreditCard().getActivationDate());
}
}
<?php
$captureRequest = CaptureFactory::create();
$captureRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
$captureRequest->setReference('1519088641')
->setPortalId(9999)
->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
->setMerchantInvoiceNumber('1234567')
->getCart()
->setOrderAmountGross(43230)
->setCurrencyIso3('EUR')
->getCustomer()
->setId('123456789');
// send the request to BillPay and retrieve the response
$captureResponse = $captureRequest->send();
// get data out of the response
if ($preauthorizeResponse->isError()) {
echo $captureResponse->getStatus();
echo $captureResponse->getErrorCode();
echo $captureResponse->getMerchantMessage();
echo $captureResponse->getDeveloperMessage();
echo $captureResponse->getCustomerMessage();
} else {
echo $captureResponse->getStatus();
echo $captureResponse->getCustomerRestriction();
$bankAccount = $captureResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
$invoiceNumber = $captureResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
}
Invoice Created: complete
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<invoice_params carttotalgross="43000" currency="EUR" reference="1519088641" deliverydelayindays="0" />
</data>
private void invoiceCreatedExample(){
//building the request
InvoiceCreatedRequest invoiceCreatedRequest = new InvoiceCreatedRequest();
invoiceCreatedRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id")
.setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
.setMerchantInvoiceNumber("1234567");
.setIsPartial(0)
.setDeliveryDelayInDays(0);
invoiceCreatedRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
invoiceCreatedRequest.getCustomer()
.setCustomerId("123456789");
invoiceCreatedRequest.getCart()
.setReference("1519088641")
.setCurrencyIso3("EUR")
.setOrderAmountGross(43000);
InvoiceCreatedResponse invoiceCreatedResponse = invoiceCreatedRequest.send();
if (invoiceCreatedResponse.hasError()){
System.out.println(invoiceCreatedResponse.getErrorCode());
System.out.println(invoiceCreatedResponse.getMerchantMessage());
System.out.println(invoiceCreatedResponse.getDeveloperMessage());
System.out.println(invoiceCreatedResponse.getCustomerMessage());
} else {
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().isActivationPerformed());
// The following is only returned for invoice as the payment method.
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getBankCode());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getBankName());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getInvoiceReference());
// The following is only returned if instalments is the chosen payment method
InstalmentPlan instalmentPlan = invoiceCreatedResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
// The following is only returned if transaction credit is the chosen payment method
RateOption rateOption = invoiceCreatedResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
// The following is only returned if you are implementing virtual credit card solution
System.out.println(invoiceCreatedResponse.getCreditCard().getAccountHolder());
System.out.println(invoiceCreatedResponse.getCreditCard().getCardNumber());
System.out.println(invoiceCreatedResponse.getCreditCard().getSecurityCode());
System.out.println(invoiceCreatedResponse.getCreditCard().getExpirationDate());
System.out.println(invoiceCreatedResponse.getCreditCard().getActivationDate());
}
}
<?php
$invoiceRequest = InvoiceCreatedFactory::create();
$invoiceRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
$invoice = $invoiceRequest->getInvoice();
$invoice->setDeliveryDelayInDays(0)
->isPartialActivation(0)
->setMerchantInvoiceNumber('1234567');
$invoice->getCart()
->setOrderAmountGross('43000')
->setOrderAmountNet('19327')
->setCurrencyIso3('EUR');
// send the request to BillPay and retrieve the response
$invoiceResponse = $invoiceRequest->send();
// get data out of the response
echo $invoiceResponse->getErrorCode();
echo $invoiceResponse->getMerchantMessage();
echo $invoiceResponse->getDeveloperMessage();
echo $invoiceResponse->getCustomerMessage();
// The following is only returned for invoice as the payment method.
$bankAccount = $invoiceResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
$invoiceNumber = $invoiceResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
// The following is only returned if instalments is the chosen payment method
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
// The following is only returned if transaction credit is the chosen payment method
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Invoice Created: partial
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="INVOICE_CREATED" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<invoice_params carttotalgross="23000" currency="EUR" reference="1773673332" deliverydelayindays="0" is_partial="1" invoice_number="INV551202291" shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="19327" />
<article_data>
<article articleid="1234" articlequantity="2" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
</article_data>
</data>
private void invoiceCreatedExample(){
//building the request
InvoiceCreatedRequest invoiceCreatedRequest = new InvoiceCreatedRequest();
invoiceCreatedRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id")
.setTransactionId("1aa2fb2d-2b78-4393-bf06-be0012dda337")
.setMerchantInvoiceNumber("1234567");
.setIsPartial(1)
.setDeliveryDelayInDays(0);
invoiceCreatedRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
invoiceCreatedRequest.getCustomer()
.setCustomerId("123456789");
invoiceCreatedRequest.getCart()
.setReference("1773673332")
.setCurrencyIso3("EUR")
.setOrderAmountGross(23000);
.setInvoiceNumber("INV551202291")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
invoiceCreatedRequest.getShipping()
.setPriceGross(1000)
.setPriceNet(840)
.setName("Express Versand");
InvoiceCreatedResponse invoiceCreatedResponse = invoiceCreatedRequest.send();
if (invoiceCreatedResponse.hasError()){
System.out.println(invoiceCreatedResponse.getErrorCode());
System.out.println(invoiceCreatedResponse.getMerchantMessage());
System.out.println(invoiceCreatedResponse.getDeveloperMessage());
System.out.println(invoiceCreatedResponse.getCustomerMessage());
} else {
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().isActivationPerformed());
// The following is only returned for invoice as the payment method.
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getBankCode());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getBankName());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(invoiceCreatedResponse.getInvoiceBankAccount().getInvoiceReference());
// The following is only returned if instalments is the chosen payment method
InstalmentPlan instalmentPlan = invoiceCreatedResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
// The following is only returned if transaction credit is the chosen payment method
RateOption rateOption = invoiceCreatedResponse.getInstalmentDetails().getRateOption();
System.out.println(rateOption.getRateCount());
System.out.println(rateOption.getTerm());
System.out.println(rateOption.getCalculationBaseAmount());
System.out.println(rateOption.getCartTotalGross());
System.out.println(rateOption.getSurcharge());
System.out.println(rateOption.getTotalPaymentAmount());
System.out.println(rateOption.getMonthlyInterestRate());
System.out.println(rateOption.getAnualInterestRate());
System.out.println(rateOption.getAdditionalFee());
DueDetail dueDetail = rateOption.getDueDetailsList().get(0);
System.out.println(dueDetail.getAmount());
System.out.println(dueDetail.getDate());
System.out.println(dueDetail.getRateType());
// The following is only returned if you are implementing virtual credit card solution
System.out.println(invoiceCreatedResponse.getCreditCard().getAccountHolder());
System.out.println(invoiceCreatedResponse.getCreditCard().getCardNumber());
System.out.println(invoiceCreatedResponse.getCreditCard().getSecurityCode());
System.out.println(invoiceCreatedResponse.getCreditCard().getExpirationDate());
System.out.println(invoiceCreatedResponse.getCreditCard().getActivationDate());
}
}
<?php
$invoiceRequest = InvoiceCreatedFactory::create();
$invoiceRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
$invoice = $invoiceRequest->getInvoice();
$invoice->setDeliveryDelayInDays(0)
->isPartialActivation(1)
->setMerchantInvoiceNumber('INV551202291');
$invoice->getShipping()
->setName('shipping')
->setPriceGross('1000')
->setPriceNet('950')
->setTrackingNumber('ABZ12398892131');
$invoice->getCart()
->setOrderAmountGross('23000')
->setOrderAmountNet('19327')
->setCurrencyIso3('EUR')
->createAndAddRebate()
->setPriceGross('2000')
->setPriceNet('1681');
$invoiceRequest->getInvoice()->getCart()->createAndAddArticle()
->setPriceGross('20000')
->setPriceNet('16807')
->setName('Hose')
->setQuantity('1')
->setId('2345')
->setCategory('Clothing')
->setFirstSubCategory('Ralph Lauren');
// send the request to BillPay and retrieve the response
$invoiceResponse = $invoiceRequest->send();
// get data out of the response
echo $invoiceResponse->getErrorCode();
echo $invoiceResponse->getMerchantMessage();
echo $invoiceResponse->getDeveloperMessage();
echo $invoiceResponse->getCustomerMessage();
// The following is only returned for invoice as the payment method.
$bankAccount = $invoiceResponse->getInvoiceBankAccount();
echo $bankAccount->isActivationPerformed();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
echo $bankAccount->getEsrReference();
echo $bankAccount->getEsrCodeLine();
$invoiceNumber = $invoiceResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
// The following is only returned if instalments is the chosen payment method
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
// The following is only returned if transaction credit is the chosen payment method
$instalmentDetails = $invoiceResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Cancel
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="CANCEL" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<cancel_params reference="1519088641" orderamountgross="43230" currency="EUR" />
</data>
private void cancelExample(){
//building the request
CancelRequest cancelRequest = new CancelRequest();
cancelRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
cancelRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
cancelRequest.getCart()
.setReference("1519088641")
.setCurrencyIso3("EUR")
.setOrderAmountGross(43000);
CancelResponse cancelResponse = cancelRequest.send();
if (cancelResponse.hasError()) {
System.out.println(cancelResponse.getErrorCode());
System.out.println(cancelResponse.getMerchantMessage());
System.out.println(cancelResponse.getDeveloperMessage());
System.out.println(cancelResponse.getCustomerMessage());
}
}
<?php
$cancelRequest = CancelFactory::create();
$cancelRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setReference('1519088641');
$cancelRequest->getCart()
->setOrderAmountGross(43000)
->setCurrencyIso3('EUR');
// send the request to BillPay and retrieve the response
$cancelResponse = $cancelRequest->send();
// get data out of the response
echo $cancelResponse->getErrorCode();
echo $cancelResponse->getMerchantMessage();
echo $cancelResponse->getDeveloperMessage();
echo $cancelResponse->getCustomerMessage();
Edit Cart
1 unit of article “1234” was returned. The articlequantity
was reduced and the orderamountnet
and orderamountgross
values are adjusted accordingly.
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="EDIT_CART_CONTENT" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="26050" orderamountgross="31000" currency="EUR" reference="976692924" trackingnumber="ABZ12398892131" />
<article_data>
<article articleid="1234" articlequantity="1" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
</article_data>
</data>
private void EditCartContentExample() {
//building the request
EditCartContentRequest editCartContentRequest = new EditCartContentRequest();
editCartContentRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
editCartContentRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
editCartContentRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000);
editCartContentRequest.getCart().createAndAddArticle()
.setId("1234")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setCategory("Clothing")
.setFirstSubCategory("Van Laack")
.setPriceNet(10084)
.setPriceGross(12000);
editCartContentRequest.getCart().createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setCategory("Clothing")
.setFirstSubCategory("Ralph Lauren")
.setPriceNet(16807)
.setPriceGross(20000);
editCartContentRequest.getCart()
.setOrderAmountNet(26050)
.setOrderAmountGross(31000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
EditCartContentResponse editCartContentResponse = editCartContentRequest.send();
if (requestResponse.hasError()) {
System.out.println(editCartContentResponse.getErrorCode());
System.out.println(editCartContentResponse.getMerchantMessage());
System.out.println(editCartContentResponse.getDeveloperMessage());
System.out.println(editCartContentResponse.getCustomerMessage());
} else {
// The following is only returned if instalments is the chose payment method
InstalmentPlan instalmentPlan = editCartContentResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
}
}
<?php
$editCartContentRequest = EditCartContentFactory::create();
$editCartContentRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
$editCartContentRequest->setReference('1519088641');
$editCartContentRequest->getShipping()
->setName('Express Versand')
->setPriceGross(1000)
->setPriceNet(840)
->setTrackingNumber('12345');
$editCartContentRequest->getCart()
->setOrderAmountNet('26050')
->setOrderAmountGross('31000')
->setCurrencyIso3('EUR');
$editCartContentRequest->getCart()->createAndAddRebate()
->setPriceGross(2000)
->setPriceNet(1681);
$editCartContentRequest->getCart()->createAndAddArticle()
->setId("1234")
->setQuantity(1)
->setType(ArticleType.OTHER)
->setName("Shirt")
->setCategory("Clothing")
->setFirstSubCategory("Van Laack")
->setPriceNet(10084)
->setPriceGross(12000);
$editCartContentRequest->getCart()->createAndAddArticle()
->setId("2345")
->setQuantity(1)
->setType(ArticleType.OTHER)
->setName("Hose")
->setCategory("Clothing")
->setFirstSubCategory("Ralph Lauren")
->setPriceNet(16807)
->setPriceGross(20000);
// send the request to BillPay and retrieve the response
$editCartContentResponse = $editCartContentRequest->send();
// get data out of the response
echo $editCartContentResponse->getErrorCode();
echo $editCartContentResponse->getMerchantMessage();
echo $editCartContentResponse->getDeveloperMessage();
echo $editCartContentResponse->getCustomerMessage();
$invoiceNumber = $editCartContentResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
// The following is only returned if instalments is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
// The following is only returned if transaction credit is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Edit Cart: partial shipment
The second partial shipment (merchantinvoicenumber 234567) was delivered containing 2 units of article 1234. 1 unit of article 1234 was returned so the articlequantity
in the main order article_data
as well as in the invoice_list
is reduced to 1 and the orderamountnet
/ orderamountgross
and invoiceamountnet
/ invoiceamountgross
are adjusted accordingly in the main (article_data node) and suborder (invoice node).
<?xml version="1.0" encoding="UTF-8"?>
<data requesttype="EDIT_CART_CONTENT" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<total shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" rebatenet="1681" rebategross="2000" orderamountnet="26050" orderamountgross="31000" currency="EUR" reference="1773673332" />
<article_data>
<article articleid="1234" articlequantity="1" articletype="0" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articlepricenet="10084" articlepricegross="12000" />
<article articleid="2345" articlequantity="1" articletype="0" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articlepricenet="16807" articlepricegross="20000" />
</article_data>
<invoice_list>
<invoice merchantinvoicenumber="1234567">
<invoice_params invoiceamountnet="15966" invoiceamountgross="19000" rebatenet="1681" rebategross="2000"
shippingname="Express Versand" shippingpricenet="840" shippingpricegross="1000" currency="EUR" reference="1773673332" trackingnumber="ABZ12398892131" />
<article_data>
<article articleid="2345" articlequantity="1" articlename="Hose" articlepricenet="16807" articlepricegross="20000" />
</article_data>
</invoice>
<invoice merchantinvoicenumber="234567">
<invoice_params invoiceamountnet="10084" invoiceamountgross="12000" rebatenet="0" rebategross="0"
shippingname="Express Versand" shippingpricenet="0" shippingpricegross="0" currency="EUR" reference="1773673332" trackingnumber="ABZ13498892131" />
<article_data>
<article articleid="1234" articlequantity="1" articlename="Shirt" articlepricenet="10084" articlepricegross="12000" />
</article_data>
</invoice>
</invoice_list>
</data>
private void EditCartContentPartialActivationExample() {
//building the request
EditCartContentRequest editCartContentRequest = new EditCartContentRequest();
editCartContentRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
editCartContentRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
editCartContentRequest.getShipping()
.setName("Express Versand")
.setPriceNet(840)
.setPriceGross(1000);
Invoice invoice1 = editCartContentRequest.createAndAddInvoice("1234567")
.setTotalPriceNet(15966)
.setTotalPriceGross(19000)
.setShippingPriceNet(840)
.setShippingPriceGross(1000)
.setShippingName("shipping name")
.setRebateNet(1681)
.setRebateGross(2000);
invoice1.createAndAddArticle()
.setId("2345")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Hose")
.setPriceNet(16807)
.setPriceGross(20000);
Invoice invoice2 = editCartContentRequest.createAndAddInvoice("234567")
.setTotalPriceNet(10084)
.setTotalPriceGross(12000)
.setShippingPriceNet(0)
.setShippingPriceGross(0)
.setShippingName("shipping name")
.setRebateNet(0)
.setRebateGross(0);
invoice2.createAndAddArticle()
.setId("1234")
.setQuantity(1)
.setType(ArticleType.OTHER)
.setName("Shirt")
.setPriceNet(10084)
.setPriceGross(12000);
editCartContentRequest.getCart()
.setOrderAmountNet(26050)
.setOrderAmountGross(31000)
.setCurrencyIso3("EUR")
.setReference("1519088641")
.createAndAddRebate()
.setRebateNet(1681)
.setRebateGross(2000);
EditCartContentResponse editCartContentResponse = editCartContentRequest.send();
if (requestResponse.hasError()) {
System.out.println(editCartContentResponse.getErrorCode());
System.out.println(editCartContentResponse.getMerchantMessage());
System.out.println(editCartContentResponse.getDeveloperMessage());
System.out.println(editCartContentResponse.getCustomerMessage());
} else {
// The following is only returned if instalments is the chose payment method
InstalmentPlan instalmentPlan = editCartContentResponse.getInstalmentDetails().getInstalmentPlan();
System.out.println(instalmentPlan.getDurationInMonths());
System.out.println(instalmentPlan.getFeePercent());
System.out.println(instalmentPlan.getFeeTotal());
System.out.println(instalmentPlan.getTotalPayment());
System.out.println(instalmentPlan.getEffAnual());
System.out.println(instalmentPlan.getNominal());
InstalmentItem instalmentItem = instalmentPlan.getInstalmentList().get(0);
System.out.println(instalmentItem.getAmount());
System.out.println(instalmentItem.getDate());
System.out.println(instalmentItem.getType());
}
}
<?php
$editCartContentRequest = EditCartContentFactory::create();
$editCartContentRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
$editCartContentRequest->setReference('1519088641');
$editCartContentRequest->getShipping()
->setName('Express Versand')
->setPriceGross(1000)
->setPriceNet(840)
->setTrackingNumber('12345');
$editCartContentRequest->getCart()
->setOrderAmountNet('26050')
->setOrderAmountGross('31000')
->setCurrencyIso3('EUR');
$editCartContentRequest->getCart()->createAndAddRebate()
->setPriceGross(2000)
->setPriceNet(1681);
$editCartContentRequest->getCart()->createAndAddArticle()
->setId("1234")
->setQuantity(1)
->setType(ArticleType.OTHER)
->setName("Shirt")
->setCategory("Clothing")
->setFirstSubCategory("Van Laack")
->setPriceNet(10084)
->setPriceGross(12000);
$editCartContentRequest->getCart()->createAndAddArticle()
->setId(2345)
->setQuantity(1)
->setName('Hose')
->setCategory('Clothing')
->setFirstSubCategory('Ralph Lauren')
->setPriceGross('16807')
->setPriceNet('20000');
$invoice1 = $editCartContentRequest->createAndAddInvoice()
->setMerchantInvoiceNumber('1234567');
$invoice1->getCart()
->setOrderAmountNet('15966')
->setOrderAmountGross('19000')
->setCurrencyIso3('EUR');
$invoice1->getShipping()
->setName('shipping name')
->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('ABZ12398892131');
$invoice1->getCart()->createAndAddArticle()
->setId(2345)
->setQuantity(1)
->setName('Hose')
->setPriceGross('20000')
->setPriceNet('16807')
->appendTo($editCartContentRequest->getCart()); // append to ecc request cart as well
$invoice1->getCart()->createRebate()
->setPriceGross(2000)
->setPriceNet(1681)
->appendTo($invoice1->getCart());
$invoice2 = $editCartContentRequest->createAndAddInvoice()
->setMerchantInvoiceNumber('234567');
$invoice2->getCart()
->setOrderAmountNet('15966')
->setOrderAmountGross('19000')
->setCurrencyIso3('EUR');
$invoice2->getShipping()
->setName('shipping name')
->setPriceGross('1000')
->setPriceNet('840')
->setTrackingNumber('ABZ12398892131');
$invoice2->getCart()->createAndAddArticle()
->setId(1234)
->setQuantity(1)
->setName('Shirt')
->setPriceGross('10084')
->setPriceNet('12000')
->appendTo($editCartContentRequest->getCart()); // append to ecc request cart as well
// send the request to BillPay and retrieve the response
$editCartContentResponse = $editCartContentRequest->send();
// get data out of the response
echo $editCartContentResponse->getErrorCode();
echo $editCartContentResponse->getMerchantMessage();
echo $editCartContentResponse->getDeveloperMessage();
echo $editCartContentResponse->getCustomerMessage();
$invoiceNumber = $editCartContentResponse->getInvoiceNumbers();
echo $invoiceNumber->getInvoiceId();
echo $invoiceNumber->getBillpayInvoiceNumber();
// The following is only returned if instalments is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getFeePercentage();
echo $instalmentDetails->getFee();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
// The following is only returned if transaction credit is the chosen payment method
$instalmentDetails = $editCartContentResponse->getInstalmentDetails();
echo $instalmentDetails->getInstalmentCount();
echo $instalmentDetails->getDurationInMonth();
echo $instalmentDetails->getBase();
echo $instalmentDetails->getCart();
echo $instalmentDetails->getSurcharge();
echo $instalmentDetails->getTotalAmount();
echo $instalmentDetails->getAnnualPercentageRate();
echo $instalmentDetails->getNominalPercentageRate();
$instalments = $instalmentDetails->getInstalments();
echo $instalments[0]->getAmount();
echo $instalments[0]->getDateString();
echo $instalments[0]->getType();
Update Order
<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="UPDATE_ORDER" apiversion="2.0.0">
<default_params mid="1234" pid="9999" passwordhash="25d55ad283aa400af464c76d713c07ad" />
<update_params transactionid="b61648a3-46a1-4771-834f-903b89510ed9" reference="1591605922_updated" />
<id_update_list>
<id_update articleid="1234" updateid="1234_mod" />
<id_update articleid="2345" updateid="2345_mod" />
</id_update_list>
</data>
private void updateOrderExample() {
//building the request
UpdateOrderRequest updateOrderRequest = new UpdateOrderRequest();
updateOrderRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
updateOrderRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
updateOrderRequest.setReference("1591605922_updated");
updateOrderRequest.setTransactionId("b61648a3-46a1-4771-834f-903b89510ed9");
updateOrderRequest.createAndAddUpdateOrder()
.setNewId("1234")
.setOldId("1234_mod");
updateOrderRequest.createAndAddUpdateOrder()
.setNewId("2345")
.setOldId("2345_mod");
UpdateOrderResponse requestResponse = updateOrderRequest.send();
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
}
}
<?php
$updateOrderRequest = UpdateOrderFactory::create();
$updateOrderRequest
->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password');
$updateOrderRequest
->setTransactionId('1aa2fb2d-2b78-4393-bf06-be0012dda337')
->setReference('1591605922_updated');
$updateOrderRequest->getCart()->createAndAddArticleUpdate()
->setId('1234')
->setNewId('1234_mod');
$updateOrderRequest->getCart()->createAndAddArticleUpdate()
->setId('2345')
->setNewId('2345_mod');
// send the request to BillPay and retrieve the response
$updateOrderResponse = $updateOrderRequest->send();
// get data out of the response
echo $updateOrderResponse->getErrorCode();
echo $updateOrderResponse->getMerchantMessage();
echo $updateOrderResponse->getDeveloperMessage();
echo $updateOrderResponse->getCustomerMessage();
Get Bank Data
<?xml version="1.0" encoding="UTF-8" ?>
<data requesttype="GET_BILLPAY_BANK_DATA" apiversion="2.0.0">
<default_params
mid="1234"
pid="9999"
passwordhash="25d55ad283aa400af464c76d713c07ad" />
<order_params reference="1519088641" />
</data>
private void getBankDataExample() {
//building the request
GetBillPayBankDataRequest getBillPayBankDataRequest = new GetBillPayBankDataRequest();
getBillPayBankDataRequest
.setMerchantId(1234)
.setPortalId(9999)
.setApiPassword("clear text password")
.setSessionId("clear text session id");
getBillPayBankDataRequest.getEnvironment()
.setEnv(Environment.Key.TEST);
getBillPayBankDataRequest.setReference("1519088641");
GetBillPayBankDataResponse requestResponse = getBillPayBankDataRequest.send();
if (requestResponse.hasError()) {
System.out.println(requestResponse.getErrorCode());
System.out.println(requestResponse.getMerchantMessage());
System.out.println(requestResponse.getDeveloperMessage());
System.out.println(requestResponse.getCustomerMessage());
} else {
System.out.println(requestResponse.getInvoiceBankAccount().isActivationPerformed());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountHolder());
System.out.println(requestResponse.getInvoiceBankAccount().getAccountNumber());
System.out.println(requestResponse.getInvoiceBankAccount().getBankCode());
System.out.println(requestResponse.getInvoiceBankAccount().getBankName());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceDueDate());
System.out.println(requestResponse.getInvoiceBankAccount().getInvoiceReference());
DueDate dueDate = requestResponse.getDueDates().get(0);
System.out.println(dueDate.getDuedate());
System.out.println(dueDate.getInvoiceid());
}
}
<?php
$bankDataRequest = GetBillPayBankDataFactory::create();
$bankDataRequest->setMerchantId(1234)
->setPortalId(9999)
->setApiPassword('clear text password')
->setReference('1519088641');
// send the request to BillPay and retrieve the response
$bankDataResponse = $bankDataRequest->send();
// get data out of the response
echo $bankDataResponse->getErrorCode();
echo $bankDataResponse->getMerchantMessage();
echo $bankDataResponse->getDeveloperMessage();
echo $bankDataResponse->getCustomerMessage();
$bankAccount = $bankDataResponse->getInvoiceBankAccount();
echo $bankAccount->getAccountHolder();
echo $bankAccount->getAccountNumber();
echo $bankAccount->getBankCode();
echo $bankAccount->getBankName();
echo $bankAccount->getInvoiceDueDate();
echo $bankAccount->getInvoiceReference();
$dueDate = $bankDataResponse->getDueDates();
echo $dueDate->getDuedate();
echo $dueDate->getInvoiceid();
Addendum
Versioning
API Version | .NET Library Version | PHP Library Version | Java Library Version |
---|---|---|---|
2.0.0 | >= 2.0.0 | >= 2.0.0 | >= 2.0.0 |
Salutations
Gender “female”: | Gender “male”: |
---|---|
frau | herr |
fräulein | hr |
fr | hr. |
fr. | sir |
miss | mr |
ms | mr. |
ms. | signor |
mrs | sig |
mrs. | sig. |
signora | gentleman |
sig.a | gentiluomo |
sig.ra | padrone |
donna | monsieur |
la signora | m. |
madame | m |
mme | |
mademoiselle | |
mlle | |
mle |
Legal Forms
API Value | Label Displayed | Germany | Austria | Switzerland |
---|---|---|---|---|
ag | (Aktiengesellschaft) | x | x | x |
ag_co_kg | AG & Co KG | x | x | |
e_ges | einfache Gesellschaft | x | ||
eg | (eingetragene Genossenschaft) | x | x | x |
eu | eingetragener Einzelunternehmer | x | ||
ek | (eingetragener Kaufmann) | x | x | |
ev | e.V. (eingetragener Verein) | x | x | x |
einzel | Einzelfirma | x | x | |
ewiv | Europäische wirtschaftliche Interessenvereinigung | x | x | |
freelancer | Freiberufler/Kleingewerbetreibender/Handelsvertreter | x | x | x |
foundation | Stiftung | x | x | x |
gbr | GbR/BGB (Gesellschaft bürgerlichen Rechts) | x | x | |
gmbh | GmbH (Gesellschaft mit beschränkter Haftung) | x | x | x |
gmbh_ig | GmbH in Gründung | x | ||
gmbh_co_kg | GmbH & Co. KG | x | x | |
inv_kk | Investmentgesellschaft für kollektive Kapitalanlagen | x | ||
kg | (Kommanditgesellschaft) | x | x | x |
kgaa | Kommanditgesellschaft auf Aktien | x | x | |
k_ges | Kollektivgesellschaft | x | ||
ltd | Limited | x | x | |
ltd_co_kg | Limited & Co. KG | x | x | |
misc | sonstige Personengesellschaft | x | x | x |
misc_capital | sonstige Kapitalgesellschaft | x | x | x |
og | offene Gesellschaft | x | ||
ohg | OHG (offene Handelsgesellschaft) | x | x | |
public_inst | öffentliche Einrichtung | x | x | x |
ug | UG (Unternehmensgesellschaft haftungsbeschränkt) | x | x |
When is the field “registerNumber and "holderName” mandatory?
API Value | registernumber | holdername | ||||
---|---|---|---|---|---|---|
DEU | AUT | CHE | DEU | AUT | CHE | |
ag | x | x | x | |||
ag_co_kg | x | x | ||||
eg | x | |||||
einzel | x | |||||
ek | x | |||||
e_ges | x | |||||
eu | x | |||||
foundation | x | |||||
freelancer | x | x | x | |||
gbr | x | x | ||||
gmbh | x | x | x | |||
gmbh_co_kg | x | x | ||||
kg | x | x | x | |||
kgaa | x | |||||
k_ges | x | |||||
ltd | x | |||||
ltd_co_kg | x | |||||
ohg | x | x | ||||
ug | x |
API Error Codes
The Customer Message is what you must display to your customers on your website when an error code is returned. The Merchant Message is what you must log, so you can review the errors that are occuring in your implementation.
Error Code | Message Audience | Message |
---|---|---|
1 | Customer | Error: An internal error occurred. Please try again later. |
1 | Merchant | Error: An internal error occurred. Please try again later. |
2 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
2 | Merchant | Error: The submitted Merchant ID is wrong. |
3 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
3 | Merchant | Error: The portal ID is wrong. |
4 | Merchant | Error: API authentication failure. |
4 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
5 | Customer | Error: Please confirm the Billpays Terms & Conditions before you use this payment method from Billpay. |
5 | Merchant | Error: Please confirm the Billpays Terms & Conditions before you use this payment method from Billpay. |
7 | Customer | Error: The mandatory parameter [parameter] was not submitted. |
7 | Merchant | Error: The mandatory parameter [parameter] was not submitted. |
8 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
8 | Merchant | Error: The value for the field [parameter] has the wrong data format. |
9 | Customer | Error: Please verify your input data. The first name of your billing address must consist of at least 2 letters. |
9 | Merchant | Error: Please verify your input data. The first name of your billing address must consist of at least 2 letters. |
11 | Customer | Error: Please verify your input data. The street of your billing address must consist of at least 2 letters. |
11 | Merchant | Error: Please verify your input data. The street of your billing address must consist of at least 2 letters. |
12 | Customer | Error: Please verify your input data. The street number of your billing address must consist of at least 1 digit. |
12 | Merchant | Error: Please verify your input data. The street number of your billing address must consist of at least 1 digit. |
13 | Customer | Error: Please verify your input data. The zip code of your billing address must consist of exactly [length] digits. |
13 | Merchant | Error: Please verify your input data. The zip code of your billing address must consist of exactly [length] digits. |
14 | Customer | Error: Please verify your input data. The city name of your billing address must consist of at least 2 letters. |
14 | Merchant | Error: Please verify your input data. The city name of your billing address must consist of at least 2 letters. |
15 | Customer | Error: Please verify your input data. The telephone number of your billing address is not correct. |
15 | Merchant | Error: Please verify your input data. The telephone number of your billing address is not correct. |
16 | Customer | Error: Please verify your input data. The mobile phone number of your billing address is not correct. |
16 | Merchant | Error: Please verify your input data. The mobile phone number of your billing address is not correct. |
17 | Customer | Error: Please verify your input data. Your email address is invalid. |
17 | Merchant | Error: Please verify your input data. Your email address is invalid. |
18 | Customer | Error: Please verify your input data. Your birthday must not be in the future. |
18 | Merchant | Error: Please verify your input data. Your birthday must not be in the future. |
19 | Customer | Error: Please select another payment method. You must be at least 18 years old in order to pay with this payment method from Billpay. |
19 | Merchant | Error: Please select another payment method. You must be at least 18 years old in order to pay with this payment method from Billpay. |
21 | Customer | Error: Please verify your input data. The last name of your shipping address must consist of at least 2 letters. |
21 | Merchant | Error: Please verify your input data. The last name of your shipping address must consist of at least 2 letters. |
22 | Customer | Error: Please verify your input data. The street of your shipping address must consist of at least 2 letters. |
22 | Merchant | Error: Please verify your input data. The street of your shipping address must consist of at least 2 letters. |
23 | Customer | Error: Please verify your input data. The street number of your shipping address must consist of at least 1 digit. |
23 | Merchant | Error: Please verify your input data. The street number of your shipping address must consist of at least 1 digit. |
24 | Customer | Error: Please verify your input data. The zip code of your shipping address must consist of exactly 5 digits. |
24 | Merchant | Error: Please verify your input data. The zip code of your shipping address must consist of exactly 5 digits. |
25 | Customer | Error: Please verify your input data. The city name of your shipping address must consist of at least 2 letters. |
25 | Merchant | Error: Please verify your input data. The city name of your shipping address must consist of at least 2 letters. |
26 | Customer | Error: Please verify your input data. The telephone number of your shipping address is not correct. |
26 | Merchant | Error: Please verify your input data. The telephone number of your shipping address is not correct. |
27 | Customer | Error: Please verify your input data. The mobile phone number of your shipping address is not correct. |
27 | Merchant | Error: Please verify your input data. The mobile phone number of your shipping address is not correct. |
28 | Customer | Error: You can only use this payment method from Billpay if billing and shipping country are located in Germany. |
28 | Merchant | Error: You can only use this payment method from Billpay if billing and shipping country are located in Germany. |
29 | Merchant | Please select another payment method. The IP address is assigned to a country that is blacklisted. |
29 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
31 | Customer | Error: Your billing and shipping addresses may not be a Packstation. |
31 | Merchant | Error: Your billing and shipping addresses may not be a Packstation. |
32 | Merchant | Please select another payment method. The request was rejected because of a failed identity or credit check. |
32 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
33 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
33 | Merchant | Error: The order amount does not match the transaction ID. |
34 | Merchant | Error: No transaction ID was submitted. |
34 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
35 | Customer | Error: An error occurred. |
35 | Merchant | Error: The submitted transaction ID is invalid. |
36 | Customer | Error: Please select a salutation. |
36 | Merchant | Error: Please verify your input data. The mandatory field [parameter] must be Mister or Misses. |
37 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
37 | Merchant | Error: Please verify your input data. The mandatory field [parameter] must contain a valid IP address. |
38 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
38 | Merchant | Error: The mandatory parameter [customerType] was not submitted or is invalid. |
39 | Customer | Error: The value for field [parameter] must be integer value. |
39 | Merchant | Error: The value for field [parameter] must be integer value. |
41 | Merchant | Error: There were too many requests sent from this IP address. |
41 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
42 | Merchant | Error: The customer has open debts. |
42 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
43 | Merchant | Error: The order limit at Billpay for this customer is reached. |
43 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
44 | Merchant | Error: The merchant has open debts against this customer. |
44 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
45 | Merchant | External identity or credit check failed. |
45 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
46 | Merchant | Error: If the billing address is used as shipping address, the shipping address must be empty [parameter]. |
46 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
47 | Customer | Error: Please verify your input data. The street number must start with a digit [parameter]. |
47 | Merchant | Error: Please verify your input data. The street number must start with a digit [parameter]. |
48 | Customer | Error: An internal error occurred. Please try again later. |
48 | Merchant | Error: No articles were submitted for cancellation. |
49 | Customer | Error: The cart has been changed. Please start again the checkout process. |
49 | Merchant | Error: The order amount submitted for confirmation has changed in comparison to the amount submitted for preauthorization. |
51 | Customer | Error: The value for field [parameter] must be at least [minLength] characters long. |
51 | Merchant | Error: The value for field [parameter] must be at least [minLength] characters long. |
52 | Customer | Error: The value for field [parameter] must be not more than [maxLength] characters long. |
52 | Merchant | Error: The value for field [parameter] must be not more than [maxLength] characters long. |
53 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
53 | Merchant | Error: The submitted order data is invalid. |
54 | Customer | Error: The value for field [parameter] must be equal to one of the following values: [string] |
54 | Merchant | Error: The value for field [parameter] must be equal to one of the following values: [string] |
55 | Customer | Error: The quantity to be cancelled of one article is higher than the order quantity of this article. |
55 | Merchant | Error: The quantity to be cancelled of one article is higher than the order quantity of this article. |
56 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
56 | Merchant | Error: The submitted XML is invalid. |
57 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
57 | Merchant | Error: The order has already been captured. |
58 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
58 | Merchant | Error: The order amount submitted for cancellation has changed in comparison to the amount submitted for preauthorization. |
59 | Merchant | Error: Partial cancellation is not allowed. |
59 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
61 | Customer | Error: The manual activation of the order is not allowed. |
61 | Merchant | Error: The manual activation of the order is not allowed. |
62 | Customer | Error: The order amount submitted for manual activation has changed in comparison to the amount submitted for preauthorization. |
62 | Merchant | Error: The order amount submitted for manual activation has changed in comparison to the amount submitted for preauthorization. |
63 | Customer | Error: The total amount of partial cancellation must not exceed the total order value. |
63 | Merchant | Error: The total amount of partial cancellation must not exceed the total order value. |
64 | Customer | Error: When removing all articles from the order the reduction amount must not deviate from the order amount. |
64 | Merchant | Error: When removing all articles from the order the reduction amount must not deviate from the order amount. |
65 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
65 | Merchant | Error: The submitted value [parameter |
66 | Customer | Error: Orders with an amount of zero are not supported. |
66 | Merchant | Error: Orders with an amount of zero are not supported. |
67 | Customer | Error: Please verify your input data. The submitted sort code is invalid. |
67 | Merchant | Error: Please verify your input data. The submitted sort code is invalid. |
68 | Customer | Error: Please verify your input data. The submitted account number is invalid. |
68 | Merchant | Error: Please verify your input data. The submitted account number is invalid. |
69 | Customer | Error: Please verify your input data. The submitted bank account is invalid. |
69 | Merchant | Error: Please verify your input data. The submitted bank account is invalid. |
71 | Merchant | Authorization failure. |
71 | Customer | Error: An internal error occurred. Please try again later. |
72 | Customer | Error: The submitted value for field [parameter] must equal one of the following values: [list] |
72 | Merchant | Error: The submitted value for field [parameter] must equal one of the following values: [list] |
73 | Customer | Error: An internal error occurred. Please try again later. |
73 | Merchant | Error: Only positive article quantities are allowed for partial cancellation (Field [parameter]). |
74 | Customer | Error: An internal error occurred. Please try again later. |
74 | Merchant | Error: The consistency check for the values submitted for the order with Transaction Credit failed. |
75 | Customer | Error: An internal error occurred. Please try again later. |
75 | Merchant | Error: The activation delay must not exceed [baseValue] days. |
76 | Customer | Error: An internal error occurred. Please try again later. |
76 | Merchant | Error: The submitted number of instalments is not allowed. |
77 | Customer | Error: The value submitted for field [parameter] must be greater than [baseValue]. |
77 | Merchant | Error: The value submitted for field [parameter] must be greater than [baseValue]. |
78 | Customer | Error: An internal error occurred. Please try again later. |
78 | Merchant | Error: No article list was submitted or the article list is empty. |
79 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
79 | Merchant | Error: The submitted IP address originates from a local network. |
81 | Merchant | Error: For this shop the payment method [parameter] is not allowed. |
81 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
82 | Merchant | Error: Orders from business clients using payment method [parameter] are not enabled for this shop. |
82 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
83 | Customer | Error: The value for the field [parameter] must be greater than or equal [baseValue]. |
83 | Merchant | Error: The value for the field [parameter] must be greater than or equal [baseValue]. |
84 | Customer | Error: The value for the field [parameter] must be smaller than or equal [baseValue]. |
84 | Merchant | Error: The value for the field [parameter] must be smaller than or equal [baseValue]. |
85 | Customer | Error: There was no list with due dates submitted or the XML structure of the list is invalid. |
85 | Merchant | Error: There was no list with due dates submitted or the XML structure of the list is invalid. |
86 | Customer | Error: The date for the field [parameter] must be in the future. |
86 | Merchant | Error: The date for the field [parameter] must be in the future. |
87 | Customer | Error: Orders from country [address.country] are not allowed. |
87 | Merchant | Error: Orders from country [address.country] are not allowed. |
88 | Customer | Error: The currency [currency] is not supported. |
88 | Merchant | Error: The currency [currency] is not supported. |
89 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
89 | Merchant | Error: The portal is deactivated. |
91 | Customer | Error: For customers from country [parameter] the Billpay payment methods are not available. |
91 | Merchant | Error: For customers from country [parameter] the Billpay payment methods are not available. |
92 | Customer | Error: The order amount is less than the minimum amount for orders with this payment method. |
92 | Merchant | Error: The order amount is less than the minimum amount for orders with this payment method. |
93 | Customer | Error: The maximum amount for orders with this payment method has been exceeded. |
93 | Merchant | Error: The maximum amount for orders with this payment method has been exceeded. |
94 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
94 | Merchant | Error: The submitted currency has changed compared to the preauthorization request. |
95 | Customer | Error: The country [country] is not supported. |
95 | Merchant | Error: The country [country] is not supported. |
96 | Customer | Error: An internal error occurred. |
96 | Merchant | Error: Invalid order status for this operation. |
97 | Customer | Error: Please verify your input data. The selected legal form is invalid for country [country]. |
97 | Merchant | Error: Please verify your input data. The selected legal form is invalid for country [country]. |
98 | Customer | Error: Please specify a value for the field [parameter]. |
98 | Merchant | Error: Please specify a value for the field [parameter]. |
99 | Customer | Error: Your submission for field [parameter] contains illegal characters. |
99 | Merchant | Error: Your submission for field [parameter] contains illegal characters. |
111 | Customer | Error: Please try again later. An internal error occurred. |
111 | Merchant | Error: The customer data must not change when using the payment control option. |
112 | Merchant | Error: Invalid preauthorization. For the current portal payment control option is enabled. |
112 | Customer | Error: Please try again later. An internal error occurred. |
113 | Merchant | Error: The request was declined because of suspected fraud. |
113 | Customer | Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
114 | Merchant | Error: Activation amount is incorrect |
114 | Customer | Error: An error has occurred |
115 | Customer | Error: An error has occurred |
115 | Merchant | Error: The total activation amount for the shipping fees exceeds the available amount for the shipping fee. |
116 | Customer | Error: An error has occurred |
116 | Merchant | Error: Negative order total |
117 | Merchant | Error: Activation is empty |
117 | Customer | Error: An error has occurred |
118 | Customer | Error: An error has occurred |
118 | Merchant | Error: No sub orders found |
119 | Customer | Error: An error has occurred |
119 | Merchant | Error: Item was already activated |
121 | Customer | Error: An error has occurred |
121 | Merchant | Error: Partial activation is not allowed |
122 | Customer | Error: An error has occurred |
122 | Merchant | Error: This operation is not permitted for this payment method. |
123 | Customer | Error: An error has occurred |
123 | Merchant | Error: Invoice number is not unique for this order |
124 | Customer | Error: An error has occurred |
124 | Merchant | Error: Reference should not contain hash (#) symbol |
125 | Customer | Error: An internal error occurred. Please try again later. |
125 | Merchant | Error: The order has not been captured. |
126 | Customer | Error: An internal error occurred. Please try again later. |
126 | Merchant | Error: Increasing the order amount is not allowed for the current status of the order. |
127 | Customer | Error: An internal error occurred. Please try again later. |
127 | Merchant | Error: The supplied number of rates is invalid. |
128 | Customer | Error: An internal error occurred. Please try again later. |
128 | Merchant | Error: Increasing the order amount is not allowed for the current status of the order. |
129 | Customer | Error: An internal error occurred. Please try again later. |
129 | Merchant | Error: The amount of the partial activation exceeds the total amount of the order. |
131 | Customer | Error: The order reference number was not found. |
131 | Merchant | Error: The order reference number was not found. |
132 | Customer | Error: Please verify your input data. The submitted IBAN is invalid. |
132 | Merchant | Error: Please verify your input data. The submitted IBAN is invalid. |
133 | Customer | Error: Please verify your input data. The submitted BIC is invalid. |
133 | Merchant | Error: Please verify your input data. The submitted BIC is invalid. |
134 | Customer | Error: Please select another payment method. The SEPA mandate for this bank account has been revoked. |
134 | Merchant | Error: The SEPA mandate for this account has been revoked by the customer. |
135 | Customer | Error: Please select another payment method or try again later. An internal error occurred. |
135 | Merchant | Error: Requests for this payment method configuration can only be processed in auto capture mode. |
136 | Customer | The BIC and IBAN country codes do not match. |
136 | Merchant | The BIC and IBAN country codes do not match. |
137 | Customer | Error: Please provide an account holder. |
137 | Merchant | Error: Please provide an account holder. |
138 | Customer | Error: The value for account holder contains invalid characters. |
138 | Merchant | Error: The value for account holder contains invalid characters. |
139 | Customer | Error: The request is already being processed. Please wait until the processing is completed. |
139 | Merchant | Error: The request is already being processed. Please wait until the processing is completed. |
141 | Customer | Error: An internal error occurred. Please try again later. |
141 | Merchant | Error: This request is invalid because for this customer a subsequent request was performed. |
142 | Customer | Error: Please select another payment method. Unfortunately we cannot offer the selected payment method from Billpay to you for this transaction. |
142 | Merchant | Error: The parameter expecteddaystillshipping is less than the allowed minimum |
143 | Customer | Error: The shipping fees must not remain in the order if the rest of the order is cancelled. |
143 | Merchant | Error: The shipping fees must not remain in the order if the rest of the order is cancelled. |
144 | Customer | Error: Please try again later. An internal error occurred. |
144 | Merchant | Error: The cart provided for the order change is inconsistent (Total of all item prices + shipping costs - rebates must be equal to the total order amount). |
145 | Merchant | Error: At least one of the articles provided for an invoice does not exist for this order. |
145 | Customer | Error: Please try again later. An internal error occurred. |
146 | Customer | Error: Please try again later. An internal error occurred. |
146 | Merchant | Error: The invoice related information contained in the request is either invalid for this payment method or does not match the existing invoices. |
147 | Customer | Error: Please try again later. An internal error occurred. |
147 | Merchant | Error: The invoice related information contained in the request is invalid for instalment based payment methods. |
148 | Merchant | Error: At least one of the invoices contained in the request does not exist for this order. |
148 | Customer | Error: Please try again later. An internal error occurred. |
149 | Customer | Error: Please try again later. An internal error occurred. |
149 | Merchant | Error: The cart provided for the change of one of the invoices is inconsistent (Total of all item prices + shipping costs - rebates must be equal to the total order amount). |
151 | Customer | Error: Please try again later. An internal error occurred. |
151 | Merchant | Error: The invoiced quantity of an article exceeds the order quantity of this article. |
152 | Customer | Error: Merchants can not report customer payments for more than the current outstanding activated amount of the order. |
152 | Merchant | Error: Merchants can not report customer payments for more than the current outstanding activated amount of the order. |
153 | Customer | Error: Please try again later. An internal error occurred. |
153 | Merchant | Error: The validation of the XML request failed. |
Settlement Files
Every merchant will receive access to a weekly settlement file via download link in the BillPay BackOffice using the dedicated “controlling” user credentials.
You will receive an e-mail notification as soon as the weekly settlement file is available. The settlement period runs from Monday to Sunday of the prior week. The files are available to be downloaded in the following formats:
- CSV
Included are the individual orders accrued during the billing period as well as their amount and the fees incurred.
Index | Column | Format | Description |
---|---|---|---|
1 | Transaction Type ID | N..2 | 0: transaction fee (minimum) 1: setup fee 2: monthly fee 3: transaction fee 4: cancellation fee 15: VAT recovery 7,00% 16: VAT recovery 19,00% 17: credit check costs 18: direct customer payment 19: Dunning fee coverage |
2 | Transaction Type | AN..50 | Description of fee |
3 | Portal ID | N..6 | BillPay portal ID |
4 | Merchant Reference Number | AN..40 | The merchant’s order reference, submitted with the preauthorization |
5 | Merchant Customer Number | AN..40 | The merchant’s customer ID |
6 | BillPay Customer Number | N..10 | BillPay’s customer ID |
7 | Debt ID | N..10 | BillPay’s debt ID |
8 | Debt Amount [3 character currency code (e.g. “EUR”)] | (-)Float(8:2) | The total amount to be paid out to the merchant |
9 | Disagio [%] | Float(1:4) | BillPay fee in percent |
10 | Transaction Fee [3 character currency code (e.g. “EUR”)] | (-)Float(8:2) | BillPay fee in EUR |
11 | Order Date | YYYMMDD | Order date |
12 | Activation Date | YYYYMMDD | Date of activation |
13 | Due Date | YYYYMMDD | The customer’s payment due date |
14 | Customer Country | A..3 | The customer’s country (e.g. DEU) ISO3166 (alpha-3) |
Additionally, the files can be downloaded via a https request, which lends itself to being built into an automated process. The link for the https request would be as follows:
https://admin.billpay.de/MerchantInvoiceDownload.action?mh=##########&cw=12&year=2017&format=csv&type=1
Get Variable Descriptions in the Above URL
Variable | Format | Info |
---|---|---|
mh | string | This is a shop/portal specific indentifying hash. BillPay will provide you with this value upon request. |
cw | ISO 8601: WW | The calendar week of the settlement file |
year | ISO 8601:YYYY | The year of the desired settlement file (YYYY format) |
format | string (csv or pdf) | The format of the document (csv, pdf) |
type | positive int | There are different settlement files depending upon the country or payment method. BillPay will provide you the file types you will need upon request. |
Downloads
The preferred BillPay payment logos for display on your website and in your checkout, as well as all of our programming libraries can be downloaded here: https://www.billpay.de/en/shopintegration/downloads/
Version history
[2.2.0] - 2017-10-04
The version 2.2.0 is not fully backwards compatible to 2.1.0
Added
Request: getOrderDetails.xsd
Response: getOrderDetails.xsd
Request: prescore.xsd
- attribute expecteddaystillshipping
Changed
- Request: shiftDueDate.xsd
- changed attribute newduedate from type date to the name shiftdatesby from the type integer in the range 1 to 90
[2.1.0] - 2017-06-19
The version 2.1.0 is not fully backwards compatible to 2.0.0
Changed
- Request: preauthorize.xsd
Request: prescore.xsd
- allowed values from attribute historicaltripcurrency changed from char to enum
Response: invoiceCreated.xsd
- element name has been changed from “invoice_numbers” to “assigned_invoice_number”. Only the invoice_number node for the currently activated suborder is returned.
[2.0.0] - 2017-07-03
Added
Notificatons: asyncCapture.xsd
Request: cancel.xsd
Request: capture.xsd
Request: editCartContent.xsd
Request: getBillPayBankData.xsd
Request: invoiceCreated.xsd
Request: partialCancel.xsd
Request: preauthorize.xsd
Request: prescore.xsd
Request: reportCustomerPayment.xsd
Request: shiftDueDate.xsd
Request: updateOrder.xsd
Response: cancel.xsd
Response: capture.xsd
Response: editCartContent.xsd
Response: getBillPayBankData.xsd
Response: invoiceCreated.xsd
Response: partialCancel.xsd
Response: preauthorize.xsd
Response: prescore.xsd
Response: reportCustomerPayment.xsd
Response: shiftDueDate.xsd
Response: updateOrder.xsd
Should you have any questions relating to this manual and/or integrating BillPay payment methods, please feel free to contact us via support@billpay.de.