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.

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

{ 
  "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"
}

{ 
  "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:

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

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)

{ 
    "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.