An Entwickler XML API Prescore

Mit der Zahlartensteuerung von BillPay können Onlinehändler vor Anzeige der Zahlarten-Auswahlseite in ihrem Onlineshop kundenindividuell steuern, welche BillPay-Zahlarten den Endkunden angeboten werden sollen. Mit dieser Vorauswahl wird ermöglicht, dass Zahlarten, für die der Kunde nicht zugelassen sind, gar nicht erst eingeblendet werden. Dadurch sinkt die Kaufabbruchquote und die Konversionsrate steigt signifikant. Der Einsatz der Zahlartensteuerung impliziert, dass die Prüfung des Endkunden auf Identität und Bonität bereits vor Auswahl der Zahlart stattfindet. Die BillPay-Zahlartensteuerung ist damit als Alternative zur Prüfung der Endkundenanfrage nach Auswahl einer BillPay-Zahlart zu sehen.

Ein Händlerportal bei BillPay kann entweder mit Zahlartensteuerung oder ohne Zahlartensteuerung arbeiten, aber nicht beides zur gleichen Zeit.

Hinweis: Es ist zu beachten, dass die Nutzung der entsprechenden XML-Service-Requests für die Zahlartensteuerung nur möglich ist, wenn der Händler-Account bei BillPay dafür freigeschaltet wurde. Voraussetzung für die Freischaltung ist, dass ein entsprechender Vertrag mit BillPay abgeschlossen wurde.

Die prescore-Antwort enthält eine Liste der erlaubten Zahlarten und einige zahlartenspezifische Zusatzinformationen.

Wichtig! Die Antwort-Parameter sind nur solange gültig, solange alle Eingabeparameter des prescore-Request unverändert bleiben. Sobald der Kunde seine personenbezogenen Daten oder den Warenkorb ändert, muss der prescore-Request erneut gesendet werden. Zusätzlich, kann nur die letzte prescore Anfrage für einen Endkunden erfasst werden.

Request

XML Header

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

Data Knoten

<data api_version="1.5.11">
    <!-- Request Daten -->
</data>

Default Params Knoten (Händler Zugangsdaten)

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

Customer Details Knoten (Rechnungsadresse des Kunden)

    <customer_details 
        customerid="123456" 
        customertype="e" 
        salutation="Herr" 
        title="" 
        firstName="Thomas" 
        lastName="Testkunde" 
        street="Anystreet 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 ist Pflichtfeld wenn country gleich NLD

birthday ist Pflichtfeld wenn customerGroup gleich "p"

Shipping Details Knoten (Versandadresse des Kunden)

In diesem Knoten kann eine zur Rechnungsadresse abweichende Liederadresse übergeben werden. Achtung: Aus Risikogründen kann dieses Feature leider nicht allen Portalen angeboten werden und bedarf einer vertraglichen Einigung. Bitte sprechen Sie vorab mit einem unserer Mitarbeiter über diese Möglichkeit.

*Alle abweichenden Adressdaten müssen nur dann ausgefüllt werden, wenn useBillingAddress = 0

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

Company Details Knoten (Details zu Geschäftskunden)

Sollten Sie Ihre Ware an Geschäftskunden verkaufen (`customertype´ = "b"), müssen in diesem Knoten alle Details zu der Firma des Kunden übergeben werden.

*siehe Glossar Vorgaben für Geschäftskunden

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

Article Data Knoten (Liste der bestellten Artikel)

Im article_data-Knoten werden alle Informationen rund um die in der Bestellungen enthaltenen Warenkorbpositionen abgebildet. Pro einzigartigem Artikel wird ein `article´-Knoten gesetzt.

*Wichtig! IDs dürfen in einer Anfrage nicht mehrfach auftreten!

    <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 Knoten (Details zur Bestellung)

Im total-Knoten werden alle zusammenfassenden Informationen der Bestellung, sowie die händlerseitige Bestellnummer übergeben.

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

Fraud Detection Knoten (Betrugsprävention)

In diesem Knoten wird die für die Session des Kunden vergebene einzigartige ID übergeben. Diese dient der Bekämpfung von Betrug in Ihrem Shop und muss immer identisch mit der als "identifier" benannten ID in der Konfiguration des JavaScript Widgets sein.

    <fraud_detection session_id="97d3d1b1cc6b0686bbc1f19feec80e6c"/>

Vollständiges XML-Beispiel

<?xml version="1.0" encoding="UTF-8"?>
<data 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="Anystreet 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 Knoten (Ergebnis der Anfrage)

Der data-Knoten enthält alle Informationen darüber, ob der Kunde zur Zahlung via BillPay zugelassen wurde, und welche eindeutige ID (bptid) der gesendeten Anfrage vergeben wurde. Zudem wird eine Meldung zur Anzeige für den Kunden und eine Meldung für das Log der Händler mit übertragen.

<?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 Knoten (Optional: Korrigierte Kundenadresse)

In diesem Knoten gibt die BillPay Schnittstelle die normalisierte Adresse des Kunden zurück.

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

Allowed Methods Node

Dieser Knoten enthält die erlaubten Zahlarten im Falle einer positiven Antwort. Jeder Zahlart hat einen eigenen "payment_method" XML Knoten.

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