Introduction

We acknowledged the fact that not all merchants or businesses are PCIDSS complaint so we created a hosted fields SDK for businesses who are non PCIDSS complaint to integrate with our payment gateway with control over how your checkout page feels.

With hosted fields, you can host our payment gateway on you domain and presents the fields to your users in an iframe to handle input of the following payments fields: Expiry Date, CVV, PIN and OTP on your checkout page. This gives you the control over the look and feel of your checkout page while ensuring that you are compliant with PCIDSS requirements.

Setup

Set up SDK as shown below,

Javascript

<script src="./sdk.js"></script>

<script> 
    isw.hostedFields.create(configuration, function createCallback(error, hostedFieldsinstance){
        if(error != null) {
            //handle create error
            return;
        }

        //create an hosted fields instance
    })
</script>

Then create a configuration object and a callback function, pass the two as arguments to the isw.hostedFields.create() method. The configuration object has three properties, which are fields, cardinal and paymentParameters.

Sample configuration object

Find below a sample configuration object written in JavaScript.

Javascript

var configuration = {
    fields: {
        cardNumber: {
            selector: '', //this indicates the id of the div
            placeholder: '',
            styles: {}
        },
        //other fields of the hosted fields follows the same pattern
        //with keys expirationDate, cvv, pin, otp
    },
    cardinal: {
        containerSelector: '', //indicates the identifier forthe cardinal div
        activeClass: '', //a css class that display the div
    },
    paymentParameters: {
        amount: //amount in minor(kobo),
        currencyCode: //merchant currency code,
        dateOfPayment: //date in YYYY-MM-DDTHH:mm:ss format,
        payableCode: //merchant payable code as provided,
        merchantCustomerName: //merchant name as provided,
        merchantCode: //provided merchant code as provided,
        transactionReference: //transaction reference as provided
    }
}

The Callback Function

The callback function takes two parameters which are error and hostedFieldsInstance. Error catch error resulting from hosted fields creation while the instance creates a new instance of the hosted fields. The instance of the hosted fields has the following methods on it:

  • makepayment(),
  • validatePayment(),
  • binConfiguration(),
  • getFieldsState(),
  • on()

The on() method handles events like focus, blur, validation, and cardinal-response. To check for the validation of each field you can call instance.getFieldsState().

Sample Code

var instance;
var showFormErrors = false;
var focusedField;

function createCallback(error, hostedFieldsInstance){
    //handleError

    instance = hostedFieldsInstance

    instance.on('blur', function(event){
        //handle event
        if(!showFormErrors) {
            return;
        }

        var validationState = instance.getFieldsState();
        checkFieldsValidation([['cardNumber', 'expirationDate', 'cvv', 'pin', 'otp']], validationstate);
    });

    instance.on('focus', function(event){
        //handle event
        if(!showFormErrors) {
            return;
        }

        var validationState = instance.getFieldsState();
        checkFieldsValidation([['cardNumber', 'expirationDate', 'cvv', 'pin', 'otp']], validationstate);
    })

    instance.on('validation', function(event){
        //handle event
        if(!showFormErrors) {
            return;
        }

        var validationState = instance.getFieldsState();
        checkFieldsValidation([['cardNumber', 'expirationDate', 'cvv', 'pin', 'otp']], validationstate);
    })

    instance.on('cardinal-response', function(error, response){
        //handle page switching
        setActivePage('card-details');

        if (err != null && err.validationError === true) {
            //handle validation error
        }

        if (err != null) {
            //handle api error
        }

        if (response.responseCode === '00') {
            //handle succesfull response
        }

        //handle response that is not a success
    })


    //add eventListener
}

Events

The instance.on method gives you the ability to hook into focus, blur, validation and this allow you to subscribe to those events.

Focus and Blur Events

For the focus and blur events, the event returns an object which contains fieldType and selector as seen in the table below.

Key Type Description
fieldType string Displays the type of input field which can be cardNumber, expiratuonDate, cvv, pin or otp
selector string Displays the id of the div container.

Validate Event

For the validate event, the event returns an object of objects that contains cardNumber, cvv, expirationDate, otp and pin as seen in the table below.

Key Type Description
cardNumber object
cardType string
isEmpty boolean
valid boolean
cvv object
isEmpty boolean
valid boolean
expirationDate object
expired boolean
isEmpty boolean
valid boolean
otp object
isEmpty boolean
valid boolean
pin object
isEmpty boolean
valid boolean

Integration

To start using Hosted Fields, you need to create a basic HTML checkout form. You will need to define containers that will hold the iframe input fields for the following inour fields (Card Number, Expiry Date, CVV, PIN, OTP). Here is a sample form that uses Hosted Fields.

Method 1


Hosted Fields Demo

See the Pen Hosted Fields: Demo by Abdulkareem Abdulbasit (@basitomania) on CodePen.


Method 2


Custom WebPay Hosted Field

See the Pen Custom WebPay Hosted Field by Edidiong Asikpo (@edyasikpo) on CodePen.


Response Codes

Find below different response codes depening on the success or failure of the integration

On Bin Configuration call

Response Code Description
Z81 No bin was found for this pan

On Pay call

Successful Response
Response Code Description
00 Approved by Financial Institution
T0 Continue Transaction
Error Response
Response Code Description
XS1 Your payment has exceeded the time required to pay.
Z1 Transaction Error.
Z5 PAYMENT_ALREADY_PROCESSED
T1 CANNOT_GENERATE_OTP
X03 Amount greater than daily transaction limit
54 Expired Card
55 Incorrect Pin
91 Issuer or Switch Inoperative
56 No card Record

On Authenticate Call

Successful Response
Response Code Description
00 Approved by Financial Institution
Error Response
Response Code Description
T1 INVALID_TOKEN_SUPPLIED
91 Issuer or Switch Inoperative