Using Billpay Payment Method Pre-scoring, merchants can filter the payment options shown to each customer before they are displayed. This helps to prevent the end user from being presented a negative alert message, enabling for a more positive user-experience and dramatically increasing the conversion rate. This option requires every customer to undergo a credit and identity check before landing on the payment method selection page. This service can be viewed as an alternative to scoring a customer after he/she has chosen to use a Billpay payment method.

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

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

Please Note: The use of this request is only available to merchants whose contract includes this option. In addition, only the most recent prescoring request for a given end-customer can be captured.

Request

XML Header

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

Data Node

There are no required fields in the data.

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

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 mandatory when the country is 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 default risk, this feature can only be offered when specifically agreed upon in the merchants contract with BillPay.

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

*see addendum defaults for business 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)

In case you are shipping to 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 concerning the purchased products are collected in the article_data node. Every unique article is represented by an individual "article" 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>

Total Node (Generic details about the order)

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

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

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.

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

Full XML example

<?xml version="1.0" encoding="UTF-8"?>
<data api_version="1.5.18">
  <trace trace_id="5efba73acc901f0414e66bcc74953869bcb68dba" />
  <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" />
  <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> 

Response

Data Node (Result of the identity and credit check)

The data node contains all relevant information about the scoring result. In addition to the plain text result ("APPROVED" / "DENIED") it contains a unique BillPay transaction ID (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"/>

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.

Attribute Mandatory Type Possible Values Details
name + String AN..50 Account holder
customer_group + String "p": Consumer (B2C)
"b": business customer (B2B)
Customer group
payment_type + String 1: Invoice
2: Direct Debit
3: Transaction Credit
4: PayLater
ID of chosen payment method
additional_data - String XML fragment Additional data specific to payment method
<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>