Introduction

The Pay With Quickteller widget is a simple Javascript that can be utilized on any website seeking to offer visitors the facility to pay for goods and services by using their bank issued cards or other payment tokens. It is designed for merchants who use shopping carts, have little experience in server side scripting, or who use shared web servers that do not offer secure database services.

Features

  1. Easy to set up: Interswitch Pay With Quickteller widget is easily integrated with most of the major shopping carts.
  2. Simple Integration: With just a few lines of code, the merchant's website can be ready to accept payment.
  3. Complete security: Customers enter their bank card details on the Interswitch WebPAY payment page and it takes care of the transaction security from there. Therefore the website owner does not need to worry about cardholder security as they do not process the card data. The Interswitch platform is certified under the PCI DSS (Payment Card Industry Data Security St\andard). The customer is redirected to Interswitch WebPAY to enter their card details, therefore no sensitive customer information needs to be taken or stored by the merchant's website, thereby removing the need for them to maintain highly secure encrypted databases, or obtain digital certificates

How it works

After integration, a Pay with Quickteller button is displayed on your website for your customers to click on during checkout. When the button is clicked, the WebPAY card input page will be displayed for your customer to complete the initiated transaction. If the user is on a mobile device, the browser will redirect to a mobile friendly page instead.

Sample Code

We created a sample code implemented in PHP. Feel free to alter the look and feel based on your taste and requirement(s). Don't forget to alter the links and paths appropriately before uploading to a web server.


https://pwq.sandbox.interswitchng.com

Authentication

Authenticate your API calls by including your access token in the Authorization header of every request you make. Interswitch utilizes OAuth 2 to facilitate authorization and grants access to an application either on behalf of a user or on behalf of the application itself.

Application Authorization

To get an access token, create a project on the Interswitch Developer Console and obtain the Client ID and Secret Key of the project and encode the them using this format client_id:secret_key using base64encode. Copy the encoded value of your Client ID and Secret Key and make a call to the endpoint below with the Authorization header that contains the word Basic followed by a space and the base64-encoded value. Ensure that you use the Content-Type:application/x-www-form-urlencoded header and finally pass the grant_type=client_credentials in the body of the request.


Endpoint

POST

/passport/oauth/token

Sample Request

import requests
url = "https://sandbox.interswitchng.com/passport/oauth/token"
body = {"grant_type":"client_credentials"}
headers = {
    'authorization': "Basic SUtJQTFCNzU5M0M0NDAyQkM1RTAwQzQ2QUM4QjFDMUNDMEI4NUVFQkIwODg6c2VjcmV0",
    'content-type': "application/x-www-form-urlencoded"}
response = requests.request("POST", url, data=body, headers=headers)
print(response.text)
REQUEST PARAMETERS
Parameters Required Type Description
ClientId Yes String Application key. Navigate to `https://developer.interswitchgroup.com` for your application key
SecretKey Yes String Application secret. Navigate to `https://developer.interswitchgroup.com` for your application secret.
grant_type Yes String This must be set to client_credentials

Sample Response (Success)

{ 
  "access_token": "{Your access token}",
  "token_type": "bearer",
  "expires_in": 43199,
  "scope": "profile",
  "merchant_code": "MX10003",
  "requestor_id": "123588975884",
  "client_name": "kL79ov",
  "payable_id": "359854",
  "jti": "19800d56-3ac6-44c2-b318-8f2ece419840"
}

Sample Response (Failure)

{ 
  "code": "Unauthorized",
  "description": "Bad credentials",
  "errors": null
}
RESPONSE PARAMETERS
Parameters Description
access_token A new access token that is used to authenticate against resources that belong to the app itself.
token_type Always bearer
expires_in The lifetime of the access token, in seconds

Authorization headers should be in the following format: Authorization: Bearer Encoded(clientId:secreteKey).


Implementation

There are two implementation of Pay with Quickteller Widgets. We have the:

  • Basic Implementation
  • Advance implementation

Basic Implementation

For basic implementation, no data integration is required between the Pay With Quickteller REST Service platform and your system for purposes of validating the status of a Transaction as Quickeller displays a default receipt page upon completing your transaction.

Once you request to be activated for Pay with Quickteller, you would receive an email that would contain a snippet of Javascript like below. Simply copy and paste the snippet into the HTML of your website at the very spot where you want the Pay with Quickteller button to appear. Copy and paste the following code on your website.

Basic Implementation

<html class="transition-navbar-scroll top-navbar-xlarge bottom-footer"  lang="en">
<head>
<title>PWQ</title>
</head>
<body>
<p><em><small><a  id="95101"  class="quickteller-checkout-anchor"  style="text-align: left;"></a></small></em></p>
<script>// <![CDATA[
var  QTCheckout  =  QTCheckout  ||  {};
var  testMode  =  true;
var  baseUrl  =  "";
QTCheckout.paymentItems  =  QTCheckout.paymentItems  ||  [];
QTCheckout.paymentItems.push({
paymentCode:  '95101',
extraData:  {
amount:"default",
buttonSize:  'medium',
customerId:"default",
mobileNumber:"default",
emailAddress:"default",
redirectUrl:  "default",
requestReference:  "9999"
}});
if  (testMode  ==  true)  baseUrl  =  "https://pwq.sandbox.interswitchng.com/scripts/quickteller-checkout-min.js?v=";
else  baseUrl  =  "https://paywith.quickteller.com/scripts/quickteller-checkout-min.js?v=";
if  (!QTCheckout.qtScript)  {
var  qtScript  =  document.createElement('script');
qtScript.type  =  'text/javascript';
qtScript.async  =  true;
qtScript.src  =  baseUrl  +  new  Date().getDay();
var  s  =  document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(qtScript,  s);
QTCheckout.qtScript  =  qtScript;}
else  if  (QTCheckout.buildPaymentItemsUI)  {
QTCheckout.buildPaymentItemsUI();}
// ]]></script>
</body>
</html>

This would generate the Pay with Quickteller button and when clicked, will render a pop-up as seen in the image below:

Pay With Quickteller

The Pay with Quickteller pop-up page.

Advance Implementation

With advance implementation, the behavior of the popup can be customized to do the following:

  • Land straight on the card input page. Note: This only happens when all the fields (amount, buttonSize, customerId, mobileNumber, emailAddress, redirectUrl) are filled.
  • Redirect to a page on your website after payment.
  • Close the pop-up window after the transaction.
  • Validate that the amount paid was the exact amount you were expecting (to prevent fraudulent transactions) as well as the status of transactions.
REQUIRED FIELDS
Field Description
paymentCode This is the merchant's payment code on the Quickteller platform.
amount The expected value you want to be paid in a lower denomination e.g N10 = 1000
buttonSize Pay with Quickteller supports 4 values. These values are small, medium, large, default.
CustomerId  This is a unique reference for this payment or customer.
mobileNumber The phone number for the paying customer. This number will receive an SMS receipt.
emailAddress An email address for the paying cutomer. This email address will receive an email receipt.
redirectUrl This is the page on my web application that I want the payment gateway to redirect to after the payment is complete.
requestReference This is the Merchant's own Transaction ID generated uniquely for each transaction. Your requestReference must be prefixed with a 4 digit prefix provided by Interswitch. This is ultimately used in querying for a Transaction to confirm status of payment.The requestReference cannot be reused and must be unique for every transaction.

The payment gateway will redirect the user to the website summary page after payment. As part of the redirect, the payment gateway will submit some POST values to the page you've specified. Find below values you can expect to recieve:

REQUIRED FIELDS
Field Description
resp_code A value that shows if the transaction was successful or not. 00 denotes successful while every other value means the transaction wasnt successful.
resp_desc A textual description of the response code.
tx_ref A unique reference for the transaction assigned by the payment gateway.
recharge_pin  If the transaction is such that it requires the payer to get a voucher (like airtime recharge vouchers or electricity) the voucher number will be passed in this value.
signature A unique signature for this trxn using a mix of amount, resp_code, tx_ref all encrypted using the secret key provided to you by Interswitch.
In essence, you have to implement a page that will receive the values in the table above, call a REST service exposed by Quickteller to retrieve other details of the transaction and lastly compare the amount paid with the amount you set above for security check. If everything checks out, mark the payment as done and give value to customer. ### Service Specification For the purposes of validating the status of transactions, there has to be a data exchange between the Pay with Quickteller REST Service platform and your system. Using the call back mechanism is a way to validate the payment when the payment gateway redirects to your app. This call back is achieved by calling the REST service with specific parameters. All parameters are passed as information in custom Headers in each request to the service, expect the Transaction Reference. You would need the following test and production details to be provided by Interswitch to be able to generate the parameters required to call the service - **ClientId:** Get this on the [Interswitch Developer Console](https://developer.interswitchgroup.com/). - **SecretKey:** Get this on the [Interswitch Developer Console](https://developer.interswitchgroup.com/). - **URL REST service:** This will be sent to you by Interswitch. ### Getting Transaction Data

Endpoint

GET

/quicktellercheckout/api/v2/transaction/099909090?isRequestRef=true
REQUEST PARAMETER
ParameterName (case sensitive) ParameterType Format Description
requestReference Part of the query endpoint Alphanumeric Assigned prefix + Merchant's TransactionID Note: requestReference is the merchant's transaction ID concatenated with the assigned prefix (e.g. if your assigned prefix is 1234 and merchant ID is 567890, the requestReference will be 1234567890).
clientid Header Alphanumeric The Client ID of your project retrieved from the Developer Console.
Hash Header This should be sent in the header of the request as hash SHA512 hash of (requestReference+SecretKey)

Sample Response (Success)

{ 
    "PaymentReference":"FBN|Web|3QTC0001|RS1|131113165041|00000024",
    "Amount":"10000",
    "TransactionDate":"11/13/2013 4:50:41 PM","ResponseCode":"00",
    "ResponseDescription":null
}
RESPONSE MESSAGE DESCRIPTION
Parameter Extra Info Format Description
ResponseCode Alphanumeric Represents the Response Code returned by the Service
ResponseDescription Alphanumeric The domain of your website.
Amount Returned if response is successful Numeric The amount paid by the customer in kobo.
PaymentReference Alphanumeric Quickteller generated unique ID for the payment (also referred to as the TransactionReference)
TransactionDate Header Datetime Date and time of the transaction

Test Details

Field Description
Client ID localhost
Secret Key E9300DJLXKJLQJ2993N1190023
Payment Code  95101
Request Reference Prefix 9999

Test Payment Cards

Type of Card Card PAN Expiry Date (Full) Expiry Date (Short) PIN CVV2
Successful Transactions Card 6280511000000095 December, 2026 12/26 0000 123
VISA Test Card 4000000000000622 January 2020 01/20 N/A 535
Insufficient Funds Card 5061030000000000027 January 2022 01/22 1234 123
No Card Record Card 5061030000000000043 January 2022 01/22 1234 123
Exceeds Withdrawal Limit Card 5061030000000000068 January 2022 01/22 1234 123
Incorrect PIN Card 5061030000000000035 January 2022 01/22 0000 123
Refer to Card Issuer (sometimes masked as Transaction error on WebPAY) 5061030000000000050 January 2022 01/22 1234 123

Response Codes

Code Description
X00 Account error, please contact your bank.
X04 The amount requested is too low.
X03 The amount requested is above the limit permitted by your bank, please contact your bank.
14 The card number inputted is invalid, please re-try with a valid card number.
38 Incorrect security details provided. Pin tries exceeded.
55 Incorrect security details provided.
56 Incorrect card details, please verify that the expiry date inputted is correct.
57 Your bank has prevented your card from carrying out this transaction, please contact your bank.
61 Your bank has prevented your card from carrying out this transaction, please contact your bank.
00 Approved by Financial Institution.
01 Refer to Financial Institution .
02 Refer to Financial Institution, Special Condition.
03 Invalid Merchant.
04 Pick-up card.
05 Do Not Honor.
06 Error.
07 Pick-Up Card, Special Condition.
08 Honor with Identification.
09 Request in Progress.
10 Approved by Financial Institution, Partial.
11 Approved by Financial Institution, VIP.
12 Invalid Transaction.
13 Invalid Amount.
15 No Such Financial Institution .
16 Approved by Financial Institution, Update Track 3 .
17 Customer Cancellation.
18 Customer Dispute.
19 Re-enter Transaction.
20 Invalid Response from Financial Institution.
21 No Action Taken by Financial Institution.
22 Suspected Malfunction.
23 Unacceptable Transaction Fee.
24 File Update not Supported.
26 Duplicate Record.
27 File Update Field Edit Error.
28 File Update File Locked.
20053 Data Verification Failed.
70035 You have not been set up to make this call.
70038 Missing Header.