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

webpay_steps

Step 1
POST is made with Transaction parameters to the Interswitch payment gateway. This is known as the beginning of the payment leg.

Step 2
A RESPONSE is sent from the payment gateway

Step 3
The merchant’s website initiates a GET request to the payment gateway requesting the status of the concluded PAY transaction. This is the beginning of the getTransactionleg.

Step 4
A RESPONSE is sent from the payment gateway containing the status of the transaction.

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://sandbox.interswitchng.com/webpay/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://sandbox.interswitchng.com/webpay/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.

Note!

This sample is used for illustrative purposes only. The data you would be hashing in reality may be somewhat different, so please take note. If you wish to try this out with more realistic data inputs you can go ahead and use the demo merchant details

 

Heads up!

When you are ready to go through UAT and production afterward, you would get unique MAC keys. Please be sure to use those instead of the test one provided in this documentation.

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.

Field

Description

txnref The transaction Reference initially generated & sent by the merchant site will be sent back with this variable.
payRef A reference number that uniquely identifies all transactions that goes through the gateway.
retRef Reference number from the switch’s interconnecting with the banking application.
cardNum Will always have a value of 0
apprAmt Will always have a value of 0

Sample Response

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

 

How to query the transaction on WebPAY

GET https://sandbox.interswitchng.com/webpay/api/v1/gettransaction.json

GET https://sandbox.interswitchng.com/webpay/api/v1/gettransaction.xml

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

Parameter

Description

Format

product_id The PAYDirect product

numeric

txn_ref Transaction reference sent in the POST by the merchant

alphanumeric

amount Original amount sent in the transaction, in small denomination

numeric

Hash SHA512 hash of productid, transactionreference and your hash key

This should be sent in the header of the request as Hash

Sample transaction query

GET https://sandbox.interswitchng.com/webpay/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://sandbox.interswitchng.com/webpay/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

Proposed masked response Response
Code
Account error, please contact your bank X00
The amount requested is above the limit permitted by your bank, please contact your X03
bank
The amount requested is too low X04
The amount requested is above the limit permitted by your bank, please contact your X05
bank
The card number inputted is invalid, please re-try with a valid card number 14
Incorrect security details provided. Pin tries exceeded. 38
Incorrect security details provided. 55
Incorrect card details, please verify that the expiry date inputted is correct 56
Your bank has prevented your card from carrying out this transaction, please contact 57
your bank
Your bank has prevented your card from carrying out this transaction, please contact 61
your bank
Incorrect security details provided. Pin tries exceeded. 75
Approved by Financial Institution 00
Refer to Financial Institution 01
Refer to Financial Institution, Special Condition 02
Invalid Merchant 03
Pick-up card 04
Do Not Honor 05
Error 06
Pick-Up Card, Special Condition 07
Honor with Identification 08
Request in Progress 09
Approved by Financial Institution, Partial 10
Approved by Financial Institution, VIP 11
Invalid Transaction 12
Invalid Amount 13
No Such Financial Institution 15
Approved by Financial Institution, Update Track 3 16
Customer Cancellation 56
Customer Dispute 18
Re-enter Transaction 19
Invalid Response from Financial Institution 20
No Action Taken by Financial Institution 21
Suspected Malfunction 22
Unacceptable Transaction Fee 23
File Update not Supported 24
Duplicate Record 26
File Update Field Edit Error 27
File Update File Locked 28
File Update Failed 29
Format Error 30
Bank Not Supported 31
Completed Partially by Financial Institution 32
Expired Card, Pick-Up 33
Suspected Fraud, Pick-Up 34
Contact Acquirer, Pick-Up 35
Restricted Card, Pick-Up 36
Call Acquirer Security, Pick-Up 37
PIN Tries Exceeded, Pick-Up 38
No Credit Account 39
Function not supported 40
Lost Card, Pick-Up 41
No Universal Account 42
No Investment Account 44
Insufficient Funds 51
No Check Account 52
No Savings Account 53
Expired Card 54
Incorrect PIN 55
No Card Record 56
Suspected Fraud 59
Contact Acquirer 60
Restricted Card 62
Security Violation 63
Original Amount Incorrect 64
Exceeds withdrawal frequency 65
Call Acquirer Security 66
Hard Capture 67
Response Received Too Late 68
PIN tries exceeded 75
Intervene, Bank Approval Required 77
Intervene, Bank Approval Required for Partial Amount 78
Cut-off in Progress 90
Issuer or Switch Inoperative 91
Routing Error 92
Violation of law 93
Duplicate Transaction 94
Reconcile Error 95
System Malfunction 96
Exceeds Cash Limit 98

One Comment

  1. Demurin Emmanuel

    I am a newbie in internet marketting. I do not understand the commands given above to set up my online payment and post it to WEBPAY and I do not want to cause any error. I want INTERSWITCH to help me do it and give me a link that will direct my customers from my site to the WEBPAY. I will allow INTERSWITCH to deduct #50 from every payment via their online integration. I will be very grateful if my request is granted. I hope to see your response via email address