Gateway

SimplePay's Gateway is an embeddable payment form for desktop and mobile devices.

How it works

SimplePay's Gateway has a custom integration that allow you to use your own custom button with our JavaScript API.
With this, any HTML element or even an event from Javascript can start a payment process with SimplePay's Gateway.

Give it a try on our demo bellow:


The CHECKOUT payment type allows for a direct payment without the need of client confirmation on delivery.

Note: SimplePay's Gateway only creates tokens - it does not complete the payment process.
You must use those tokens to verify the payment on your server. Please see the API for further details.

Implementation

The implementation of SimplePay's Gateway is a simple process.

First add a line of client-side code. Please allow it to be the first script on your page.

<script src="https://checkout.simplepay.ng/simplepay.js"></script>
<!-- add your other scripts after this -->


Warning: Please make sure you are using our url in the script tag. A downloaded version of the Gateway may result in various types of errors.

Next, configure SimplePay's Gateway and create the callback function which will receive the response token.
When your page has finished loading, create a handler object (or a name that fits you the most), using SimplePay.configure() method.

Example using jQuery:

function processPayment (token) {
    // implement your code here - we call this after a token is generated
    // example:
    var form = $('#checkout_form');
    form.append(
        $('<input />', { name: 'token', type: 'hidden', value: token })
    );
    form.submit();
}

// Configure SimplePay's Gateway
var handler = SimplePay.configure({
   token: processPayment, // callback function to be called after token is received
   key: 'test_pu_demo', // place your api key. Demo: test_pu_*. Live: pu_*
   image: 'http://' // optional: an url to an image of your choice
});

After this, you can customize your payment button as you want, adding an event to it to call handler.open().
This event will then trigger the payment form.

Example using jQuery:

$('#btn-checkout').on('click', function (e) { // add the event to your "pay" button
    e.preventDefault();

    handler.open(SimplePay.CHECKOUT, // type of payment
    {
       email: 'customer@store.com', // optional: user's email
       phone: '+234*', // optional: user's phone number
       description: 'My Test Store Checkout 123-456', // a description of your choosing
       address: '31 Kade St, Abuja, Nigeria', // user's address
       postal_code: '110001', // user's postal code
       city: 'Abuja', // user's city
       country: 'NG', // user's country
       amount: '110000', // value of the purchase, ₦ 1100
       currency: 'NGN' // currency of the transaction
    });
});

Configuration

Argument Requirement Description
payment type Required payment type should be chosen from available choices: SimplePay.CHECKOUT, SimplePay.REMEMBER
token Required callback function to be called once the token is created and received by the merchant's website
key Required your api key -- sign up for one at SimplePay
image Optional full url to a image of your choice
email Optional customer's email address
phone Optional customer's phone number -- country code is needed (e.g. +234)
description Optional description of the payment
address Required customer's address
postal_code Optional customer's postal code
city Required customer's city
country Required customer's country code -- should be 2-letter ISO 3166-1 alpha-2
amount Required payment amount -- must be in lower denomination (e.g. ₦ 1100 must be configured as 110000)
currency Required payment currency -- should be 3-letter ISO_4217

Browser Support

SimplePay's Gateway strives to support all major and modern browser as well as old versions of some browsers.
Internet Explorer is only supported version 8 and newer.

Pop-Up Blockers

If SimplePay's Gateway is being blocked by a pop-up blocker, please verify the event in which the open() method is being called.
Browsers block pop-ups that doesn't come from a trusted event so, if you have the method inside a, let's say, ajax call, since it is not a trusted event anymore, SimplePay's Checkout will be flagged as a pop-up to be blocked.
Check the examples bellow for a clear understanding of this:


// Good case, pop-up will not be blocked
$('#btn-checkout').on('click', function (e) {
    e.preventDefault();
    handler.open(SimplePay.CHECKOUT,{...});
});

// Bad case, pop-up will be blocked by the browser
$("#btn-checkout").on("click", function(e) {
    e.preventDefault();
    $.ajax({
        url: "path/to/service/",
    }).done(function(e) {
        handler.open(SimplePay.CHECKOUT,{...});
    });
});

SSL certificates

SimplePay's Gateway is a secure feature and implements a secure HTTPS connection.
In order to be protected against certain forms of attacks, you should server the page in which the payment form resides with HTTPS.
Note: Some versions of Internet Explorer may require you to serve the page with HTTPS in order to correctly display the payment form.

Testing

To simulate a successful transaction with credit card payment, you can use this cards:
Note:

Card number Type 3DSecure
4024007125686666 Visa No
4111111111111111 Visa No
4556071004574605 Visa Yes
4012888888881881 Visa Yes
5336038525505388 MasterCard No
5500000000000004 MasterCard No
5331793375596359 MasterCard Yes
5169147129584558 MasterCard Yes


For testing a credit card that fails the credit card validation (luhn check), use this cards:

Card number Type
4343434343434343 Visa
5555333355554444 MasterCard

Screenshots

When configuring SimplePay's Gateway, there are some important cases to be aware of.

Optional user data

The user fields "email" and "phone" are marked as optional. In their absent, SimplePay's Gateway will prompt the user for their values.



Errors

Configuration errors

If for some reason there are some issues on configuring SimplePay Gateway, there will be a warning popup on your client's site. Please review all your configurations if this happens.


Missing data errors

If for some reason the required parameters are not passed to SimplePay's Gateway, a warning will be placed on the client's site.