Documentation

Borgun, all rights reserved. 2017 ©

Introduction

The BorgunPayment.js is a javascript library built upon Borgun's Restful Payment Gateway and enables merchants to have full control over their payment form without any sensitive card information flowing through their servers. All creditcard information is handled by the cardholders browser and Borgun. For more information on access tokens see RPG documentation. https://docs.borgun.is/paymentgateways/bapi/rpg/ Example usage steps of the library:

  1. Cardholder enters Card information
  2. Cardholder's browser sends card information to Borgun RPG via SSL
  3. Borgun returns a single-use token to the cardholder's browser
  4. The browser posts the token to the server of the merchant.
  5. Merchant uses token to charge the card.
  6. Merchant displays receipt to the cardholder.

Referencing the library

WARNING: Never host the borgunpayment.js library yourself. Always use the version distributed by Borgun servers.

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

To reference the borgunpayment.js library simply add the following line to your HTML file.

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

Set public access token

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

An access token pair issued by Borgun is required when using the library, see RPG documentation. The library should only be used with the public access token which does not grant access to any sensitive API functionality. The public access token to be used by the library can be set using two methods. Either by a call to BAPIjs.setPublicToken

BAPIjs.setPublicToken('myPublicToken');

or as a global variable before the library is loaded.

<script type="text/javascript">var BORGUN_API_TOKEN = 'myPublicToken';</script>

Library methods

getToken

The getToken method accepts card information as parameters and sends them to Borgun for tokenization.

Parameters to getToken:

Name Description
pan
Required
Cardnumber to tokenize. Value should only contain numbers, no spaces or dashes (-).
expYY
Required
Expiration year of the card in the format YY or YYYY (Example: '2016' or '16').
expMM
Required
Expiration month of the card in the format MM (Example: February becomes '02' or '2').
callback
Required
Function to call after communication with Borgun has finished.
tokenLifetime
Optional
Expiry time of token in seconds, default is 60 seconds.
verifyCard If verifyCard object is present an attempt to verify the card by performing authorization will be performed.

Parameters to callback function:

Name Description
status
Required
Status of response. status code of response can be accessed via status.statusCode.
data
Required
Data returned from server as JSON object. See examples below for object structure.

verifyCard object structure

NOTE: Merchants verifying cards by charging an amount to the card may be subject to fees per attempt. Please contact Borgun for more information.

Name Description
cvc CVC number on card, if provided it will be used when verifying the card.
checkamount Authorization amount to charge on card, authorization will be canceled. Default is 0.
currency Amount Currency in ISO 4217 numerical representation Example: '840' for USD, only required if amount is greater than 0.

data returned from server

If token request is successful (Status code: 201) a token object will be returned from the server:

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.

If card verification was performed the result will also contain a VerifyCardResult object

Name Description
ActionCode
Required
Will contain '000' if card verification was successful, please see ActionCode reference for more information on action codes.
TransactionId
Required
Contains the identifier of the transaction that was created when verifying the card.

getToken Examples

Basic usage:

BAPIjs.getToken({
  pan: '4242424242424242',
  expYear: '26',
  expMonth: '01'
}, function(status, data) { });

Data returned from server:

{
  'Token': 'ts_12345',
  'PAN': '424242******4242',
  'ExpYear': '2026',
  'ExpMonth': '01',
  'Enabled': true,
  'Used': false,
  'ValidUntil': '2016-03-12T11:41:56Z',
}

Basic usage with card verification attempt:

BAPIjs.getToken({
  pan: '4242424242424242',
  expYear: '26',
  expMonth: '01',
  tokenLifetime: '10',
  verifyCard: {
    'cvc': '000'
  }
}, function(status, data) { });

Data returned from server:

{
  "Token": "ts_12345",
  "PAN": "424242******4242",
  "ExpMonth": "01",
  "ExpYear": "2026",
  "Enabled": true,
  "Used": false,
  "ValidUntil": "2016-05-12T17:06:31Z",
  "VerifyCardResult": {
    "ActionCode": "000",
    "TransactionId": "tr_12345"
  }
}

isValidCardNumber

The isValidCardNumber performs basic checks to determine whether the input is a legal cardnumber and returns a boolean value.

Parameters:

Name Description
pan
Required
Cardnumber to validate. Value should only contain number, no spaces or dashes (-).

Example:

BAPIjs.isValidCardNumber('4242424242424242');

isValidExpDate

The isValidExpDate method performs basic checks to determine whether the input is a legal expiration date and returns a boolean value.

Name Description
expMM
Required
Expiration month of the card in the format MM (Example: February becomes '02' or '2').
expYY
Required
Expiration year of the card in the format YY or YYYY (Example: '2016' or '16').

Example:

BAPIjs.isValidExpDate('02', '26');
BAPIjs.isValidExpDate('02', '2026');

isValidCVC

the isValidCVC method performs basic checks to determine whether the input is a legal CVC value.

Name Description
cvc
Required
cvc value.

Example:

BAPIjs.isValidCVC('123');

Examples

Following is an example of how the library can be used to create single use tokens. The example depends on Bootstrap and JQuery while borgunpayment.js does not.

Try it out

The form (index.html)

<!DOCTYPE html>
<html>
<head>
    <meta charset=utf-8 />
    <title>BorgunPayment.js example</title>
    <script type="text/javascript" src="//code.jquery.com/jquery-1.12.0.min.js"></script>
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" integrity="sha384-1q8mTJOASx8j1Au+a5WDVnPi2lkFfwwEAa8hDDdjZlpLegxhjVME1fgjWPGmkzs7" crossorigin="anonymous">
    <script type="text/javascript" src="https://test.borgun.is/resources/js/borgunpayment-js/borgunpayment.v1.min.js"></script>
</head>
<body>
     <div class="container">
    <div class='row'>
        <div class='col-md-4'></div>
        <div class='col-md-4'>
          <form action="" id="payment-form" method="post">
            <div class='form-row'>
              <div class='col-xs-12 form-group required'>
                <label class='control-label'>Cardholder name</label>
                <input class='form-control' id="card-name" size='4' type='text'>
              </div>
            </div>
            <div class='form-row'>
              <div class='col-xs-12 form-group required'>
                <label class='control-label'>Card Number</label>
                <input autocomplete='off' class='form-control card-pan' size='19' type='text'>
              </div>
            </div>
            <div class='form-row'>
              <div class='col-xs-4 form-group required'>
                <label class='control-label'>CVC</label>
                <input autocomplete='off' class='form-control card-cvc' placeholder='XXX' size='4' type='text'>
              </div>
              <div class='col-xs-4 form-group required'>
                <label class='control-label'>Expiration</label>
                <input class='form-control card-exp-month' placeholder='MM' size='2' type='text'>
              </div>
              <div class='col-xs-4 form-group required'>
                <label class='control-label'> </label>
                <input class='form-control card-exp-year' placeholder='YYYY' size='2' type='text'>
              </div>
            </div>
            <div class='form-row'>
              <div class='col-md-12 form-group'>
                <button class='form-control btn btn-primary submit-button' type='submit'>Pay »</button>
              </div>
            </div>
            <div class='form-row'>
              <div class='col-md-12 error form-group' style="display: none">
                <div class='alert-danger alert'>
                  Please correct the errors and try again.
                  <ul class="error-message" style="font-weight: bold"></ul>
                </div>

              </div>
            </div>
          </form>
        </div>
        <div class='col-md-4'></div>
    </div>
</div>
<script type="text/javascript" src="payment.js"></script>
</body>
</html>

The javascript (payment.js)

$(function(){
    // Set public access token. Replace this with our own.
    BAPIjs.setPublicToken('REPLACE_ME');

    $("#payment-form").submit(function(event) {
      var pan = $("#payment-form .card-pan").val().trim();
              var expMonth = $("#payment-form .card-exp-month").val().trim();
              var expYear = $("#payment-form .card-exp-year").val().trim();
              var cvc = $("#payment-form .card-cvc").val().trim();
        var hasErrors = false;
        $("div.error").hide();
        $("ul.error-message").html('');

        // Preemptive input validation.
        if (BAPIjs.isValidCardNumber(pan) === false) {
            $("ul.error-message").append('<li>Invalid card number</li>');
            hasErrors = true;
        }
        if (BAPIjs.isValidExpDate(expMonth, expYear) === false) {
            $("ul.error-message").append('<li>Invalid expiration date</li>');
            hasErrors = true;
        }
        if (BAPIjs.isValidCVC(cvc) === false) {
            $("ul.error-message").append('<li>Invalid cvc number</li>');
            hasErrors = true;
        }

        if (hasErrors) {
            $("div.error").show();
        } else {
            // The function that parses the response from Borgun.
            var borgunResponseHandler = function(status, data) {
                if (status.statusCode === 201) {
                    // OK
                    $("#payment-form").append($('<input type="hidden" name="singleToken" />').val(data.Token));
                    $("#payment-form").get(0).submit();
                } else if (status.statusCode === 401) {
                    // Unauthorized
                    $("ul.error-message").append('<li>Unauthorized received from BorgunPaymentAPI</li>');
                    $("div.error").show();
                } else if (status.statusCode) {
                    $("ul.error-message").append('<li>Error received from server ' + status.statusCode + ' - ' + status.message + '.</li>');
                    $("div.error").show();
                } else {
                    $("ul.error-message").append('<li>Unable to connect to server ' + status.message + '.</li>');
                    $("div.error").show();
                }
                // Enable Pay button again.
                $('.submit-button').prop("disabled", false);
            };

            // Disable Pay button.
            $('.submit-button').prop("disabled", true);
            // Request single use token from Borgun.
            BAPIjs.getToken({
                'pan': pan,
                'expMonth': expMonth,
                'expYear': expYear,
                'cvc': cvc
            }, borgunResponseHandler);
        }

        event.preventDefault();
        return false;
    });
});