Web Checkout

Interswitch provides a simple way to integrate a checkout feature into your existing products. This is the fastest and easiest way to get paid online with minimal code required for integration.

Some of the benefits of using the web checkout flow are:

  • Ease of integration
  • Secured checkout experience
  • Various payment options to enable
  • Improvement of checkout retention by using the inline checkout.

How to Integrate

❗️

Transaction Confirmation

After payment completion, you MUST make a server-side request to get the transaction status and amount that was paid before giving value.

There are two(2) ways that you can integrate Checkout into your product.

Option 1 - Inline Checkout

With Inline checkout payment, a widget will open in a popup on your current page, without the need for a redirect. This allows the customer to complete payment without navigating away from your site.

To use Inline Checkout, include the inline checkout script at the bottom of your page's body as shown below

<body>
    ... 
    <script src="https://webpay-ui.k8.isw.la/inline-checkout.js"></script>
<body>

📘

Go Live

To go live, change src value to 'https://newwebpay.interswitchng.com/inline-checkout.js'


You can now initiate checkout by calling window.webpayCheckout(request). The request is an object containing your payment parameters.

A callback function will also be passed in order to receive the response from the checkout. The list of the response parameters can be found here.

Here's an example of how to implement Inline Checkout

//declare callback function
function paymentCallback(response) {
    console.log(response);
}

//sample payment request
var samplePaymentRequest = {
    merchant_code: "MX007",          
    pay_item_id: "101007",
    txn_ref: "sample_txn_ref_123",
    amount: 10000, 
    currency: 566, // ISO 4217 numeric code of the currency used
    onComplete: paymentCallback,
    mode: 'TEST'
};

//call webpayCheckout to initiate the payment
window.webpayCheckout(samplePaymentRequest);

That's it! If you want to see more sample code, check out this repository.

Below is a full list of inline checkout parameters

Field Name

Data Type

Required

Description

pay_item_id

String

true

payable_code

pay_item_name

String

true

Name of the item being paid for

txn_ref

String

true

transaction reference

amount

String

true

Cost of the item you want your customer to pay

currency

String

true

ISO currency code

cust_name

String

false

merchant customer name

cust_email

String

false

merchant customer email

cust_id

String

false

merchant customer id

merchant_code

String

false

The Merchant's code

site_redirect_url

String

false

Merchant's website redirect url

tokenise_card

String("true" or "false")

false

Flag to indicate whether you want the customer's card to be tokenised, a tokenised value would be returned when you requery to confrim the transaction status

access_token

String("true" or "false")

false

Access token value gotten from passport

mode

String("TEST" or "LIVE")

true

The mode of the payment

onComplete

Object (function)

true

The callback function that returns the state of a transaction.

Option 2 - Web Redirect

If you decide to use Web Redirect, on checkout, the user will be navigated away from your site to the payment page. When the user completes the transaction, the payment page will make a form submit (POST call) to the redirect URL you provided on checkout.

An example form is shown below

<form method='post' action='https://webpay-ui.k8.isw.la/collections/w/pay'>
    <input name='merchant_code' value='MX007' />
    <input name='pay_item_id' value='101007' />
    <input name='site_redirect_url' value='https://example.com/payment-response' /> 
    <input name='txn_ref' value='sample_txn_ref_123' />
    <input name='amount' value='10000' />
    <input name='currency' value='566' />
    <input type='submit' value='Make Payment' /> 
</form>

📘

Go Live

To go live, change post URL to 'https://newwebpay.interswitchng.com/collections/w/pay'


As you can see in the form above, the site_redirect_url value you provide will be the URL that we will call when the user is done completing the transaction. The list of the response parameters can be found here.

You can view our sample project that shows how to integrate using Web Redirect here.


Payment Request Parameters

Field Name

Data Type

Required

Description

merchant_code

String

true

Merchant Code on Quickteller Business

pay_item_id

String

true

Pay item ID on Quickteller Business

txn_ref

String

true

Unique merchant reference for the transaction

amount

Integer

true

Cost of the item you want your customer to pay for in minor

currency

String

true

ISO currency code

cust_name

String

false

Name of the customer paying

cust_email

String

false

Email address of the customer paying

cust_id

String

false

Unique identifier of the customer on the merchant's system

pay_item_name

String

false

Name of the item being paid for

site_redirect_url

String

true for redirect integration

Merchant URL for the customer to be redirected to after completing payment


Confirming Transaction Status

You MUST make a server-side request to get the transaction status and amount that was paid before giving value. You make the request using your merchantCode, the relevant transaction reference and amount. Please confirm the amount returned by our server matches your original transaction amount before giving value.

Sample Request

curl https://qa.interswitchng.com/collections/api/v1/gettransaction.json?merchantcode={merchantcode}&transactionreference={reference}&amount={amount} \
# LIVE BASE URL: https://webpay.interswitchng.com
-H "Content-Type: application/json" \
-X GET

Sample Response

{
    "Amount": 66666600,
    "CardNumber": "",
    "MerchantReference": "933437251484",
    "PaymentReference": "UBA|API|MX187|25-07-2018|249510|719456",
    "RetrievalReferenceNumber": "000647661227",
    "SplitAccounts": [],
    "TransactionDate": "2018-07-25T06:57:24",
    "ResponseCode": "00",
    "ResponseDescription": "Approved by Financial Institution",
    "AccountNumber": "9999999999"
}

📘

Webhooks

Instead of calling our API to confirm the status of a transaction, you can enable webhooks, and configure a URL where we make a POST request to every time a transaction status changes. You can view the guide here

📘

Test Cards

Click here to get test cards to test your transactions.


Did this page help you?