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>