Introduction: The BillPay JavaScript Widget

The core of all shop integrations is the BillPay JavaScript widget which will display all payment methods in a conversion optimized and standardized fashion. This way, the BillPay brand can be recognized throughout various shops and customers will trust the payment method.

For integration projects where the shop system is developed in-house or BillPay does not offer a plug-in, it is a requirement to implement the BillPay Widget for the display of the BillPay payment methods.

Configuration of the JavaScript widget

Step 1: Loading the JavaScript

In order to use the BillPay JavaScript widget, the following snippet needs to be included in the shop template:

<!-- Initialization & Configuration -->
<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>

The function billpayCheckout is now available to use.

Step 2:Configuration

In order to configure the JavaScript widget the billpayCheckout function is called and given the first parameter "options" and a JSON object containing customer and shop information as the second parameter.

Variable Explanation
checkout.form jQuery selector for the checkout form HTML element
shop.apiKey Public API Key; generated and delivered by BillPay for your portal.
shop.live Defines if the widget is running in "test" or "live" mode.
order.cartAmount Value of the total shopping cart (Just article value excl. shipping cost or any other additional fees.)
order.orderAmount Total order value (incl. shipping cost or any other additional fees
order.currency ISO Code for the currency
customer.billing.salutation Salutation
customer.billing.firstName First name of the customer
customer.billing.lastName Last name of the customer
customer.billing.street Street of the customer address
customer.billing.zip ZIP code of the customer address
customer.billing.city City of the customer address
customer.billing.phoneNumber Phone number
customer.billing.countryIso2 ISO Code of the customer address country
customer.billing.countryIso3 ISO Code of the customer address country
customer.billing.dayOfBirth Customer's date of birth
customer.language Language of the customer
customer.identifier Unique token used for fraud prevention (e.g. hash of session ID)
customer.customerGroup "private" for B2C Customers oder "business" für B2B Customers
customer.forceCustomerGroup true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false: when the value is not provided in the customerGroup
inputNames IDs of the hidden input fields that will be generated inside the checkout.form jQuery selector by the JavaScript widget. (e.g.: billpay[NAME_OF_THE_FORM_FIELD])
inputNames.order Input fields for the order data
inputNames.customer Input fields for the customer data
inputNames.paymentMethods Input fields for payment specific information
request JSON object, which contains request information (e.g. json_encode($_REQUEST) )
<script type="application/javascript">
    billpayCheckout('options', {
        "checkout": {"form": "#payment_form"},
        "shop": {
            "apiKey": "710290a938e6b4770000005552",
            "live": false
        },
        "order": {
            "cartAmount": 161.94, // Total cart value without shipping or additional fees
            "orderAmount": 166.94, // Total cart value including shipping and additional fees
            "currency": "EUR" // the currency to be used for checkout
        },
        "customer": {
            "billing": {
                "salutation": "", // The customer's salutation. If this field is empty, the salutation input will be shown in the checkout widget.
                "firstName": "Thomas", // The customer's first name
                "lastName": "Testkunde", // The customer's last name
                "street": "Zinnowitzer Str.", // The customer's street (billing address)
                "streetNo": "1", // The customer's house number (billing address)
                "zip": "10115", // The customer's zip code (billing address)
                "city": "Berlin", // The customer's city (billing address)
                "phoneNumber": "3254234234234", // TThe customer's phone number. If this field is empty, the phone number input will be shown in the checkout 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-digit lagugage code for the checkout session
            "identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // unique session id hash
            "customerGroup": "private", //private oder business customer
            "forceCustomerGroup": true, // true: Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false if you do not have this value
        },
        "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>

Step 3: Executiion

Finally, the function billpayCheckout is called with the argument "run". A second argument can be passed that contains a JSON object which defines the container for the BillPay payment methods that will be displayed.

Variable Description
container jQuery selector, which defines the container for the BillPay payment methods to be displayed. (in this example: ".bpy-checkout-container")
<script type="application/javascript">
    billpayCheckout('run', {"container": ".bpy-checkout-container"});
</script>

Step 4: Validating the Widget on submit

Variable Description
'#payment_form' jQuery selector, which defines the id of the checkout form that contains the payment methods and is being submitted (in this example: "#payment_form")
<script type="application/javascript">
    $("#payment_form").submit(function( event ) {
        if(!billpayCheckout('isValid')){
            event.preventDefault();
        }
    });
</script>

Full Example of the Widget implementation

<!DOCTYPE html>
<html>
<head></head>

<body>

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

    billpayCheckout('options', {
        "checkout": {"form": "#payment_form"},
        "shop": {
            "apiKey": "710290a938e6b4770000005552",
            "live": false
        },
        "order": {
            "cartAmount": 161.94, // Total cart value without shipping or additional fees
            "orderAmount": 166.94, // Total cart value including shipping and additional fees
            "currency": "EUR" // the currency to be used for checkout
        },
        "customer": {
            "billing": {
                "salutation": "", // The customer's salutation. If this field is empty, the salutation input will be shown in the checkout widget.
                "firstName": "Dieter", // The customer's first name
                "lastName": "Testkunde", // The customer's last name
                "street": "Zinnowitzer Str.", // The customer's street (billing address)
                "streetNo": "1", // The customer's house number (billing address)
                "zip": "10115", // The customer's zip code (billing address)
                "city": "Berlin", // The customer's city (billing address)
                "phoneNumber": "3254234234234", // TThe customer's phone number. If this field is empty, the phone number input will be shown in the checkout 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-digit lagugage code for the checkout session
            "identifier": "cee58750b29d5c9c6ce04a480d3ceb6d", // unique session id hash
            "customerGroup": "private", //private oder business customer
            "forceCustomerGroup": true, //Widget takes the value for the customer group that your shop provides and the widget does not display the dropdown or false if you do not have this value
        },
        "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>

<!-- Container -->
<form id="payment_form">
        <h1>Rechnungskauf</h1>
        <div class="bpy bpy-checkout-container" bpy-pm="invoice"></div>
        <h1>Lastschrift</h1>
        <div class="bpy bpy-checkout-container" bpy-pm="directDebit"></div>
        <h1>PayLater</h1>
        <div class="bpy bpy-checkout-container" bpy-pm="paylater"></div>

</form>

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

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

</body>
</html>