Merchant Manual (Technical)

GTPay INTEGRATION OF MERCHANT ONTO GTPay GTPay TRANSACTION REQUEST URL SENDING TRANSACTION REQUESTS TO GTPay GTPay TRANSACTION PROCESSING GTPay RETURNED TRANSACTION STATUS REPORT PARAMETERS GTPay TRANSACTION ERROR CODES GTPay TRANSACTION STATUS CODES AND DESCRIPTIONS GT-Merchant (GTPay test merchant)

GTPay
For an overview on GTPay: description, benefits, supported gateways, a summary of mode of operations and GTPay's URLs, please click here

INTEGRATION OF MERCHANT ONTO GTPay

For information on merchant's integration onto GTPay, please click here

GTPay TRANSACTION REQUEST URL

All transaction requests must be sent to URL: https://gtpay.gtbplc.com/public/tranx.jsp

SENDING TRANSACTION REQUESTS TO GTPay

Merchants registered on GTPay send transaction requests to GTPay via HTTP Post to URL https://gtpay.gtbplc.com/public/tranx.jsp . When merchant's customer on merchant's site concludes selection of items to purchase and chooses to pay via GTPay, the merchant's site will send such transaction request to GTPay via HTTP Post including the HTTP parameters described in the table below: Max Length

Parameter

Description

Type

Required gtpay_mert_id This is the GTPay-wide unique identifier of merchant, assigned by GTPay and communicated to merchant by GTBank. Optional This is a merchant-wide unique identifier of each transaction request sent to GTPay by merchant. If this parameter is not sent, GTPay always generate a unique identifier for the transaction. gtpay_tranx_id NOTE: Merchants should consistently send or otherwise not send this parameter as sending it in one transaction and not in another may result in duplicate transaction ID which will invalidate the transaction. -80 numeric 4

*Optional* The total monetary value of transaction. If not sent, GTPay will calculate the total monetary value of transaction from parameters gtpay_item_name_X and gtpay_item_price_X as described below. NOTE: Either this parameter is specified or the parameters gtpay_item_name_X and gtpay_item_price_X are specified. If gtpay_item_name_X and gtpay_item_price_X are not specified, in which case the transaction amount is given by this parameter, the whole transaction will be named "MERCHANT-GENERIC". NOTE: If this parameter is sent its value is used as transaction amount, regardless of whether parameters gtpay_item_name_X and gtpay_item_price_X are sent, and regardless of the total of all the gtpay_item_price_X's sent.

gtpay_tranx_amt

numeric

10

*Optional* The value of this parameter will be the name of an item been purchased by merchant's customer. The suffix "X" here must be numeric, some sort of serial number given to the item in a -particular purchase. For example, gtpay_item_name_1 for Item-1, gtpay_item_name_2 for item 2 selected by customer, gtpay_item_name_3 for item 3, etc. Note, the "X" here must have a corresponding gtpay_item_price_X. *Optional* The value of this parameter will be the price of an item been purchased by merchant's customer. The suffix "X" here must be numeric and must match a corresponding gtpay_item_name_X. For example, Say there is an item denoted by gtpay_item_name_8, then to tell GTPay the price of this item, there must be a corresponding gtpay_item_price_8 in the same transaction request. NOTE: Either parameters gtpay_item_name_X and gtpay_item_price_x are specified or gtpay_tranx_amt is specified.

gtpay_item_name_X

120

gtpay_item_price_X

numeric

10

Optional gtpay_tranx_curr This parameter specifies a symbol representing the currency in which the transaction is been carried out. If not specified, merchant's currency symbol in GTPay's database will be used. Required The value of this parameter will be the merchant-wide unique identifier of the customer. For example, for a student paying for school fees online, this may be the student's School's Registration Number, since the registration number is unique to that student throughout the whole school. Optional This describes the transaction to the customer. For example, gtpay_tranx_memo = "John Adebisi (REG13762) : 2nd Term School Fees Payment" If not sent, "Purchasing from [Business-Name-Of-Merchant]" will be used -3

gtpay_cust_id

--

60

gtpay_tranx_memo

--

120

Optional The URL to which GTPay should send transaction status report to on completion of transaction. If not specified, merchant's value in GTPay database will be used. If merchant has no value in GTPay database for this parameter, and the parameter is not included in the transaction request, GTPay will simply show transaction status report to customer, and not redirect back to merchant's site. Optional This parameter is intended to hold the value of the session ID on merchant's server for the session on merchant's server in which this transaction request was sent. When status report is sent to merchant at completion of transaction, this could be used to recover from session loss or mix-up for merchants that store transaction information in sessions. Optional If GTPay should not show the value of parameter gtpay_cust_id gtpay_no_show_cust_id to the customer. If not specified, merchant's value in GTPay database will be used.

gtpay_tranx_noti_url

URL characters

120

gtpay_req_session_id

--

80

yes or no

Optional If GTPay should not show any GTBank's symbols, like GTBank logo, the word "GTPay", etc. If not specified, merchant's value in GTPay database will be used.

gtpay_no_show_gtbank

yes or no

**Optional** gtpay_gway_name If specified, then customer cannot choose what gateway to use for webpay or etranzact the transaction. Accepted values are "webpay" or "etranzact" only. **Optional** If GTPay should take customer directly from merchant's page to the gateway to effect the debit/credit. If not specified, customer will be shown GTPay's own first page, from where he/she will click Continue to go to the gateway. NOTE: If specified, then gtpay_gway_name must be specified. 9

gtpay_gway_first

yes or no

Optional gtpay_echo_data Merchant can store in this parameter any data that it needs returned back at transaction completion. -255

Following is an example transaction request (you may copy and paste the HTML code into a text file, save it as HTML file and open the file):

<html> ... <body onload="document.submit2gtpay_form.submit()"> <form name="submit2gtpay_form" action="https://gtpay.gtbplc.com/public/tranx.jsp" target="_self"> <input type="hidden" name="gtpay_mert_id" value="17"> <input type="hidden" name="gtpay_item_name_1" value="2nd term school fees"> <input type="hidden" name="gtpay_item_price_1" value="31000"> <input type="hidden" name="gtpay_item_name_2" value="2nd term accomodation fees"> <input type="hidden" name="gtpay_item_price_2" value="4000"> <input type="hidden" name="gtpay_cust_id" value="REG13762"> <input type="hidden" name="gtpay_no_show_cust_id" value="no"> //no = show, whereas yes = dont show <input type="hidden" name="gtpay_tranx_memo" value="John Adebisi: 2nd term school and accomodation fees"> <input type="hidden" name="gtpay_echo_data" value="DEQFOOIPP0;REG13762;John Adebisi: 2nd term school and accomodation fees;XNFYGHT325541;1209"> </form> </body> </html>

There is a test merchant "GT-Merchant" configured on GTPay, you can test this at URL: https://gtpay.gtbplc.com/public/test/index.html

Back To Top

GTPay TRANSACTION PROCESSING

For an overview of GTPay's mode of transaction processing, please click here The transaction processing steps are now described in details as follows:
G

GTPay receives transaction request and validates it On receiving transaction request from merchant, GTPay validates the request, making sure that required parameters are supplied with appropriate values, transaction amount can be correctly determined, etc. If transaction request fails this validation phase, the transaction is NOT logged in GTPay's database, is rejected on the basis of invalid transaction, and a status code of -2 is returned to merchant, or shown to customer in the case gtpay_tranx_noti_url is not supplied, denoting INVALID TRANSACTION, and GTPay simply terminates the transaction. Please click here for a list of all error codes and their descriptions.

Transaction request passes GTPay validation and is forwarded to gateway If the transaction request passes GTPay's validation, GTPay logs all information relating to the transaction request, then, if gtpay_gway_first is not specified or its value is "no", shows the customer its own first page, on which customer can choose the gateway to use for transaction if gtpay_gway_name is not specified, and the customer clicks the "Continue" button to go to the gateway for debit/credit. If, however, gtpay_gway_first is yes, then the customer is simply taken straight to the gateway specified by gtpay_gway_name.

Gateway attempts transaction debit/credit leg and reports back to GTPay After logging details of transaction request in its database, GTPay forwards the debit/credit leg of the transaction request to the merchant-specified or customer-chosen gateway which handles the debit/credit and reports the result to GTPay.

GTPay receives transaction status from gateway and completes transaction On receiving the transaction status report from the gateway, GTPay updates the transaction information in its database with the received status report. Then sends the status report to the merchant or shows it to customer in case gtpay_tranx_noti_url is not known. The transaction ends from GTPay's point of view. Please click here for a list of all transaction status codes. For a list of all parameters sent to merchant in the transaction status report, click here.

Back To Top

GTPay RETURNED TRANSACTION STATUS REPORT PARAMETERS

On transactions completion, if merchant desires status of transactions, GTPay will send the following parameters to describe the transaction and how it has fared: Parameter Description

gtpay_tranx_id

The merchant-wide unique transaction identifier, sent by merchant in the transaction request sent, or generated for merchant by GTPay

gtpay_tranx_status_code The transaction status code denoting how transaction fared gtpay_tranx_status_msg A description of gtpay_tranx_status_code gtpay_tranx_amt The total monetary value of transaction

gtpay_tranx_curr The symbol used to denote the currency in which transaction was carried out gtpay_cust_id The merchant-wide unique identifier of the customer that carried out transaction

gtpay_tranx_memo

The description of the transaction sent by merchant, or "MERCHANT-GENERIC", if not earlier sent by merchant

gtpay_req_session_id The session ID on merchant server in which request came to GTPay

gtpay_gway_name

The name of the gateway that serviced transaction. This will be either webpay or etranzact

gtpay_referer The HTTP referer header of the page that submitted transaction request to GTPay

gtpay_echo_data

The miscellaneous data merchant sent earlier and wants returned at transaction completion

Back To Top

GTPay TRANSACTION ERROR CODES

Error Code Description What To Do

Error G000 This error is internal to GTPay itself. GTPay internal error G001 This error is internal to GTPay itself. Unknown GTPay parameter Merchant's request to GTPay includes a request parameter whose name starts with gtpay_ but the parameter is not one of GTPay's recognized transaction request parameters. Currently, this is not enforced Remove offending parameter, or edit it into a known parameter Contact GTBank Contact GTBank

G002

Invalid customer id G003 Merchant's request to GTPay does not include required request parameter gtpay_cust_id, or the parameter's value is empty Include the parameter with a non-empty value Include the parameter gtpay_tranx_amt with appropriate value or include parameters gtpay_item_name_X and gtpay_item_price_X with appropriate values

Invalid transaction amount G004 GTPay cannot for some reason determine the total monetary value of transaction request, or the value is not numeric or is 0 or less

Invalid item price G005 GTPay cannot successfully determine the monetary value of request parameter gtpay_item_price_X for some gtpay_item_name_X, perhaps because the gtpay_item_price_X is not correspondingly specified, is empty, not numeric or zero Invalid transaction notification url G006 Request parameter gtpay_tranx_noti_url is specified but its value is not in valid URL format Invalid gateway G007 Request parameter gtpay_gway_first is specified but gtpay_gway_name is not specified, or its value is empty, or its value is not webpay or etranzact. Invalid reference G008 Merchant desires that GTPay check the HTTP REFERER header, and GTPay determines the referer as invalid Edit the value of gtpay_gway_name as webpay or etranzact Check that your server is sending HTTP header "referer", and that the page sending transaction is the page you have noted to us for that purpose. Be sure to be sending the ID communicated to you as your GTPay-Assigned merchant ID Edit the value into a valid URL Include the correspoding gtpay_item_price_X with appropriate value

Invalid merchant G009 Specified merchant ID is not known to GTPay, or the ID is not specified Inactive merchant G010 Merchant is known to GTPay but is not currently permitted to accept payment via GTPay Inactive gateway Gateway is known to GTPay but is not currently permitted to handle transactions for GTPay Currently, this error is not possible.

Contact GTBank

G011

--

Duplicate transaction id G012 Merchant sent a transaction id which has already been sent for some previous transaction by same merchant. Invalid transaction id G013 Request parameter gtpay_tranx_id is present in request but its value is empty Gateway timeout G014 -Resend transaction with a new unique transaction ID

Resend transaction with a non-empty unique transaction ID

In this version of GTPay, the transaction is never cancelled on gateway timeout.

Gateway communication error G015 Communication with gateway failed for some reason Gateway update error G016 Unable to update transaction gateway information, typically this will regard updating eTranzact's ID

Resend transaction with a new unique transaction ID, or Contact GTBank Resend transaction with a new unique transaction ID, or Contact GTBank

Back To Top

GTPay TRANSACTION STATUS CODES AND DESCRIPTIONS

Code Description

-2 Invalid Transaction

-1

Transaction cancelled by customer at GTPay OR Transaction cancelled by customer at payment gateway

For a list of other codes, please click here

Back To Top

GT-Merchant (GTPay test merchant)

To test, browse: https://gtpay.gtbplc.com/public/test/index.html

Back To Top

GTPay, version 2.0 -- January 2008

Merchant Manual (General)

G

GTPay INTEGRATION OF MERCHANT ONTO GTPay WEBPAY AND ETRANZACT TEST CARDS

For technical information, see the GTPay Merchant Manual Technical

GTPay
For an overview on GTPay: description, benefits, supported gateways, a summary of mode of operations and GTPay's URLs, please click here

INTEGRATION OF MERCHANT ONTO GTPay

To be integrated onto GTPay, a merchant needs to do the following: 1. Register with at least one
supported payment gateway

Payment gateways usually charge registration fees and other fees to service merchants for ePayments on their platforms. For information on the latest modalities on these please click here for the contacts of our eBusiness unit. A merchant cannot be registered on GTPay

until they first register with at least one of our supported payment gateways 2. Send all required GTPay integration information to our
eBusiness unit

To download the form you need to fill in and submit to us for GTPay integration, please click here. NOTE: This is in addition to any gateway-specific forms. For a description of the information contained in the form, please click here. 3. Commence a Pilot phase to determine stability of integration On successful registration on GTPay, merchant's technical integration with GTPay will be watched for a period of time for correctness and stability. For card details to use in pilot phase, please click here 4. Cutover to live environment Whenever all parties, (Merchant, GTBank, and Gateway), agree that there has been a successful integration, after tests on Pilot environment after some period of time, merchant will be configured on live environment, after which actual bank accounts can be debited/credited.

Back To Top

GTBank's eBusiness Unit Contacts

You may contact our eBusiness unit on the following numbers:
G

234-1-4610906 234-1-2713193

Or physically at:
eBusiness Unit, GTBank, Tiamiyu Savage Street, Victoria Island, Lagos.

Back To Top

WEBPAY AND ETRANZACT TEST CARDS

While still on pilot on the gateways, make use of the following card details for testing for successful transactions. To test for unsuccessful transactions, simply vary the details. Gateway Card Details Card Number 1111222233334444 Interswitch WebPAY Expiry Date PIN Jan 2010 Any four digits

Card Number: 0910010705222055 eTranzact Expiry Date: PIN: Back To Top 05 2009 (May 2009) 1234

GTPay, version 2.0 -- January 2008

//EFT error codes: 00 = Transaction successful! 01 = An issue requires the attention of card issuer 02 = An issue requires the attention of card issuer, 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 = Transaction partially approved 11 = Transaction approved with VIP status 12 = Invalid transaction, transaction not supported or permitted here 13 = Invalid amount 14 = Invalid card number 15 = No such issuer, card issuer does not exist or is not recognized here 16 = Approved, update track 3 17 = Customer cancellation 18 = Customer dispute 19 = Re-enter transaction 20 = Invalid response 21 = No action taken 22 = Suspected malfunction in system 23 = Unacceptable transaction fee 24 = File update not supported 25 = Unable to locate record 26 = Duplicate record 27 = File update field edit error 28 = File update file locked 29 = File update failed 30 = Format error 31 = Card issuer or merchant's bank not supported 32 = Transaction completed partially 33 = Expired card, pick-up 34 = Suspected fraud, pick-up 35 = Contact acquirer, pick-up 36 = Restricted card, pick-up 37 = Call acquirer security, pick-up 38 = PIN tries exceeded, pick-up 39 = No credit account 40 = Function not supported 41 = Lost card, pick-up 42 = No universal account 43 = Stolen card, pick-up 44 = No investment account 45 = Account closed 46 = Identification required 47 = Identification cross-check required #48 to #50 Reserved for future Postilion use 51 = Insufficient funds in your account for this transaction 52 = No check account 53 = No savings account 54 = Expired card 55 = Incorrect PIN 56 = No card record 57 = Transaction not permitted to cardholder 58 = Transaction not permitted at this terminal 59 = Suspected fraud 60 = Contact acquirer, (your merchant's bank)

61 = Transaction financial value exceeds your withdrawal limit 62 = Restricted card 63 = Security violation 64 = Original amount incorrect 65 = You already exceeded withdrawal frequency set by card issuer 66 = Call acquirer security 67 = Hard capture 68 = Response received too late 69 = Advice received too late #70 to #74 Reserved for future Postilion use 75 = PIN tries exceeded #76 Reserved for future Postilion use 77 = Intervene, bank approval required 78 = Intervene, bank approval required for partial amount #79 to #89 Reserved for client-specific use (declined) 90 = Cut-off in progress 91 = Your financial institution is not currently available (try again in a moment) 92 = Routing error 93 = Violation of law 94 = Duplicate transaction 95 = Reconcile error 96 = System malfunction #97 Reserved for future Postilion use 98 = Transaction financial value exceeds cash limit #99 Reserved for future Postilion use #o A to A Zero Reserved for future Postilion use A1 = ATC not incremented A2 = ATC limit exceeded A3 = ATC configuration error A4 = CVR check failure A5 = CVR configuration error A6 = TVR check failure A7 = TVR configuration error #A8 to #BZ Reserved for future Postilion use C0 = Unacceptable PIN C1 = PIN Change failed C2 = PIN Unblock failed #C3 to #D Zero Reserved for future Postilion use D1 = MAC Error #D2 to E Zero Reserved for future Postilion use E1 = Prepay error #E2 to MZ Reserved for future Postilion use #N Zero to ZZ Reserved for client-specific use (declined) //InterSwitch WebPAY-specific error codes: W56 w56 W09 w09 W63 w63 W57 w57 W06 w06 W17 w17 W94 w94 = = = = = = = = = = = = = = Transaction record not found in payment gateway system Transaction record not found in payment gateway system Transaction request is still in progress at payment gateway Transaction request is still in progress at payment gateway payment gateway security violation payment gateway security violation Merchant deactivated at payment gateway Merchant deactivated at payment gateway payment gateway application error payment gateway application error Customer cancellation at payment gateway Customer cancellation at payment gateway Duplicate transaction reference at payment gateway Duplicate transaction reference at payment gateway

//eTranzact error codes (as used by GTPay): 000 001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 = = = = = = = = = = = = = = = = = = = Transaction Successful! Destination Card Not Found Card Number Not Found Invalid Card PIN Card Expiration Incorrect Insufficient balance Spending Limit Exceeded Internal System Error Occured please contact the service provider Financial Institution Cannot authorise transaction Please try later PIN tries Exceeded Card has been locked Invalid Terminal Id Payment Timeout Destination card has been locked Card has expired PIN change required Invalid Amount Card has been disabled Unknown Error Occurred please contact the service provider