Preauthorize

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

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

Request

XML Header

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

Data Node

Attribute	Type	Possible Values	Details
tcaccepted	Int	0/1	Boolean flag that indicates if the customer has accepted the BillPay terms of service / the data protection policy
expecteddaystillshipping	Int		Payment type 1-4: the expected delay in shipping, Payment Type 7: Amount of days until the customer will depart for their trip.
capturerequestnecessary	Int	Standard: 0	Boolean flag that indicates if the preauthorization is done in Autocapture mode; Attention: The standard is set to "0"; any changes to this standard have to be agreed upon by te BillPay integration support.
paymenttype	Int	1: Invoice 2: Direct Debit 3: Transaction Credit 4: PayLater 7: PayLater Collateral Promise (for Travel Industry)	Id of the desired payment method

<data 
    tcaccepted="1" 
    expecteddaystillshipping="0" 
    capturerequestnecessary="0" 
    paymenttype="1" 
    api_version="1.5.11">
    <!-- Request Daten -->
    </data>

Default Params Node (Merchant Credentials)

Attribute	Type	Details
mid	Int	Merchant Id
pid	Int	Portal Id
bpsecure	String	MD5 hash of the API security key (delivered by BillPay)

    <default_params 
        mid="4441" 
        pid="6021" 
        bpsecure="25d55ad283aa400af464c76d713c07ad"/>

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.

Parameters specific to the Payment Method Pre-scoring	Mandatory	Data format	Comments
is_prescored	+	0: No 1: Yes	Value indicates if a prescore -request was sent previously. Please note: If the Payment Method Pre-scoring is activated, the value "1" has to be sent.
bptid	+	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.

    <preauth_params 
        is_prescored="1" 
        bptid="1aa2fb2d-2b78-4393-bf06-be0012dda337" />

Customer Details Node (customer billing address)

Attribute	Mandatory	Type	Possible Values	Details
customerid	-	String	AN..40	Customer ID in the merchant system (Allowed characters are: 0-9, a-z, A-Z, .,-,_,/)
customertype	+	Int	g: Guest n: New Customer e: Existing Customer	Type of customer
salutation	+	String	Default: See addendum `Saluations`	Salutation
title	-	String	AN..20	academic title (e.g. "Dr.")
firstName	+	String	AN..40	First name
lastName	+	String	AN..40	Last name
street	+	String	AN..40	Street
streetNo	-	String	AN..7	House number
addressAddition	-	String	AN..40	Address addition
zip	+	String	AN..7	ZIP code
city	+	String	AN..40	City
country	+	String	ISO3166-aplha-3	Customer Country Code (z.B."DEU")
email	+	String	AN..40 (excl. non-valid special characters)	Email address
phone	-*	String	AN..40	Phone number
cellPhone	-	String	AN..40	Mobile number
birthday	-*	String	JJJJMMTT	Date of birth
language	+	String	ISO639-1	Customer language (e.g. "de")
ip	+	String	IPv4 & IPv6	IP address of the client
customerGroup	+	String	p: Private b: Business	Customer group

    <customer_details 
        customerid="123456" 
        customertype="e" 
        salutation="Herr" 
        title="" 
        firstName="Thomas" 
        lastName="Testkunde" 
        street="Tinnowitzerstrasse 1" 
        streetNo="" 
        addressAddition="" 
        zip="10115" 
        city="Berlin" 
        country="DEU" 
        email="anymail@gmx.de" 
        phone="03012345678" 
        cellPhone="" 
        birthday="19741012" 
        language="de" 
        ip="127.0.0.1" 
        customerGroup="p" />

phone is a mandatory field when paymenttype equals 3, 4 or 7 (all installments products) or when country equals "NLD"

birthday is a mandatory field when customerGroup equals "p"

Shipping Details Node (customer shipping address)

This node contains either the boolean flag useBillingAddress to be set to "true" ("1") or the full alternate shipping address. Attention: Due to the high risk of default, this feature can only be offered when specifically agreed upon in the merchants contract with BillPay.

*The fields for the alternate shipping address only need to be populated if the parmater useBillingAddress is set to "0"

*see addendum defaults for business cusomers

Attribute	Mandatory	Type	Possible Values	Details
useBillingAddress	+	Boolean	BOOLEAN 1/0	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`	Salutation
title	+*	String	AN..20	academic title (e.g. "Dr.")
firstName	+*	String	AN..40	First name
lastName	+*	String	AN..40	Last name
street	+*	String	AN..40	Street
streetNo	+*	String	AN..7	House number
addressAddition	-	String	AN..40	Address addition
zip	+*	String	AN..7	ZIP code
city	+*	String	AN..40	City
country	+*	String	ISO3166-aplha-3	Customer country code (z.B."DEU")
phone	+*	String	AN..40	Phone number
cellPhone	-	String	AN..40	Mobile number

    <shipping_details 
        useBillingAddress="1" 
        salutation="" 
        title="" 
        firstName="" 
        lastName="" 
        street="" 
        streetNo=""
        addressAddition="" 
        zip="" 
        city="" 
        country="" 
        phone="" 
        cellPhone="" />

Company Details Node (Details about business customers)

If the order is being placed by a business customers (`customertype´ = "b"), additional information needs to be collected about the business.

Attribute	Mandatory	Type	Possible Values	Details
name	+	String	AN..200	Registered name of the company
legalForm	+	String	Defauls: see addendum `legal forms`	Company legal form
registerNumber	+*	String	AN..20	Company register number
holderName	+*	String	AN..100	Owner's full name
taxNumber	-	String	valid tax ID (DEXXXXXXXXX)

    <company_details
        name="Testfirma"
        legalForm="GmbH"
        registerNumber="HRB 122 029 B"
        holderName="Testinhaber"
        taxNumber="DE268874183" />

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.

*Important! Article IDs have to be unique!

Attribute	Mandatory	Type	Possible Values	Details
articleid	+	String	AN..20	Unique article ID
articlequantity	+	Int	N..7	Article quantity
articlename	+	String	AN..50	Article name
articlecategory	-	String	AN..50	Article Category
articlesubcategory1	-	String	AN..50	Article Sub-Category
articlesubcategory2	-	String	AN..50	Article Sub-Category
articleprice	+	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)

    <article_data>
         <article 
            articleid="1234" 
            articlequantity="2" 
            articlename="Shirt" 
            articlecategory="Clothing"
            articlesubcategory1="Van Laack"
            articleprice="10084" 
            articlepricegross="12000" />
        <article 
            articleid="2345" 
            articlequantity="1" 
            articlename="Hose" 
            articlecategory="Clothing"
            articlesubcategory1="Ralph Lauren"
            articleprice="16807" 
            articlepricegross="20000" />
    </article_data>

Bank Data Node (Customer Bank Info)

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

Attribute	Mandatory	Type	Possible values	Details
accountholder	+ (if paymentType in {2,3,4,7})	String	AN..100	First and Lastname of account holder
accountnumber	+ (if paymentType in {2,3,4,7})	Int	AN..30	International Bank Account Number
sortcode	+ (if paymentType in {2,3,4,7}) AND LAND NOT DE	Int	AN..11	Bank Identifier Code

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

Total Node (Generic details about the order)

To total node contains all generic information about the order and all connected fees / rebates.

*If sticking to the standard: capturerequestnecessary="0"

Attribute	Mandatory	Type	Possible values	Details
shippingname	+	String	AN..50	Shipping method name (e.g. "Express")
shippingprice	+	Int	N..7	net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross	+	Int	N..7	gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
rebate	+	Int	N..7	positive net value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
rebategross	+	Int	N..7	positive gross value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
carttotalprice	+	Int	N..7	net value of the order total (1,00 EUR = 100)
carttotalpricegross	+	Int	N..7	gross value of the order total (1,00 EUR = 100)
currency	+	String	ISO4217	3-digit currency code of the order (e.g. "EUR")
reference	+*	String	AN..40	Unique order ID in the merchant system (allowed characters: 0-9, a-z, A-Z,.,-,_,/)

    <total 
        shippingname="Express Versand" 
        shippingprice="840" 
        shippingpricegross="1000" 
        rebate="1681" 
        rebategross="2000" 
        carttotalprice="36134" 
        carttotalpricegross="43000" 
        currency="EUR"
        reference="1773673332" />

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 his widgets.

Attribute	Mandatory	Type	Possible Values	Details
session_id	+	String	AN..100	a session ID (must be equal to the session ID set in the JavaScript widget configuration script)

    <fraud_detection session_id="97d3d1b1cc6b0686bbc1f19feec80e6c"/>

Rate Request Node

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

Attribute	Mandatory	Type	Possible Values	Details
term	+*	Int	N..7	Term of the installment plan
ratecount	+	Int	N..7	Count of installments to be paid during the term
totalamount	+	Int	N..7	Total amount of the installments plan including the transaction credit interest / PayLater fee

<rate_request ratecount="6" term="6" totalamount="45520"/>

Async Capture Request Node (Prepayment process)

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

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

Attribute	Mandatory?	Type	Possible Values	Details
redirect_url	+	String	AN	Shop-sided result page after successful / failed prepayment.
notify_url	+	String	AN	Shop-sided webservice URL for async BillPay 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>

Sample XML: Invoice B2C

<?xml version="1.0" encoding="UTF-8"?>
<data tcaccepted="1" expecteddaystillshipping="0" capturerequestnecessary="0" paymenttype="1" api_version="1.5.11">
   <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
   <customer_details customerid="" customertype="e" salutation="Herr" title="" firstName="Thomas" lastName="Testkunde" street="Tinnowitzerstrasse 1" streetNo="" addressAddition="" zip="10115" city="Berlin" country="DEU" email="anymail@gmx.de" phone="03012345678" cellPhone="" birthday="19741012" language="de" ip="127.0.0.1" customerGroup="p" />
  <shipping_details useBillingAddress="1" salutation="" title="" firstName="" lastName="" street="" streetNo="" addressAddition="" zip="" city="" country="" phone="" cellPhone="" />
  <total shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="36134" carttotalpricegross="43000" currency="EUR" reference="1773673332" reference2="" />
  <article_data>
    <article articleid="1234" articlequantity="2" articlename="Shirt" articlecategory="Clothing" articlesubcategory1="Van Laack" articleprice="10084" articlepricegross="12000" />
    <article articleid="2345" articlequantity="1" articlename="Hose" articlecategory="Clothing" articlesubcategory1="Ralph Lauren" articleprice="16807" articlepricegross="20000" />
  </article_data>
  <fraud_detection session_id="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Sample XML: Invoice B2B

<?xml version="1.0" encoding="UTF-8"?>
<data tcaccepted="1" expecteddaystillshipping="0" capturerequestnecessary="0" paymenttype="1" api_version="1.5.18">
  <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
  <customer_details customerid="" customertype="e" salutation="Herr" title="" firstName="Thomas" lastName="Testkunde" street="Tinnowitzerstrasse 1" streetNo="" addressAddition="" zip="10115" city="Berlin" country="DEU" email="anymail@gmx.de" phone="03012345678" cellPhone="" birthday="19741012" language="de" ip="127.0.0.1" customerGroup="b" />
  <shipping_details useBillingAddress="1" salutation="" title="" firstName="" lastName="" street="" streetNo="" addressAddition="" zip="" city="" country="" phone="" cellPhone="" />
  <company_details name="Test Company" legalForm="gmbh" registerNumber="HRB 9874568" holderName="Thomas Testkunder" taxNumber="DE268874183" />
  <total shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="36134" carttotalpricegross="43000" currency="EUR" reference="761463697" reference2="" />
  <article_data>
    <article articleid="1234" articlequantity="2" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
    <article articleid="2345" articlequantity="1" articlename="Hose" articleprice="16807" articlepricegross="20000" />
  </article_data>
  <fraud_detection session_id="97d3d1b1cc6b0686bbc1f19feec80e6c" />
</data>

Sample XML: Direct Debit

<?xml version="1.0" encoding="UTF-8"?>
<data tcaccepted="1" expecteddaystillshipping="0" capturerequestnecessary="0" paymenttype="2" api_version="1.5.18">
  <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
  <customer_details customerid="" customertype="e" salutation="Herr" title="" firstName="Thomas" lastName="Testkunde" street="Tinnowitzerstrasse 1" streetNo="" addressAddition="" zip="10115" city="Berlin" country="DEU" email="anymail@gmx.de" phone="03012345678" cellPhone="" birthday="19741012" language="de" ip="127.0.0.1" customerGroup="p" />
  <shipping_details useBillingAddress="1" salutation="" title="" firstName="" lastName="" street="" streetNo="" addressAddition="" zip="" city="" country="" phone="" cellPhone="" />
  <bank_account accountholder="Thomas Testkunde" accountnumber="DE89370400440532013000" sortcode="" />
  <total shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="36134" carttotalpricegross="43000" currency="EUR" reference="1519088641" reference2="" />
  <article_data>
    <article articleid="1234" articlequantity="2" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
    <article articleid="2345" articlequantity="1" articlename="Hose" articleprice="16807" articlepricegross="20000" />
  </article_data>
  <fraud_detection session_id="12a854eb6758ec7770860a230269275b" />
</data>

Sample XML: PayLater/Transaction Credit

<?xml version="1.0" encoding="UTF-8"?>
<data tcaccepted="1" expecteddaystillshipping="0" capturerequestnecessary="0" paymenttype="4" api_version="1.5.18">
  <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
  <customer_details customerid="" customertype="e" salutation="Herr" title="" firstName="Thomas" lastName="Testkunde" street="Tinnowitzerstrasse 1" streetNo="" addressAddition="" zip="10115" city="Berlin" country="DEU" email="anymail@gmx.de" phone="03012345678" cellPhone="" birthday="19741012" language="de" ip="127.0.0.1" customerGroup="p" />
  <shipping_details useBillingAddress="1" salutation="" title="" firstName="" lastName="" street="" streetNo="" addressAddition="" zip="" city="" country="" phone="" cellPhone="" />
  <rate_request ratecount="6" term="6" totalamount="45520" />
  <bank_account accountholder="Thomas Testkunde" accountnumber="DE89370400440532013000" sortcode="" />
  <total shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="36134" carttotalpricegross="43000" currency="EUR" reference="1747930987" reference2="" />
  <article_data>
    <article articleid="1234" articlequantity="2" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
    <article articleid="2345" articlequantity="1" articlename="Hose" articleprice="16807" articlepricegross="20000" />
  </article_data>
  <fraud_detection session_id="12a854eb6758ec7770860a230269275b" />
  <async_capture_request>
    <redirect_url>
<![CDATA[http://google.de/my_shops_paylater_giropay_redirect_url.php]]>
  </redirect_url>
  <notify_url>
<![CDATA[http://google.de/my_shops_paylater_giropay_notify_url.php]]>
  </notify_url>
  </async_capture_request>
</data>

Response

Data Node (Result of the identity and credit check)

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

Attribute	Mandatory	Type	Possible Values	Details
status	+	String	"APPROVED" / "DENIED"	Status of the identity and credit check
bptid	+	String	AN..50	Unique BillPay transaktion ID
error_code	+	Int	N..3	Error code (0: No error); For an extensive list of all error codes and messages please refer to the following list `Error codes`
merchant_message	-	String	AN..200	Detailled error message for the merchant
customer_message	-	String	An..200	Detailled error message to be shown to the customer

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data 
    bptid="1aa2fb2d-2b78-4393-bf06-be0012dda337" 
    customer_message="" 
    error_code="0" 
    merchant_message=""
    status="APPROVED">
<!-- weitere Antwortdaten -->
</data>

Corrected Address Node (Optional: Normalized customer address)

This node returns the normalized customer address.

Attribute	Mandatory?	Type	Possible Values	Details
city	+	String	AN..50	Normalized city
country	+	String	ISO3166 alpha-3	Normalized country code (z.B. "DEU")
street	+	String	AN..50	Normalized street
streetNo	+	String	AN..15	Normalized house number
zip	+	String	AN..7	Normalized ZIP code

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

Invoice Bank Account Node (only "Invoice" & "Transaction Credit CHE", if `capturerequestnecessary` = "0")

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

Attribute	Mandatory?	Type	Possible Values	Details
account_holder	+	String	AN..255	Account holder
account_number	+	String	AN..40	BillPay IBAN
bank_code	+	String	AN..16	BillPay BIC
bank_name	+	String	AN..255	Name of the BillPay bank
invoice_reference	+	String	AN..255	Transaction purpose

<invoice_bank_account 
    account_holder="BillPay GmbH" 
    account_number="DE07312312312312312" 
    bank_code="BELADEBEXXX" 
    bank_name="Sparkasse Berlin" 
    invoice_reference="BP555666777/9999"/>

Hire Purchase Node (only for PayLater and Transaction Credit)

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

Attribute	Mandatory?	Type	Possible Values	Details
instl_plan		Parent node
num_inst		Int	N	Number of installments
calc		Child node of the instl_plan node.
-> duration		Int	N	Duration of the payment plan in months
-> fee_percent		Int	N	PayLater fee (%)
-> fee_total		Int	N	Total PayLater fees
-> pre-payment		Int	N	Deposit amount
-> total_amount		Int	N	Total amount of the PayLater order (including the fees)
-> eff_annual		Int	N	Annual effective interest rate (%)
-> nominal		Int	N	Annual nominal interest rate (%)
instl_list	(node)	Child node of the instl_plan node.
-> instl	(node)	Child node of the instl_list node.
date		DATE	YYYYMMDD	Date of the installment
type		String	AN	Type of Installment („immediate“, „first“, „date“, „fee“)

Response

<hire_purchase>
    <instl_plan num_inst="6">
      <calc>
        <duration>
          6
        </duration>
        <fee_percent>
          6.00
        </fee_percent>
        <fee_total>
          2520
        </fee_total>
        <pre_payment>
          0
        </pre_payment>
        <total_amount>
          45520
        </total_amount>
        <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>
  </hire_purchase>

For developers XML API Preauthorize

Request

XML Header

Data Node

Default Params Node (Merchant Credentials)

Preauth Params

Customer Details Node (customer billing address)

Shipping Details Node (customer shipping address)

Company Details Node (Details about business customers)

Article Data Node (List of all ordered articles)

Bank Data Node (Customer Bank Info)

Total Node (Generic details about the order)

Fraud Detection Node

Rate Request Node

Async Capture Request Node (Prepayment process)

Sample XML: Invoice B2C

Sample XML: Invoice B2B

Sample XML: Direct Debit

Sample XML: PayLater/Transaction Credit

Response

Data Node (Result of the identity and credit check)

Corrected Address Node (Optional: Normalized customer address)

Invoice Bank Account Node (only "Invoice" & "Transaction Credit CHE", if capturerequestnecessary = "0")

Hire Purchase Node (only for PayLater and Transaction Credit)

Response

Invoice Bank Account Node (only "Invoice" & "Transaction Credit CHE", if `capturerequestnecessary` = "0")