XML Schnittstelle

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

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

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

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

Webservice URL

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

Base URLs

Attention: The XML interface only works when using the HTTPS protocol. Any request sent through the HTTP protocol will not be accepted.

Overview: Frontend XMLs service requests

"classical scoring"

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

"Prescoring"

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

Overview: Backend XML service requests

XML service Meaning Time of execution Service URL Mandatory? Backoffice? Response
Activation Invoice: Setting of the payment due date (20 / 30 days); Direct Debit/PayLater: Initialization of the debit process When generating the invoice; usually this action is triggered by a backend workflow or scheduled task/cron job. [Base-URL]/invoiceCreated Y Y Invoice: BillPay bank account data and payment due date; Direct Debit/PayLater: -
Cancellation A full cancellation of the existing debt. Usually this action is triggered by a backend workflow or scheduled task/cron job. [Base-URL]/cancel N Y -
Editing the Cart Any change in the content of the existing cart or the included fees/rebates of the order. Usually is triggered when items were returned by the customer or the order has been adjusted before shipping. [Base-URL]/editCartContent N N -
Update Order Update the order id (reference number). Used in cases where the order is completed before the order reference number is available/known. Order process; after the order is placed in the shop [Basis-URL]/updateOrder N N -
Get Bank Details Only for invoice orders. Retrieve the payment details for a given order for display on the order invoice From the backend, in cases where the bank details can't be used/saved from the capture/invoiceCreated response. [Basis-URL]/getBillPayBankData N N BillPay bank account and payment due date for the invoice.
Report of a direct customer payment Only invoice: the merchant reports a direct payment made by the customer to his/her account. From the backend, after accounting has discovered that there has been a direct transfer of funds to the merchant bank account. [Basis-URL]/reportCustomerPayment N Y -