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