Integration Overview

Introduction

Integrating Interswitch WebPAY with an existing website is extremely easy and can be achieved with a few simple steps. At a high level you want to achieve the following:

• POST transaction details to load the WebPAY page
• Calculate a request hash to ensure transaction integrity
• Provide a URL which WebPAY would post back the authorization response
• Query the transaction details directly from WebPAY to ensure the actual transaction amount was approved

The only requirement is to POST data to the WebPAY server. The section below describes how to create this POST

How to post transaction details

Create an HTML form wherever you would like your ‘Pay’ button to appear and the set the form’s method to POST and the action attribute to https://stageserv.interswitchng.com/test_paydirect/pay.

Create a submit button in the form and a few hidden fields through which you would assign transaction values you wish to post. See Fields and values for the required fields and a few optional ones.

The sample form below illustrates how the field values are setup and posted to WebPAY.

<formname="form1"action="https://stageserv.interswitchng.com/test_paydirect/pay"method="post"><inputname="product_id"type="hidden"value="XX"/><inputname="pay_item_id"type="hidden"value="XX"/><inputname="amount"type="hidden"value="XXXXXXX"/><inputname="currency"type="hidden"value="566"/><inputname="site_redirect_url"type="hidden"value="http://abc.com /getresponse”/><inputname="txn_ref"type="hidden"value=" XXXAFTXXX”"/><inputname="hash"type="hidden"value="BB292DF9268F05CB9CBBC5E0C13CC1B13ACA34DC"/></form>

How to compute the request hash

When you are setup for WebPAY you will be giving a secret MAC key that would be used to hash your request data. This is necessary to prevent man-in-the-middle attacks and it therefore needs to be kept secret.

The following fields are to be combined (in this same order) to create the request hash using SHA512 algorithm and the secret MAC key assigned.

• tnx_ref
• product_id
• pay_item_id
• amount
• site_redirect_url
• <the provided MAC key>

For example, given a transaction with the following details:

txn_ref

7645536

product_id

174

pay_item_id

23

amount

1000000

site_redirect_url

http://www.yoursite.com/return/

MAC key

AC43543FA32234HB23423AFH843535

The resulting string on which the SHA512 algorithm would be computed would be:

7645536174231000000http://www.yoursite.com/return/AC43543FA32234HB23423AFH843535

And the final hash that would be sent in the request should be:

CE69DB9638BB5F26FFF0B80F1F53640E3F52C5129D06CEBF035C0125D1BCE4173AD4D597FEC8179466DA295E67F43DE41F43E4913E9AD6236B449F4ED05CCCE3

You would find a good tool that can help verify that you are doing the SHA512 correctly here.

How to process the response

The following are the parameters returned by WebPAY for real time transactions.  Note that WebPAY will perform a POST request to the site_redirect_url provided in the request to WebPAY.

Sample Response

txnref=1234567&payRef=&refRef=238477494594&cardNum=0&apprAmt=0

How to query the transaction on WebPAY

GET https://stageserv.interswitchng.com/test_paydirect/api/v1/gettransaction.json

GET https://stageserv.interswitchng.com/test_paydirect/api/v1/gettransaction.xml

This service is used to get the status of a transaction.

Sample transaction query

GET https://stageserv.interswitchng.com/test_paydirect/api/v1/gettransaction.json?productid=21&transactionreference=8421941122&amount=300000 HTTP/1.1UserAgent:Mozilla/4.0(compatible; MSIE 6.0; MS WebServicesClientProtocol4.0.30319.239)Hash: F6FF2E22F99D93DDDA52D71811FD92B3A71FA1968A66216E0D310DAD

GET https://stageserv.interswitchng.com/test_paydirect/api/v1/gettransaction.xml?productid=21&transactionreference=8421941122&amount=300000 HTTP/1.1UserAgent:Mozilla/4.0(compatible; MSIE 6.0; MS WebServicesClientProtocol4.0.30319.239)Hash: F6FF2E22F99D93DDDA52D71811FD92B3A71FA1968A66216E0D310DAD

Sample transaction query response

HTTP/1.1200 OK
Date:Thu,20Dec201211:27:44 GMT
Cache-Control:no-cache
Pragma:no-cache
Expires:-1Content-Type: application/json; charset=utf-8Content-Length:331{"Amount":300000,"CardNumber":"6055","MerchantReference":"4989328211","PaymentReference":"ZIB|WEB|VNA|18-12-2012|018158","RetrievalReferenceNumber":"000000557679","LeadBankCbnCode":null,"LeadBankName":null,"SplitAccounts":[],"TransactionDate":"2012-12-18T15:36:52.9","ResponseCode":"00","ResponseDescription":"Approved Successful"}

HTTP/1.1200 OK
Date:Thu,20Dec201211:26:35 GMT
Cache-Control:no-cache
Pragma:no-cache
Expires:-1Content-Type: application/xml; charset=utf-8Content-Length:550<TransactionQueryResponse><ResponseCode>00</ResponseCode>
    <ResponseDescription>Approved Successful</ResponseDescription><Amount>300000</Amount> <CardNumber>6055</CardNumber><MerchantReference>4989328211</MerchantReference>
    <PaymentReference>ZIB|WEB|VNA|18-12-2012|018158</PaymentReference><RetrievalReferenceNumber>000000557679</RetrievalReferenceNumber>
    <SplitAccounts/><TransactionDate>2012-12-18T15:36:52.9</TransactionDate>
</TransactionQueryResponse>

WebPAY Responses