Documentation

Borgun, all rights reserved. 2017 ©

Introduction

Borgun.Checkout is a payment solutions built upon BorgunPayment.js which enables developers to create and process payment forms with minimal effort.

Borgun Checkout

Referencing the library

WARNING: Never host Borgun.Checkout javascript code yourself. Always use the version distributed by Borgun servers.

NOTE: Borgun.Checkout does not depend on any third-party javascript libraries such as jQuery.

To reference Borgun.Checkout simply add the following line to your HTML file.

<script type="text/javascript" src="https://test.borgun.is/resources/js/borguncheckout/borguncheckout.v1.min.js"></script>

While Borgun.Checkout does not depend on jQuery it has extended functionality if paired with jQuery. See jQuery examples in the Examples section below.

Reference

WARNING: Never expose your private access token in html or public javascript, only use public tokens provided by Borgun.

Borgun.Checkout can be initialized in a variety of ways:

// Javascript shortcut.
Borgun.CheckoutInit(options, btn, onCallback);

// Available if using jQuery.
$("#myButton").BorgunCheckout(options, onCallback);

// Default.
var checkout = new Checkout(options, btn, onCallback, form);
checkout.Init();

Upon successful tokenization of card a Borgun.Checkout dialog will add/update a input field named "BorgunCheckoutToken" to a connected form.

Parameters

Name Description
options
Required		 Object of type options.
btn
Conditional		 The element that displays a Borgun.Checkout dialog when clicked.
onCallback If provided it will be called after successful tokenization of cardnumber with data as a parameter. If not provided the default havior is to submit the form connected to the Borgun.Checkout dialog.
form If provided it specifies the form element this Borgun.Checkout dialog will connect to, defaults to the parent form of btn.

Borgun.Checkout supports the following options when initialized:

Options

Name Description
publictoken
Required		 Public access token that the merchant received from Borgun. See RPG documentation.
amount
Required		 Amount that should be displayed to cardholder.
amountcurrencycode
Required		 Amount currency code to be displayed to cardholder.
companyname Company name to be displayed in form.
companyslogan Text that appears in the header.
companylogourl Url to company logo.
companylogoshown If true company logo will be shown.
language Language to display messages. Default EN (English). Please see Translations section for list of supported languages.
css Object that defines the payment form colors.
resources Object that defines custom resources.

css object structure:

Name Description
btncolor Hex representation of pay button color. Default: "#454545".
textcolor Form text color. Default: "#FFFFFF".
headercolor Color of header portion. Default: "#F2F2F2".
headertextcolor Color of text in header. Default: "#000000".
bodycolor Color of body portion. Default: "#F2F2F2".
bodytextcolor Color of text in body. Default: "#000000".
footercolor Color of footer portion. Default: "#F2F2F2".

Return value

If a callback function is specified this object will be passed to it as a parameter.

Name Description
Token
Required		 Single use token received from the server.
PAN
Required		 Masked version of the card number behind the token.
ExpYear
Required		 Expiration year on the card in the format YYYY.
ExpMonth
Required		 Expiration month on the card in the format MM.
Enabled
Required		 Flag that indicates that the token is enabled.
Used
Required		 Flag that indicates if the token has been used.
ValidUntil
Required		 Expiration date of token in ISO 8601 format YYYY-MM-ddTHH:mm:ddZ.

Translations

Custom translations can be specified in the resources object when initializing Borgun.Checkout. Official translations are also available for the following languages: EN (English), IS (Icelandic).

resources object structure

The structure of the resources object that can be specified when initializing Borgun.Checkout is as follows:

Name Description
btnprefix Prefix text to be displayed on pay button. Default: "Pay" or it's equivalent if language is other than EN.
ccnumber Text to display in card number input field. Default: "Card number" or it's equivalent if language is other than EN.
cvc Text to display in cvc input field. Default: "CVC" or it's equivalent if language is other than EN.
dateformat Text to display in cvc input field. Default: "MM/YY" or it's equivalent if language is other than EN.
errors Object that defines error messages.

resources.errors object structure:

Name Description
cardnumberInvalid Text to display when cardnumber in the cardnumber field is in invalid format.
cardnumberMissing Text to display when cardnumber field is empty.
cvcInvalid Text to display when cvc in the cvc field is in invalid format.
cvcMissing Text to display when cvc field is empty.
expDateInvalid Text to display when Expiration date is in invalid format or has expired.
expDateMissing Text to display when Expiration data is missing.
serverUnauthorized Text to display when Unauthorized (Status code 401) is received from Borgun.
serverError Text to display when request to Borgun was not successful (Status Code other than 201 and 401).
serverNoConnection Text to display when no response was received from Borgun or if unable to connect to Borgun.

Loading official translations

Official translations come as javascript files, these files must be loaded after the Borgun.Checkout javascript file has been loaded. Example: when loading the Icelandic translation:

<script type="text/javascript" src="https://test.borgun.is/resources/js/borguncheckout/borguncheckout.v1.min.js"></script>
<script type="text/javascript" src="https://test.borgun.is/resources/js/borguncheckout/borguncheckout.v1.lang.is.js"></script>

Then the language code must be set when initializing the Borgun.Checkout dialog. Example:

Borgun.CheckoutInit(
{
    publictoken: 'MY_ACCESS_TOKEN',
    language: 'IS'
},
document.getElementById("testbutton"));

Please see the list of official translations in the table below:

Language code Translation file url
EN N/A, comes bundled with Borgun.Checkout
IS https://test.borgun.is/resources/js/borguncheckout/borguncheckout.v1.lang.is.js

Specific texts can be overwritten even when using translations for example when overwriting the button prefix text:

Borgun.CheckoutInit(
{
    publictoken: 'MY_ACCESS_TOKEN',
    language: 'IS',
    resources: { btnprefix: 'Click to Pay' }
},
document.getElementById("testbutton"));
Try it out

Examples

Basic usage w/o jQuery

When used with classic Javascript the form and button must exist and with certain attributes:

<form>
    <button id="testbutton"
        value="Checkout"
        title="Checkout"
        data-amount="250"
        data-amountcurrencycode="ISK">Checkout</button>
</form>

Checkout can then be initialized

window.onload = function () {
    Borgun.CheckoutInit(
        {
            publictoken: 'MY_ACCESS_TOKEN',
        },
        document.getElementById("testbutton"));
};
Try it out

Usage with jQuery and script blocks

When using jQuery Borgun.Checkout can be loaded loaded using a script block inside a form.

<form action="/?formwithbutton=true">
    <script src="https://test.borgun.is/resources/js/borguncheckout/borguncheckout.v1.min.js" class="borgun-checkout"
    data-title="Pay USD 1.99"
    data-amount="1.99"
    data-amountcurrencycode="USD"
    data-css='{ "btncolor": "#454545", "textcolor": "#FFF" }'
    data-companyname="Borgun Testing" ,
    data-companyslogan="Pencils and more"
    data-companylogourl="https://test.borgun.is/resources/images/blogo/borgun_icon_logo.jpg">
    </script>
</form>
Try it out

Usage with jQuery selector

Checkout can be initialized by calling the BorgunCheckout extension method on an jQuery element variable. For Example:

<form>
    <button id="testbutton"
        value="Checkout"
        title="Checkout">Checkout</button>
</form>

$('#testbutton').BorgunCheckout(
{
    publictoken: 'MY_ACCESS_TOKEN',
    amount: 100,
    amountcurrencycode: 'ISK',
    companyname: "Borgun Checkout",
    companyslogan: ""
    companylogoshown: false
});
Try it out

Using a Callback function 

<form>
    <button id="testbutton"
        value="Checkout"
        title="Checkout"
        data-amount="250"
        data-amountcurrencycode="ISK">Checkout</button>
</form>

Checkout can then be initialized

window.onload = function () {
    var myCallback = function(data) {
      console.log('Callback');
      console.log(data);
    }

    Borgun.CheckoutInit(
        {
            publictoken: 'MY_ACCESS_TOKEN',
        },
        document.getElementById("testbutton"),
        myCallback
    );
};

Color customization example 1

Example of a light Borgun.Checkout dialog.

Borgun.CheckoutInit(
{
    publictoken: 'MY_ACCESS_TOKEN',
    amount: 1.99,
    amountcurrencycode: 'USD',
    companyname: 'Borgun Testing',
    companyslogan: 'Pencils and more',
    companylogourl: 'https://test.borgun.is/resources/images/blogo/borgun_icon_logo.jpg',
    css: {
        "btncolor": "#454545",
        "textcolor": "#FFFFFF",
        "headercolor": "#FFFFFF",
        "bodycolor": "#FFFFFF",
        "footercolor": "#1E6584"
    }
},
document.getElementById("testbutton"));
Try it out

Color customization example 2

Example of another customized Borgun.Checkout dialog.

Borgun.CheckoutInit(
{
    publictoken: 'MY_ACCESS_TOKEN',
    amount: 1.99,
    amountcurrencycode: 'USD',
    companyname: 'Borgun Testing',
    companyslogan: 'Pencils and more',
    css: {
        "btncolor": "#F9BA42",
        "textcolor": "#1D5977",
        "headercolor": "#9AD8E7",
        "headertextcolor": "#1E5A78",
        "bodycolor": "#9AD8E7",
        "footercolor": "#F9BA42",
        "textcolor": "#FFFFFF",
        "bodytextcolor": "#FFF"
    }
},
document.getElementById("testbutton"));
Try it out

Translation file

NOTE: You will have to load the desired translation file after loading Borgun.Checkout. See Transactions section for more details.

Example of a Borgun.Checkout dialog using the Icelandic translation.

Borgun.CheckoutInit(
{
    publictoken: 'MY_ACCESS_TOKEN',
    amount: 199,
    amountcurrencycode: 'ISK',
    language: 'IS',
    companyname: 'Borgun Prófanir',
    companyslogan: 'Pennar o.fl.',
    companylogourl: 'https://test.borgun.is/resources/images/blogo/borgun_icon_logo.jpg',
    css: {
        "btncolor": "#454545",
        "textcolor": "#FFFFFF",
        "headercolor": "#FFFFFF",
        "bodycolor": "#FFFFFF",
        "footercolor": "#FFFFFF"
    }
},
document.getElementById("testbutton"));
Try it out