JavaScript-Widget

Einführung: Das BillPay JavaScript Widget

Der Kern der Shop-Integration ist das JavaScript-Widget für die Darstellung der BillPay-Zahlarten im Checkout. Mit dem BillPay Widget lässt sich die conversion-optimierte Darstellung der BillPay-Zahlarten in drei Schritten in Ihren bestehenden Checkout integrieren.

Für den Fall, dass Sie ein selbst entwickeltes Shopsystem verwenden oder BillPay für Ihr Shopsystem keine Pluginlösung anbietet, ist für die Darstellung der BillPay Zahlarten zwingend das Java-Script-Widget zu verwenden, welches eine reibungslose Integration gewährleistet.

Einbindung des BillPay JavaScript Widgets

Schritt 1: Laden des JavaScripts

Um das BillPay JavaScript Widget für die Anzeige der BillPay-Zahlarten nutzen zu können, müssen Sie das JavaScript Snippet in Ihr Shop Template einfügen. Anschließend steht eine Funktion namens billpayCheckout zur Verfügung, die im Anschluss benutzt wird.

<!-- 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');

</script>

Schritt 2: Konfiguration

Zur Konfiguration des JavaScript Widgets wird die billpayCheckout Funktion mit "options" als erster Parameter aufgerufen. Als zweiter Parameter wird ein JSON Objekt mit den shop- und kundenspezifischen Informationen erwartet.

Variable	Erklärung
checkout.form	jQuery Selector für das Checkout Form HTML Element
shop.apiKey	Öffentlicher API Schlüssel, den Sie von BillPay erhalten haben
shop.live	Definiert, ob der Checkout im Live oder Testmodus läuft
order.cartAmount	Warenkorbwert (Artikelwert exkl. Versandkosten und zusätzlicher Gebühren)
order.orderAmount	Gesamtbestellwert (inkl. Versandkosten und zusätzlicher Gebühren)
order.currency	ISO Code der Währung
customer.billing.salutation	Anrede
customer.billing.firstName	Vorname des Kunden
customer.billing.lastName	Nachname des Kunden
customer.billing.street	Straße der Kundenadresse
customer.billing.zip	PLZ der Kundenadresse
customer.billing.city	Ort der Kundenadresse
customer.billing.phoneNumber	Telefonnummer
customer.billing.countryIso2	ISO Code des Kundenlands
customer.billing.countryIso3	ISO Code des Kundenlands
customer.billing.dayOfBirth	Geburtsdatum
customer.language	Sprache des Kunden
customer.identifier	Eindeutige Kennung, welche für die Betrugsprävention benutzt wird (z.B. Hash der SessionId)
customer.customerGroup	"private" für B2C Kunden oder "business" für B2B Kunden
customer.forceCustomerGroup	true oder false: Widget übernimmt den customerGroup Wert vom Shop
inputNames	IDs der vom JavaScript Widget zu erzeugenden hidden Input-Felder innerhalb des definierten checkout.form jQuery Selectors. (im Beispiel: billpay[NAME_DES_FORMULARFELDES])
inputNames.order	Input-Felder für die Bestelldaten
inputNames.customer	Input-Felder für die Kundendaten
inputNames.paymentMethods	Input-Felder für die zahlartspezifischen Daten

<script type="application/javascript">
    billpayCheckout('options', {
        "checkout": {"form": "#payment_form"},
        "shop": {
            "apiKey": "710290a938e6b4770000005552",
            "live": false
        },
        "order": {
            "cartAmount": 161.94, // Wert des Warenkorbs ohne etwaige Gebühren
            "orderAmount": 166.94, // Gesamtwert inkl. aller Gebühren
            "currency": "EUR"
        },
        "customer": {
            "billing": {
                "salutation": "", // Anrede des Kunden. Wird dieses Feld gefüllt, erscheint die Abfrage nicht im Widget.
                "firstName": "Thomas", // Vorname des Kunden
                "lastName": "Testkunde", // Nachname des Kunden
                "street": "Zinnowitzer Str.", // Straße der Rechnungsadresse des Kunden
                "streetNo": "1", // Hausnummer der Rechnungsadresse des Kunden
                "zip": "10115", // Postleitzahl der Rechnungsadresse des Kunden
                "city": "Berlin", // Ort der Rechnungsadresse des Kunden
                "phoneNumber": "3254234234234", // Telefonnummer der Rechnungsadresse des Kunden. Wird dieses Feld gefüllt, erscheint die Abfrage nicht im Widget.
                "countryIso2": "DE", // 2-stelliger Ländercode der Rechnungsadresse des Kunden
                "countryIso3": "deu", // 3-stelliger Ländercode der Rechnungsadresse des Kunden
                "dayOfBirth": "1970-01-15" // Geburtsdatum des Kunden im Format JJJ-MM-TT. Wird dieses Feld gefüllt, erscheint die Abfrage nicht im Widget
            },
            "language": "de", // 2-stelliger Code der gewünschten Sprache des Kunden
            "identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // eindeutiger Hash für die Nutzersession
            "customerGroup": "private", //private oder business Kunde
            "forceCustomerGroup": true, // true: Widget übernimmt den vom Shop übergebenen customerGroup Wert oder false
        },
        "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>

Schritt 3: Ausführen

Abschließend wird die billpayCheckout Funktion mit dem Argument "run" aufgerufen. Optional kann als zweites Argument ein JSON Objekt übermittelt werden, welches einen Container definiert, in dem die BillPay-Zahlarten dargestellt werden.

Variable	Erklärung
container	jQuery Selector, welcher definiert, in welchem Element die Zahlmethode dargestellt werden soll (In diesem Beispiel ".bpy-checkout-container")

<script type="application/javascript">
    billpayCheckout('run', {"container": ".bpy-checkout-container"});
</script>

Schritt 4: Validierung des Widgets

Variable	Erklärung
'#payment_form'	jQuery selector, welcher definiert die ID der Checkout Formular, die die Zahlungsmethoden enthält und wird gesendet (In diesem Beispiel "#payment_form")

<script type="application/javascript">
    $("#payment_form").submit(function( event ) {
        if(!billpayCheckout('isValid')){
            event.preventDefault();
        }
    });
</script>

Volles Beispiel für das JavaScript Widget