Payment Gateway Integration Guide For Merchants-V4.6

INTEGRATION GUIDE FOR MERCHANTS
Version 4.6
01 Jan 2021
Payaxis – Integration Guide
Copyright
This is unpublished, confidential document of TPS Pakistan Pvt Ltd.
No part of this document may be reproduced, stored in retrieval form, adopted or transmitted in any
form or by any means, electronic, mechanical, photographic, graphic, optic or otherwise, translated
in any language or computer language, without prior written permission from TPS Pakistan Pvt Ltd.
This document has been prepared with all due diligence, however, TPS, makes no representation or
warranties with respect to the contents hereof and shall not be responsible for any loss or damage
caused to the user by the direct or indirect use of this document and the accompanying information.
Furthermore TPS, reserves the right to alter, modify or otherwise change in any manner the content
hereof, without the obligation to notify any person of such revision or changes.
All registered and trademarked names referred to in this document are owned by their respective
owners.
COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - ii -

Document History
Date Author Status Change Reference
Added new sections for 1.1.1.1.1.1 Added: Section 9 and 7.3

Bina Khan
15th April Confirmation/Reversal. Updated all sections Updated: Sections 6, 7
and Faizan
2014 for introducing Settlement Expiry and and Appendix 1.
Ahmed
Confirmation flows.
22nd April Usman
Format, Appendix III fixed length Updated section: 14
2014 Danish
Mohamma
29th April Made Bank ID field as Mandatory in Payment
d Furqan section 8.1
2014 Status Update
Zakeria
30th April Removed Customer IBAN fields and updated
Bina Khan Sections 6.2 and 8.1.
2014 length of Bank ID field.
Removed Bill Reference parameter from
7th August Sections 5.2, 6.1, 7.1, 7.2,
Bina Khan Status Service.
2014 7.3, 8.1, 9, 9.1, 9.2
Removed other minor issues.
th
25
Adeel
December Revision of document Complete document
Siddiqui
2015
16th June Adeel
Revision of Payment Status Update Sections 8, 8.1, 8.2, 8.3
2016 Siddiqui
26th July Iqbal
Addition of HMAC calculation Sub section 11.2
2016 Maskati
Set bank Id and product Id as optional in
Payment inquiry and OTC update, added
16th August, Muhamma Section 7.1 & 8.1,
field CustomercardNo And increase Auth
2016 d Mujtaba appendix 1
code length to 12 in payment Status Inquiry
Response.
25th August, Zia Ur
OTC Payment API Module Section 11
2016 Rehman
09th Sept, Iqbal Status Update in All transaction types. Added
Section 8,14
2016 Maskati response Codes
6th January, Muhamma ASCII:32 will be used for white space in
Section 7.2
2016 d Mujtaba inquiry response
Added response code of 129. Modified
24th March, Muhamma Section 6.1, 6.2, 11.1, 11.2
transaction parameters with respect to
2017 d Mujtaba & 14
discount module.
22nd May, Muhamma Added response code + Added
Section 12, Section 15
2017 d Mujtaba documentation for Card API
31 July, Muhamma Response code updated with respect to
Section 15
2017 d Mujtaba MPGS APIs
Muhamma Setting txnexpiry in payment request as
Section 6.1, Section 11.2
d Mujtaba optional and update pp_description remarks
COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - iii -

Added tokenization description for payment

portal.
Added pp_IsRegisteredCustomer,
pp_TokenizedCardNumber in payment
request.
Added pp_IsRegisteredCustomer,
pp_TokenizedCardNumber,
Section 5.2,
20 pp_TokenizationResponseCode,
Rabia Section 6.1,Section 6.2
December,2 pp_TokenizationResponseMsg,
Qaiser
018 pp_CustomerCardNo,
Section 15 Appendix I
pp_CustomerCardExpiry in payment
response.
Rename response code field of existing table

as Payment Response Code.
Add new table for Tokenization Response

Codes.
Ali Abid
25 Feb 2019 Delete Token Api added Section 13
Zaidi
Adding request fields
pp_CustomerID,
pp_CustomerEmail,
pp_ CustomerMobile
27 Mar Ali Abid Adding response fields Section 6.1, Section 6.2,
2019 Zaidi pp_CustomerID, Section 13.2
pp_ CustomerEmail,
pp_CustomerMobile
Adding Instant Token Notification API.
04 Idrees
Retrieve Token Api added Section 13.6
April,2019 Shabbir
Following Apis are added
Section
08 Idrees 1. Version2.0-PaymentAuthorize
12.1,12.2,12.3,12.4,12.5,
May,2019 Shabbir 2. Version2.0-PaymentAuthorize Token
12.6
3. Version2.0-Capture
14 Nov 2019 Aamir Amin Fields Description added for all 2.0 APIs
 Token Inquiry API added
Shazia
09 Dec 2019  Formatting of document
Tabassum
 Via Account APIs added
29 Apr 2020 Aamir Amin  Wallet REST API 2.0 added Section 7.2, 7.3
Shazia  Wallet Refund REST API added
20 Jan 2021 Section 7.1.7, 7.1.8
Tabassum  Card Refund REST API added
COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - iv -

Table of Contents
OVERVIEW ............................................................................................................. 1
1.1 WHO SHOULD READ THIS GUIDE ............................................................................. 1
1.2 RELATED DOCUMENTS........................................................................................... 1
BUSINESS FLOW..................................................................................................... 2
2.1 PAYMENT METHODS ............................................................................................. 3
2.1.1 Debit/Credit Card .................................................................................. 3
2.1.2 Mobile Wallet ....................................................................................... 3
2.1.3 Over the Counter ................................................................................... 4
2.1.4 Via Account ........................................................................................... 4
2.1.5 Direct Debit ........................................................................................... 4
2.1.6 Refund .................................................................................................. 5
2.2 INQUIRY............................................................................................................. 5
2.2.1 Payment Status Inquiry ......................................................................... 5
2.2.2 Token Inquiry ........................................................................................ 5
2.3 STATUS UPDATE .................................................................................................. 5
2.3.1 Payment Status Update ......................................................................... 5
2.3.2 Delivery Status Update .......................................................................... 5
2.4 NOTIFICATION ..................................................................................................... 6
2.4.1 Instant Payment Notification (IPN) ........................................................ 6
2.4.2 Instant Token Notification (ITN) ............................................................. 6
2.5 TOKEN OPERATION ............................................................................................... 6
2.5.1 Delete Token ......................................................................................... 6
2.5.2 Retreive Token ...................................................................................... 6
MERCHANT SETUP PROCESS .................................................................................. 7
PAYMENT GATEWAY TEST SYSTEM ........................................................................ 8
PAYMENT INTEGRATION VIA PAYMENT PORTAL ................................................... 9
5.1 VERSION 1.1 ...................................................................................................... 9
5.1.1 Request ................................................................................................. 9
5.1.2 Response............................................................................................. 12
5.2 VERSION 2.0 .................................................................................................... 14
5.2.1 Request ............................................................................................... 14
5.2.2 Response............................................................................................. 16
PAYMENT INTEGRATION VIA SOAP APIS.............................................................. 20
6.1 MWALLET & OTC .............................................................................................. 20
6.1.1 Request ............................................................................................... 20
6.1.2 Response............................................................................................. 22
6.1.3 Sample ................................................................................................ 24
6.2 PAYMENT STATUS INQUIRY ................................................................................... 25
6.2.1 Request ............................................................................................... 26
6.2.2 Response............................................................................................. 27
6.3 DELIVERY STATUS UPDATE ................................................................................... 28
6.3.1 Request ............................................................................................... 29
6.3.2 Response............................................................................................. 29
6.3.3 Processing Details ............................................................................... 30
PAYMENT INTEGRATION VIA REST APIS............................................................... 32
COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. -v-

7.1 DEBIT/CREDIT CARD PAYMENT .............................................................................. 32

7.1.1 Authorize Payment .............................................................................. 32
7.1.2 Capture Payment ................................................................................ 36
7.1.3 Void .................................................................................................... 38
7.1.4 Check 3DS Enrollement ........................................................................ 39
7.1.5 Process ACS ......................................................................................... 44
7.1.6 Direct Pay ........................................................................................... 47
7.1.7 Refund ................................................................................................ 52
7.2 MWALLET PAYMENT .......................................................................................... 54
7.2.1 Pay ..................................................................................................... 54
7.2.2 Refund ................................................................................................ 58
7.3 OTC PAYMENT .................................................................................................. 60
7.3.1 Pay ..................................................................................................... 60
7.4 VIA ACCOUNT PAYMENT ...................................................................................... 64
7.4.1 Auth Token.......................................................................................... 64
7.4.2 List of Banks ........................................................................................ 65
7.4.3 Generate OTP ...................................................................................... 65
7.4.4 Pay Via Account .................................................................................. 68
7.5 PAYMENT STATUS INQUIRY ................................................................................... 72
TOKENIZATION API .............................................................................................. 75
8.1 DELETE TOKEN .................................................................................................. 75
8.1.1 Version 1.0 .......................................................................................... 75
8.1.2 Parameter Detail ................................................................................. 75
8.2 RETRIEVE TOKEN ................................................................................................ 76
8.2.1 Version 1.0 .......................................................................................... 76
8.3 INQUIRE TOKEN ................................................................................................. 78
8.3.1 Version 1.0 .......................................................................................... 78
WEB HOOK .......................................................................................................... 80
9.1 PAYMENT STATUS UPDATE (IPN)........................................................................... 80
9.1.1 Request ............................................................................................... 80
9.1.2 Response............................................................................................. 82
9.2 INSTANT TOKEN NOTIFICATION (ITN)...................................................................... 82
9.2.1 Version 1.0 .......................................................................................... 82
CALCULATING AND VALIDATING THE SECURE HASH ............................................ 85
10.1HOW THE SECURE HASH IS CREATED AND VERIFIED .................................................... 85
10.2HOW IS SHA256- HMAC CALCULATED .................................................................. 86
PADDING RULES .................................................................................................. 87
APPENDIX I – RESPONSE CODE ............................................................................ 88
12.1PAYMENT RESPONSE CODE ................................................................................... 88
12.2TOKENIZATION RESPONSE CODE ............................................................................ 90
APPENDIX II – FIXED LENGTH ............................................................................... 92
COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - vi -

Overview
This Payment Gateway Integration Guide for Merchants is a technical integration document
for Merchants to interface with PMCL Payment Gateway (PG) allowing their customers to
perform e-commerce transactions over the internet.
It guides merchant on how to use various functionality of the Payment Portal Integration and
describes the interfacing specification of Version 1.1 & 2.0 of Payment Gateway Portal. The
Merchant can enable multiple modes of payment over their e-commerce website with this
integration:
 Credit/Debit Card
 Over the counter (Voucher)
 Mobile Wallet
 Via Account
 Direct Debit (using customer’s Banking portal)
Furthermore, the guide also elaborates on the business logic and transaction flow of payment
processing done through the Payment Gateway with respect to the new interface for payment
processing.
The Payment Gateway’s Payment Portal provides the online merchants

1.1 Who Should
an easy to use interface enabling them to process transactions over their
Read This Guide e-commerce websites. The interfacing is done through standard web
technologies and requires minimal development at the merchant end.
Moreover, Payment Portal does not require any software to be installed
at the merchant end and allows the merchants to leverage their existing
infrastructure and applications to enable transaction processing through
Payment Gateway.
The document is intended for application developers and business

analysts at merchant to allow them to integrate effectively with the
Payment Gateway Portal Interface or APIs.
A Merchant Portal by Payment gateway is also available to all merchants

1.2 Related
in addition to Payment Portal Interface. The Merchant Portal offers a
Documents variety of back-office features related to merchant administration of
Payment Gateway. For complete details Payment Gateway Merchant
Portal Guide may be referenced.
COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 1 of 85

Business Flow
This section describes the business transaction flow or the customer experience during
payment cycle using Debit Card and Direct Debit option. It is designed to highlight the
transaction handling at Merchant website and responsibilities shared between Merchant and
Payment Gateway during the online end-to-end cycle:
The online user experience will be divided between two portals:
1. Merchant’s Web site

2. Payment Gateway
Merchant’s Web Site:
The merchant’s portal will prepare the item cart and offer the check-out option to the
customer. The transaction flow and information captured are as follows:
1. Product Selection: The customer selects one or more products to be bought from the
merchant
2. Product Details: Upon check-out the merchant confirms the items to be purchased
3. Product Payment Details: An invoice will be presented to the customer that includes
the price of each product and the total amount payable
Note: If the merchant is integrated with multiple payment gateways then the
following step (4) will be presented otherwise the customer will be redirected to the
Payment Gateway
4. Payment Method: If the merchant is integrated with multiple payment gateways the
customer will be prompted to select a payment method. If the customer chooses to
pay by debit card, direct debit, mobile wallet or over the counter then he will be
redirected to the Payment Gateway.
Payment Gateway:
The Payment Gateway will receive control from the merchant’s website, based on the
transaction options selected at merchant end. Following will be the customer experience:
Payment Method Selection: This screen will be shown to customer if Merchant did not offer
Payment Method Selection (4) at its end.
Customer will be presented with Payment Method Selection covering:

a. Debit/Credit Card
b. Mobile Wallet
c. Via Account
d. Over The Counter
e. Direct Debit.

2.1 Payment
Methods
2.1.1 Debit/Credit Card

The Payment Gateway supports two payment models:
2.1.1.1 Offline Pay Integration

Also known as Authorize-Capture model. It is a mode where the merchant first does
an authorization to reserve the funds, then (typically after shipping the goods) does
a capture. Card scheme rules prevent charging the payer until goods are shipped,
so this mode is frequently used by mail-order companies.
2.1.1.2 Direct Pay Integration

A single transaction to authorize the payment and transfer funds from the payer's
account to your account. For card payments, Pay is a mode where the Authorize
and Capture operations are completed at the same time.
In page redirection mode (i.e. Payment Portal Integration), only direct pay model
works having the below mentioned flow, however both types of integration are
available on API mode.
Card Number: Customer will enter his/her card number on Payment Gateway
Mobile Number: Customer will enter his/her mobile number on Payment Gateway. This is
an optional field for record keeping purpose
Expiry & CVV2: Customer will enter his Card Expiry & CVV2
Save Detail Option: If customer checks the Save card detail option, a token will be generated
and sent to merchant against his card details, upon the successful completion of transaction.
For returning customers, who have saved their cards will not be required to enter card
details again for any transaction with same card in future
Payment Gateway – Transaction Completion : Once Pay is clicked, the transaction will be
posted to relevant system for authorization. Upon successful transaction, customer will be
taken back to return URL of the merchant
2.1.2 Mobile Wallet

Mobile Number (MSISDN): Customer will enter his mobile number. Once Pay is clicked, the
transaction will be posted to relevant system for authorization.
Note: MPIN will be sent by CPS to the customer.

2.1.3 Over the Counter

This transaction enables a customer to make a transaction by providing the cash to any
retail outlet. Customer will get a voucher number of 12 digits, after clicking on Pay.
Customer will visit retail outlet and will pay the desired amount. The payment status will
be updated on Payment Gateway by the external system, and merchant will be notified
regarding the payment by generating IPN (Instant Payment Notification) by payment
gateway. After this, merchant will proceed to deliver the goods
2.1.4 Via Account

Using this feature, online merchants can collect funds directly from the Bank Account with the
approval of the account holder. This feature removes the requirement of cards altogether and
allows the payer to directly pay via their Account for any online purchases
Bank: Customer will be asked to select bank of his/her account
CNIC: Customer will be asked to enter his/her account number with CNIC
OTP: An OTP will be generated by issuer bank on customer’s registered mobile number and
he/she will be asked to enter the same on screen
Payment Gateway – Transaction Completion : PGW will capture the OTP and send the
request for authorization. Upon successful authorization from issuing bank, transaction will
be processed.
2.1.5 Direct Debit

This transaction enables a customer to make a transaction using an internet banking
account of member bank. A merchant provides transaction details (transaction amount,
order number, etc.) to the Payment Gateway. The Payment Page redirects the customer

to the respective member bank’s designated internet banking page. The customer will
login to the internet banking portal using his credentials and complete the transaction.
The member bank will then return the response to the payment gateway which in turn
will forward it to the merchant’s website. The details of the function are described in later
sections.
2.1.6 Refund
Trasnaction performed using Debit/Credit Card or wallet account can be refunded. In the
event of a customer dispute, the merchant may need to make full/partial refund of
transaction. The transaction refund option will allow the merchant to refund a transaction
processed by the Payment Gateway. Typically, a Refund is linked to the Pay through the
transaction reference no.
Merchant may refund a transaction fully or partially, deending upon the permission
assigned by the backoffice user.
2.2 Inquiry
2.2.1 Payment Status Inquiry

Payment Status Inquiry is a API (SOAP & REST) exposed by the Payment Gateway which
allows merchant to query the status of any transaction that has been performed by the
merchant using the Payment Gateway. The merchant can query against the transaction
reference no. This function will be used by merchant to query status of any transaction
type. The details of the function are described in later sections.
2.2.2 Token Inquiry

For those merchants using tokenization feature, it may happen that they do not receive
ITN (Instant Token Notification) which is used to send the newly generated token against
card details. In this case, merchant will call Token Inquiry API to get the token, against any
transaction reference no.
2.3 Status Update
2.3.1 Payment Status Update

Payment Status Update web service is to be exposed by Merchants so that Payment
Gateway can update the status of a pending transaction. Parameter details and signature
of the function are described in later sections.
2.3.2 Delivery Status Update

Delivery Status Update is a web service interface exposed by the Payment Gateway which
is to be invoked by the merchant to confirm the delivery of services or goods. The details
of the function are described in later sections.

2.4 Notification
2.4.1 Instant Payment Notification (IPN)

After every payment transaction, a notification is generated from Payment Gateway to
the merchant on the web hook provided by the merchant.
2.4.2 Instant Token Notification (ITN)

For those merchants using Tokenization feature, the token is generated on first
successful transaction containing token request. This token is sent to the merchant
asynchronously with the payment, using the web hook provided by the merchant.
2.5 Token Operation
2.5.1 Delete Token

If a customer has saved his/her card detail in the past, and now want to remove this
information from merchant’s website, he/she will trigger delete operation on merchant’s
website and the merchant in return will send Delete Token request to Payment Gateway
in order the unsave the card details
2.5.2 Retreive Token

In case if the customer has requested to save the card details, and token is generated
against his request, Retreive Token API can be used to fetch the card details against the
generated token.

Merchant Setup Process

In order to process online payments using the Payment Gateway, the merchant needs to be
registered with the Payment Gateway as member merchant.
The below process assumes that the merchant has been registered and all the parameters
related to merchant have been configured in the Payment Gateway system.
There are 2 ways of registering merchant at Payment Gateway:

 Scheme’s backoffice user will create merchant profile using backoffice portal
 Merchant will register itself using Merchant On-Boarding Portal
1. Once merchant has registered for Payment Gateway services, the merchant will be
provided with Payment Gateway Integration Guide for Merchants and Merchant Portal
User Guide documents. These documents will assist in integrating with the Payment
Gateway Payment Portal and elaborate the administration support processes. The
integration documents contain the following:
a. Payment Gateway Payment Portal Integration Guide

b. Sample code for integration
2. At the time of merchant registration with the Payment Gateway, a merchant code will be
assigned to each merchant. In addition Payment Gateway will generate two more codes:
a. Password
It is the password needed to do the transaction by merchant
b. Integrity Salt
It is used to calculate hash
These values are emailed to the registered email address of the merchant after
registration, by scheme backoffice user. The merchant may request to re-generate the
codes by communicating with the Payment Gateway service provider.
3. After getting the basic information, the merchant will be in a position to perform test
transactions using the password and integrity salt. Once the sample transaction has been
successfully processed, it indicates that all the required systems have been configured
correctly and the merchant is ready to go live.
4. If the merchant has been on-boarded using Merchant On-boarding Portal, then it can
perform transaction testing on Sandbox Portal. If the registration process is done by the
scheme user using backoffice portal, then testing will done on testbed server.
5. Finally after the transaction testing has been successfully done, merchant can move its
system into production. It is to be noted that merchant will need to inform the service
provider before merchant will be able to accept transaction in the production
environment.

Payment Gateway Test System

Beside the Sandbox testing portal for on-boarded merchants, Payment Gateway also provides
an independent testing system on testbed which has the same infrastructure as production.
This testing facility caters for all the merchant integration features.
The merchant is provided with IP addresses to connect with the test and production systems
as required.
As mentioned earlier the test environment is a complete system and provides all the options.
The transactions are recorded in the system and the merchant can access the reports and
other administration options via the Test Merchant Portal.
In case of testing, the transactions are triggered by a simulator and the response from
Payment Gateway will also be rendered on the simulator. The complete list of response codes
can be found in Appendix I .
As test transactions are fully recorded, Merchants can test PG’s Payment Status Inquiry
service using either APIs or simulator’s Generic Inquiry option. In case of Direct Debit, PG hits
Bank’s service for inquiry. If bank is not available for testing, PG will respond with the relevant
response message.
PG test system will also provide Update Payment Status service for testing. For this purpose,
merchant can either use Payment Gateway APIs or simulator’s Generic Update option.
Once the testing has been completed, the merchant can move the testing application into
production. Please note that the merchant will be required to configure the integration
options with Payment Gateway so that the merchant’s website gets connected with the
Payment Gateway Production system.
Further, the merchant cannot perform live transactions unless it is configured in Payment
Gateway production system.

Payment Integration via Payment Portal

This section describes in detail how to integrate the merchant’s e-commerce website with the
PG Payment Portal using Page Redirection Mode.
Merchant will provide the input parameters using an HTTP POST request to the PG Payment
Portal. The PG Payment Portal will process the transaction and return the response via an
HTTP POST request to the return URL provided by the merchant. The merchant may use the
response to show the transaction results (success or failure) of the transaction to the
customer.
To receive the transaction response, merchant must specify a return URL. This address is also
where the customer is returned to when they have completed the purchase. The
pp_ReturnURL field must contain a valid URL (starting with “https://” or “https ://”), otherwise
an error is generated which will stop the transaction from further processing. The
pp_ReturnURL field is validated against this provided URL in request. If the values do not
match, transaction is rejected.
The PG Payment Portal will receive an HTTP POST request from the merchant website which
will contain the merchant authentication details along with the transaction details. The
Payment Gateway will inquire the required details from the customer, validate and process
transaction. The form will be containing the input parameters as hidden fields such as:
<input type="hidden" id="pp_Version" value="1.0">

<input type="hidden" id="pp_TxnType" value="PAY">
<input type="hidden" id="pp_MerchantID" value=" MERC001">
<input type="hidden" id="pp_TxnRefNo" value="TXN1234">
<input type="hidden" id="pp_Amount" value="10000">
<input type="hidden" id="pp_TxnDateTime" value="20110909124545">
….
The parameter names and details of each parameter are described below:
5.1 Version 1.1

This version is used to perform basic payments. Card tokenization functionality is not present in this
version
5.1.1 Request
Parameter Max. Length Mandatory Sample Values Remarks
Payment Portal Version.

pp_Version 4 AN Yes 1.1
Fixed value ‘1.1’
Presents the transaction type:
pp_TxnType 10 AN No PAY Internet Banking = DD
Mobile Wallet = MWALLET

Debit/Credit Card = MIGS

Over The Counter = OTC
Specifies the language in which to
display the page.
pp_Language 3A Yes EN
Fixed value ‘EN’.
Unique Code assigned to each
pp_MerchantID 10 AN Yes MERC001
Merchant by PG.
If the merchant is handling any child
merchants at its end, then the child
pp_SubMerchan merchant Id will be provided. The
10 AN No SUBMER001
tID Transaction reports will be grouped on
the basis of Sub Merchant Id, if
available.
Password is the Password assigned to
each merchant and is used to
pp_Password 10 AN Yes 75019F19EA authenticate merchant at the time of
payment. This is a system generated
value.
This field will only be used in case of DD
transaction type, otherwise it should be
pp_BankID 4AN No BNK01
sent as an empty field.
Bank Id of the customer’s bank
Product of Bank through which
pp_ProductID 4A No RETL
payment will be done. For e.g. Retail,
Corporate.
Fixed values: ‘RETL’, ‘CORP’

20 AN & ‘/’ A unique value created by the
pp_TxnRefNo Yes Tx2011090901
& ‘.’ merchant to identify the transaction.
The transaction amount.
100.00 will be
Please note that no decimal places are
pp_Amount 13 N Yes passed as
included. Decimal place will be
10000
assumed at the default position of the
currency provided.
The discounted amount merchant
wants to send.
100.00 will be
pp_DiscountedA
13 N No passed as Please note that no decimal places are
mount
10000 included. Decimal place will be
currency provided.
pp_DiscountBan BankID of the bank for which merchant
4AN No SCB
k wish to send discount.
Currency of Transaction amount. It has
pp_TxnCurrency 3A Yes PKR
a fixed value ‘PKR’.

9th Oct, 2011

10:35:47 PM Merchant provided date and time of
pp_TxnDateTim
14 N Yes will be sent as transaction. The format of date time
e
‘201110092235 should be yyyyMMddHHmmss.
47’
pp_BillReferenc
20 AN & ‘.’ Yes Cart001
e Bill/invoice Number being settled.
Transaction details to be shown on
screen as desired by the merchant. This
field will be parsed to identify any
200 Free Payment for 3 malicious data entered by the end user.
pp_Description Yes
Text Field Item(s) bought In cases when any of these characters
<>\*=%/:'"{} are inserted, they will be
replaced with a space.Pipe ‘|’ is not
allowed
Transaction Expiry can be specified by
9th Oct, 2011
merchant to indicate to the issuing
10:35:47 PM
pp_TxnExpiryDa bank that the transaction must be
14 N No will be sent as
teTime approved within this period. Please
‘201110092235
note that the default and maximum
47’
value of this expiry is 3 months.
The URL where merchant wants the
transaction results to be shown. Once
Merchant
the transaction has been processed,
pp_ReturnURL 200 AN Yes site/payment/R
response details will be sent over to the
esults.aspx
merchant on this URL using an HTTP
POST Request.
9e107d9d372bb
6826bd81d3542 Used to allow the Payment Gateway to
pp_SecureHash 64 AN No a419d69e107d9 check the integrity of the transaction
d372bb6826bd8 request.
1d3542a419d6
Merchant Optional Fields
255 AN and xxxx will be replaced by any value from

ppmpf_xxxx ~!@#$%^&* No 1 to 5. Merchant can send additional
()_+}{“:?>< information to PG in this field. These
will be returned to Merchant in
transaction response.
Bank Optional Fields
xxxx will be replaced by any value from

1 to 5. Merchant may send some
additional information to Member
Bank.
ppmbf_xxxx 255 AN No
If received, PG will forward the
information contained in this field to
bank.
*Only used in case of DD

5.1.2 Response
Sample
Parameter Max. Length Mandatory Remarks
Values
pp_Version 4 AN Yes 1.1 As provided in the request.
pp_TxnType 10 AN No PAY As provided in the request.
pp_IsRegisteredCust
3A Yes Yes/No As provided in the request.
omer
pp_Language 3A Yes EN As provided in the request.
Unique code assigned to each
Merchant by PG.
pp_SubMerchantId 10 AN No SUBMER001 As provided in the request.
20 AN & ‘/’ & Tx201109090
pp_TxnRefNo Yes As provided in the request.
‘.’ 1
If merchant wish to use discount
100.00 will be module than final amount will be
pp_Amount 13 N Yes passed as respond back which payaxis considers,
10000 else same amount will be responded
as in the request.
pp_TxnCurrency 3A Yes PKR As provided in the request.
9th Sept, 2011
10:35:47 PM
will be sent
pp_TxnDateTime 14 N Yes As provided in the request.
as
‘2011090920
3547’
pp_BillReference 20 AN & ‘.’ Yes Cart001 As provided in the request.
This field represents the customer
card expiry against tokenized card.
pp_CustomerCardEx Example :
4N Yes 0220
piry
0220 = Feburay 2020
Response code representing the

transaction success or failure. A
pp_ResponseCode 3 AN Yes 000 response code of 000 represents
success. For a complete list of
response codes refer to Appendix I.
Error details in case the transaction
Not enough
failed to be processed.
pp_ResponseMessag balance to
200 AN No This field will be mandatory for all
e perform
cases where response code is not
transaction
equal to 000.
A unique number generated by the
Payment Gateway when the
pp_RetreivalReferen 00011223344
12 N No transaction got processed. The
ceNo 5
number should be stored and used for
future reference.

The number is unique for any given

date.
An identifying code issued by the

issuing bank to approve or deny the
transaction.
pp_AuthCode 12 N No 123456 The field is mandatory in case of

successful response code. Refer to
Appendix I for a list of response codes
and the codes which when sent will
require Auth Code.
A date supplied by the Payment
Gateway indicating that if the
merchant does not send a
9th Oct, 2011
Confirmation of the transaction by this
10:35:47 PM
time, the PG will mark the transaction
will be sent
pp_SettlementExpiry 14N No as expired and the Merchant will not
as
be able to resume it.
‘2011100922
3547’
The field is mandatory in case of
successful response code and when
the AuthCode is not blank.
Customer’s bank that authorized the

pp_BankID 4 AN Yes BNK1
transaction.
This field will only be used in case of

DD transaction type.
payment has been performed. For e.g.
Retail, Corporate.
pp_ProductID 4A No RETL Fixed values: ‘RETL’, ‘CORP’
In case value was provided at the time

of request, this field will contain the
same value. Otherwise, ID of the
product chosen by customer at PG will
be filled.
9e107d9d372
bb6826bd81d
Used to allow the Merchant to check
3542a419d69
pp_SecureHash 64 AN No the integrity of the transaction
e107d9d372b
response.
b6826bd81d3
542a419d6

1 to 5. Merchant can send additional
ppmpf_xxxx 255 AN No
information to PG in these fields while
making the payment request. If
received, the fields will be echoed
back at the time of response.


1 to 5. Member Bank may send some
ppmbf_xxxx 255 AN No additional information to Merchant.
If received from Member Bank, PG will

forward the information contained in
this field to Merchant.
5.2 Version 2.0
5.2.1 Request
This verison is used to support payment using token instead of card details. In this approach,
token will be shared with merchant through token notification service
Sample
Parameter Max. Length Mandatory Remarks
Values
API Version
Fixed value ‘2.0’ should be used
Internet Banking = DD
pp_TxnType 10 AN No PAY Mobile Wallet = MWALLET
Credit/Debit Card = MIGS
display the page.
It represents that the request has been
pp_IsRegisteredC
3A Yes Yes made by the registered or a guest
ustomer
customer of a merchant.
It represents the tokenized card
number of returning customer.
pp_TokenizedCar 9113633378
16 N No This token will be received to the
dNumber 227378
merchant in response of save card
details when selected by the customer
on Payment portal.
Merchant by PG.
pp_SubMerchantI merchant Id will be provided. The
10 AN No SUBMER001
D Transaction reports will be grouped on
the basis of Sub Merchant Id, if
available.

Password assigned to each merchant

and is used to authenticate merchant
pp_Password 10 AN Yes 75019F19EA
at the time of payment. This is a
system generated value.
DD transaction type, otherwise it
should be sent as an empty field.
Bank Id of the customer’s banks
payment will be done. For e.g. Retail,
Corporate.

20 AN & ‘/’ & Tx20110909 A unique value created by the
pp_TxnRefNo Yes
‘.’ 01 merchant to identify the transaction.
100.00 will
pp_Amount 13 N Yes be passed as
included. Decimal place will be
10000
currency provided.
The discounted amount merchant
wants to send.
100.00 will
pp_DiscountedA
13 N No be passed as Please note that no decimal places are
mount
10000 included. Decimal place will be
currency provided.
BankID of the bank for which
pp_DiscountBank 4AN No SCB
merchant wish to send discount.
Currency of Transaction amount. It has
a fixed value ‘PKR’.
9th Oct, 2011
10:35:47 PM
Merchant provided date and time of
will be sent
pp_TxnDateTime 14 N Yes transaction. The format of date time
as
should be yyyyMMddHHmmss.
‘2011100922
3547’
pp_BillReference 20 AN & ‘.’ Yes Cart001
Bill/invoice Number being settled.
screen as desired by the merchant.
This field will be parsed to identify any
Payment for
200 Free Text malicious data entered by the end
pp_Description Yes 3 Item(s)
Field user. In cases when any of these
bought
characters <>\*=%/:'"{} are inserted,
they will be replaced with a space.Pipe
‘|’ is not allowed

9th Oct, 2011 Transaction Expiry can be specified by

10:35:47 PM merchant to indicate to the issuing
pp_TxnExpiryDat will be sent bank that the transaction must be
14 N No
eTime as approved within this period. Please
‘2011100922 note that the default and maximum
3547’ value of this expiry is 3 months.
The URL where merchant wants the
Merchant transaction results to be shown. Once
site/paymen the transaction has been processed,
pp_ReturnURL 200 AN Yes
t/Results.asp response details will be sent over to
x the merchant on this URL using an
HTTP POST Request.
9e107d9d37
2bb6826bd8
1d3542a419 Used to allow the Payment Gateway to
pp_SecureHash 64 AN No d69e107d9d check the integrity of the transaction
372bb6826b request.
d81d3542a4
19d6
Registered Customer’s LoginID or
(Provided by
pp_CustomerID 255 AN No Identifier address provided by
Merchant)
Merchant.
255 AN and
pp_CustomerEma sample@gm Registered Customer’s Email address
!#$%&'*+- No
il ail.com provided by Merchant.
/=?^_`{|}~
pp_CustomerMo 0300123789 Regsitered Customer’s Mobile

11 N No
bile 6 Number provided by Merchant.

255 AN and
1 to 5. Merchant can send additional
ppmpf_xxxx ~!@#$%^&*() No
information to PG in this field. These
_+}{“:?><
will be returned to Merchant in
transaction response.

1 to 5. Merchant may send some
additional information to Member
ppmbf_xxxx 255 AN No Bank.
If received, PG will forward the

information contained in this field to
bank.
*Only used in case of DD
5.2.2 Response
This verison is used to support payment with tokenization. In this approach token will be
shared with merchant through token generation notification (ITN).

Max.
Parameter Mandatory Sample Values Remarks
Length
pp_Version 4 AN Yes 1.1 As provided in the request.
pp_TxnType 10 AN No PAY As provided in the request.
pp_IsregisteredCust
3A Yes Yes/No As provided in the request.
omer
pp_Language 3A Yes EN As provided in the request.
Unique code assigned to each Merchant by
PG.
pp_SubMerchantId 10 AN No SUBMER001 As provided in the request.
20 AN & ‘/’
pp_TxnRefNo Yes Tx2011090901 As provided in the request.
& ‘.’
If merchant wish to use discount module
100.00 will be than final amount will be respond back
pp_Amount 13 N Yes passed as which payaxis considers, else same
10000 amount will be responded as in the
request.
pp_TxnCurrency 3A Yes PKR As provided in the request.
9th Sept, 2011
10:35:47 PM
pp_TxnDateTime 14 N Yes will be sent as As provided in the request.
‘20110909203
547’
pp_BillReference 20 AN & ‘.’ Yes Cart001 As provided in the request.
transaction success or failure. A response
pp_ResponseCode 3 AN Yes 000 code of 000 represents success. For a
complete list of response codes refer to
Appendix I.
There are two types of tokenized card
number in reponse.
1) The same Tokenized card number as

pp_TokenizedCard 911363337822
16 N No received in request for returning customer
Number 7378
2)When customer selects save card option
on Payment Portal Screen then PG returns
a new tokenized card number in this field
After save card details merchant will
provide 3 digits response code to inform
the status of tokenization.
pp_TokenizationRe
3 AN No T00
sponseCode
This field will be helpful for merchant to
manage tokenized card against register
customers.

After save card details merchant will

provide a response message with
The respective to the
tokenization pp_TokenizationResponseCode field as
pp_TokenizationRe
300 A No operation was define above.
sponseMsg
successfully
processed This field will be mandatory for all cases
where pp_TokenizationResponseCode is
not equal to T00.
This field represents the masked card
pp_CustomerCardN 512345******
16 N No number of the customer against tokenized
o 2346
card.
This field represents the customer card
pp_CustomerCardE expiry against tokenized card. Example :
4N Yes 0220
xpiry
0220 = Feburay 2020
Not enough Error details in case the transaction failed
pp_ResponseMessa balance to to be processed.
200 AN No
ge perform This field will be mandatory for all cases
transaction where response code is not equal to 000.
Payment Gateway when the transaction
pp_RetreivalRefere
12 N No 000112233445 got processed. The number should be
nceNo
stored and used for future reference.
The number is unique for any given date.
An identifying code issued by the issuing
bank to approve or deny the transaction.
pp_AuthCode 12 N No 123456 The field is mandatory in case of successful

response code. Refer to Appendix I for a
list of response codes and the codes which
when sent will require Auth Code.
A date supplied by the Payment Gateway
indicating that if the merchant does not
send a Confirmation of the transaction by
9th Oct, 2011
this time, the PG will mark the transaction
10:35:47 PM
pp_SettlementExpir as expired and the Merchant will not be
14N No will be sent as
y able to resume it.
‘20111009223
547’
The field is mandatory in case of successful
response code and when the AuthCode is
not blank.

pp_BankID 4 AN Yes BNK1
transaction.

transaction type.
Product of Bank through which payment
has been performed. For e.g. Retail,
Corporate.

In case value was provided at the time of

request, this field will contain the same
value. Otherwise, ID of the product chosen
by customer at PG will be filled.
9e107d9d372b
b6826bd81d35
42a419d69e10 Used to allow the Merchant to check the
pp_SecureHash 64 AN No
7d9d372bb682 integrity of the transaction response.
6bd81d3542a4
19d6
(Provided by
pp_CustomerID 255 AN No As provided in the request.
Merchant)
255 AN and
sample@gmail
pp_CustomerEmail !#$%&'*+- No As provided in the request.
.com
/=?^_`{|}~
pp_CustomerMobil
11 N No 03001237896 As provided in the request
e
Optional Fields
xxxx can be replaced by any value from 1

to 5. Merchant can send additional
ppmpf_xxxx 255 AN No
information to PG in these fields while
making the payment request. If received,
the fields will be echoed back at the time
of response.
Optional Fields
xxxx can be replaced by any value from 1

to 5. Member Bank may send some
additional information to Merchant.
ppmbf_xxxx 255 AN No
If received from Member Bank, PG will
forward the information contained in this
field to Merchant.

Payment Integration Via SOAP APIs
6.1 Mwallet & OTC

For merchants who want to enable payment through Payment Gateway, are required to consume
payment APIs. This section describes in detail how to integrate the merchant e-commerce website
with the PG Payment APIs.
Merchant will provide the authentication details along with the transaction details using SOAP request
to the PG Payment API. The PG Payment API will validate & process transaction and return the
response via SOAP message. The merchant may use the response to show the transaction results
(success or failure) of the transaction to the customer.
To integrate with Payment Gateway through SOAP API, a wsdl file will be shared to merchant.
Merchant will use the provided WSDL and access below URL to consume this API on merchant
website. Sample xml request is provided in the end of this section
URL: https://<baseurl>/ExternalStatusService/StatusService_v11.svc?wsdl
public string DoPaymentViaAPI(string pp_Version, string pp_TxnType, string pp_Language, string

pp_MerchantID, string pp_SubMerchantID, string pp_Password, string pp_BankID, string
pp_ProductID,string pp_TxnRefNo, string pp_Amount, string pp_TxnCurrency, string pp_TxnDateTime,
string pp_BillReference, string pp_Description, string pp_TxnExpiryDateTime, string pp_ReturnURL, string
pp_SecureHash, string ppmpf_1, string ppmpf_2, string ppmpf_3, string ppmpf_4,string ppmpf_5 )
6.1.1 Request
The request will be containing the input parameters as XML fields as:
Max.
Length

pp_TxnType 10 AN Yes OTC or MWALLET Over The Counter = OTC,
Mobile Account = MWALLET
Specifies the language in which to display
the page.
Unique code assigned to each Merchant by
PG.
pp_SubMerchan
10 AN No SUBMER001 merchant Id will be provided. The
tID
Transaction reports will be grouped on the
basis of Sub Merchant Id, if available.

Password assigned to each merchant and is

pp_Password 10 AN Yes 75019F19EA used to authenticate merchant at the time
of payment. It is a system generated value.

pp_BankID 4AN No BNK01 sent as an empty field.
Bank Id of the customer’s banks if
available.
pp_ProductID 4A No RETL Product of Bank through which payment
will be done. For e.g. Retail, Corporate.

20 AN & A unique value created by the merchant to
‘/’ & ‘.’ identify the transaction.
100.00 will be
included. Decimal place will be assumed at
10000
the default position of the currency
provided.
Currency of Transaction amount. It has a
fixed value ‘PKR’.
9th Oct, 2011
pp_TxnDateTim 10:35:47 PM will be
14 N Yes transaction. The format of date time
e sent as
‘20111009223547’
pp_BillReferenc 20 AN &
Yes Cart001
e ‘.’ Bill/invoice Number being settled.
Transaction details to be shown on screen
as desired by the merchant. This field will
be parsed to identify any malicious data
200 Free Payment for 3
pp_Description Yes entered by the end user. In cases when any
Text Field Item(s) bought
of these characters <>\*=%/:'"{} are
inserted, they will be replaced with a
space. Pipe ‘|’ is not allowed
9th Oct, 2011 merchant to indicate to the issuing bank
pp_TxnExpiryDa 10:35:47 PM will be that the transaction must be approved
14 N Yes
teTime sent as within this period. Please note that the
‘20111009223547’ default and maximum value of this expiry is
3 months.
This field is mandatory and merchant must
share this URL before using API as it will be
Merchant a part of merchant profile.URL should
pp_ReturnURL 200 AN Yes site/payment/Resu always be the same in every request once
lts.aspx shared. It is a part of merchant
authentication, difference of URL will fail
the validation.

9e107d9d372bb68
26bd81d3542a419 Used to allow the Payment Gateway to
pp_SecureHash 64 AN No d69e107d9d372bb check the integrity of the transaction
6826bd81d3542a4 request.
19d6
Mobile Number Field
ppmpf_1 255 AN Yes 03211234567
100.00 will be
Discounted Amount (Final amount after
ppmpf_2 255 AN No passed as
discount)
10000
ppmpf_3 255 AN No SCB Discount bank
ppmpf_4 255 AN No Optional Fields
Merchant can send additional information

to PG in this field. These will be returned to
ppmpf_5 255 AN No Merchant in transaction response.
6.1.2 Response
The response by Payment Gateway Payment API will be sent to the merchant’s website so that the
merchant can perform the required operations accordingly.
SOAP response will be sent to merchant in an alphabetical order separated by pipe ‘|’. Merchant
needs to parse the response and show the transaction results to user on any screen accordingly.
Response parameter details with sequence number is as follows.
Max.
Parameter Mandatory Sequence Sample Values Remarks
Length
pp_Version 4 AN Yes 17 1.1 As provided in the request.
pp_TxnType 10 AN No 16 PAY As provided in the request.
pp_Language 3A Yes 5 EN As provided in the request.
Unique Code assigned to each
pp_MerchantID 10 AN Yes 6 MERC001
Merchant by PG.
pp_SubMerchantI
10 AN No 12 SUBMER001 As provided in the request.
d
20 AN &
pp_TxnRefNo Yes 15 Tx2011090901 As provided in the request.
‘/’ & ‘.’
If merchant wish to use
discount module then final
100.00 will be amount will be respond back
pp_Amount 13 N Yes 1
passed as 10000 which payaxis considers, else
same amount will be responded
as in the request.
pp_TxnCurrency 3A Yes 13 PKR As provided in the request.

9th Sept, 2011

10:35:47 PM will
pp_TxnDateTime 14 N Yes 14 be sent as As provided in the request.
‘2011090920354
7’
20 AN &
pp_BillReference Yes 4 Cart001 As provided in the request.
‘.’
Response code representing
the transaction success or
failure. A response code of 000
pp_ResponseCod
3 AN Yes 7 000 for mwallet and 124 for OTC
e
represents success. For a
complete list of response codes
refer to Appendix I.
Error details in case the
Not enough transaction failed to be
pp_ResponseMes balance to processed.
200 AN No 8
sage perform This field will be mandatory for
transaction all cases where response code is
not equal to 000.
A unique number generated by
the Payment Gateway at the
time of transaction processing.
pp_RetreivalRefe
12 N Yes 9 000112233445 The number should be stored
renceNo
and used for future reference.
The number is unique for any
given date.
An identifying code issued by
the issuing bank to approve or
deny the transaction.

pp_AuthCode 12 N No 2 123456
successful response code. Refer
to Appendix I for a list of
response codes and the codes
which when sent will require
Auth Code.
Confirmation of the transaction
9th Oct, 2011 by this time, the PG will mark
10:35:47 PM will the transaction as expired and
pp_SettlementEx
14N No 11 be sent as the Merchant will not be able to
piry
‘2011100922354 resume it.
7’
successful response code and
when the AuthCode is not
blank.
Customer’s bank that

pp_BankID 4 AN Yes 3 BNK1
authorized the transaction.

9e107d9d372bb
6826bd81d3542 Used to allow the Merchant to
pp_SecureHash 64 AN No 10 a419d69e107d9 check the integrity of the
d372bb6826bd8 transaction response.
1d3542a419d6
Mobile Number Field

ppmpf_1 255 AN Yes 23 03211234567
Format : xxxxxxxxxxx
ppmpf_2 255 AN No 24
Optional Field
Merchant can send additional information to PG in
this field while making the payment request. If
ppmpf_4 255 AN No 26 received, the fields will be echoed back at the time
of response.
xxxx in the name for Optional fields can be replaced

by any set of characters from 1 to 5.
ppmbf_xxxx 255 AN No 18 Merchant may send some additional information to

Member Bank.
If received, PG will forward the information

contained in this field to bank.
6.1.3 Sample
6.1.3.1 Request
<soapenv:Envelope xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
xmlns:tem="https://tempuri.org/">
<soapenv:Header/>
<soapenv:Body>
<tem:DoPaymentViaAPI>
<tem:pp_Version>1.1</tem:pp_Version>
<tem:pp_TxnType>OTC</tem:pp_TxnType>
<tem:pp_Language>EN</tem:pp_Language>
<tem:pp_MerchantID>TestMerc0003</tem:pp_MerchantID>
<tem:pp_SubMerchantID/>
<tem:pp_Password>0123456789</tem:pp_Password>
<tem:pp_BankID/>
<tem:pp_ProductID/>
<tem:pp_TxnRefNo>TR160825173822</tem:pp_TxnRefNo>

<tem:pp_Amount>10000</tem:pp_Amount>
<tem:pp_TxnCurrency>PKR</tem:pp_TxnCurrency>
<tem:pp_TxnDateTime>20160825174445</tem:pp_TxnDateTime>
<tem:pp_BillReference>0123456</tem:pp_BillReference>
<tem:pp_Description>Product</tem:pp_Description>
<tem:pp_TxnExpiryDateTime>20160830113600</tem:pp_TxnExpiryDateTime>
<tem:pp_ReturnURL>https://<baseurl>/MerchantSimulator/HttpRequestDemoServer/Index</tem:p
p_ReturnURL>
<tem:pp_SecureHash>5212E6DC8A73E6335663476E9A52CEF9950811815529E8C2F44F7125D0B3E3
E2</tem:pp_SecureHash>
<tem:ppmpf_1>03312456985</tem:ppmpf_1>
</tem:DoPaymentViaAPI>
</soapenv:Body>
</soapenv:Envelope>
6.1.3.2 Response
SOAP sample response in an alphabetical order separated by pipe ‘|’.Parse the data according to the
response sequence guid provided above.
Response![10000|||0123456|EN|MERC0003|124|Order is placed and waiting for financials to be

received over the
counter.|160825002328|4551BFAF3332B2A7712CD4EFFD36396E5CC8B4ED9A3C2CAFA7324C1FD9
C8E769|||PKR|20160825174445|TR160825173822|OTC|1.1||||||03312456985]
Note : Consider the value empty between two PIPs’|’ if no value is present. eg : 10000|||0123456
6.2 Payment Status

Inquiry
The Payment Status Inquiry service allows merchant to check the status of any transaction, it has
performed through the Payment Gateway. The inquiry will in turn respond with the transaction
status (success or failure or pending) along with response message and some other fields. Following
are few possible scenarios:
 On receiving the request from Merchant, Payment Gateway will check whether it has the
transaction in pending state or not.
 If the transaction is NOT in pending state, that is, the transaction is either in Success/Approved
or Failed/Denied/Expired stage, the same response will be sent to Merchant. In case of
Approved transaction, Settlement Expiry will be sent as well. Note that the Settlement Expiry
is calculated at the time the approval of transaction was received from the bank and not when
the inquiry request was received.

 In case of Pending transaction, PG will proceed to inquire the status of the transaction from
the external system.
 If inquiry is initiated after Settlement Expiry or Transaction Expiry has elapsed, a response code
indicating the same would be sent to Merchant.
 Merchant may not receive the response to a Status Inquiry call. This can happen when the
response is lost due to network problems. In this case, Merchant will need to send the inquiry
again to get the status.
The signature of Payment Status Inquiry Web Service which the merchant may call to fetch
transaction status is:
URL: https://<baseurl>/ExternalStatusService/StatusService_v11.svc?wsdl
Public string DoPaymentStatusInquiryNew(string pp_Version, string pp_TxnType, string

pp_MerchantId, string pp_Password, string pp_TxnRefNo, string pp_TxnDateTime, string
pp_SecureHash)
6.2.1 Request
Max.
Length
API Version
pp_TxnType 10 AN No PAY
pp_Merchant Unique code assigned to each Merchant
10 AN Yes MERC001
ID by PG.
Password assigned to each merchant and
is used to authenticate merchant at the
time of payment. Password is a system
generated value.
20 AN & As provided in the transaction processing

‘/’ & ‘.’ request.
9th Sept, 2011

10:35:47 PM will be The transaction date time that was
pp_TxnDateTi
14 N Yes sent as provided at the time of transaction
me
‘20110909203547’ execution.
9e107d9d372bb6826 Used to allow the Payment Gateway to

pp_SecureHa
64 AN No bd81107d9d372bb68 check the integrity of the transaction
sh
26bd81d3542a419d6 response.

6.2.2 Response
In response to the above stated function call, the Payment Status Inquiry will respond with a string
which will contain the response code, followed by other transaction authorization related fields as
provided in the Payment Portal Transaction Processing response. Also, the response sent will be
fixed length and white spaces will be padded with the ASCII:32 if parameter is left as empty
Max.
Length
First three characters of the string
Response Code 3 AN Yes 000 denoting the response code. For list of
response codes see Appendix I.
The Response Message field shows
message corresponding to the response
code. It is concatenated with the
response code. In case Response code is
Response Message 200 AN No Low Balance
‘000’ i.e. Success, this field will be all
spaces.
This field will be mandatory for all cases
where response code is not equal to 000.
Payment Gateway at the time of
transaction processing. The number
Retrieval
12 N Yes 000112233445 should be stored and used for future
Reference No
reference.

to indicate when this transaction will be
settled.
For 9th Sept, When the Payment Gateway closes the

Settlement Date 8N No 2011 value will be batch at the end of the day, the date will
20110909 roll over to the next processing day’s
date.
This date will only be provided in case a
transaction is already confirmed by the
merchant.

Auth Code 12 N No 123456987456
Appendix I for a list of response codes
and the codes which when sent will
require Auth Code.
9th Oct, 2011
10:35:47 PM will
Settlement Expiry 14N No be sent as
this time, the PG will mark the transaction
‘20111009223547
as expired and the Merchant will not be
’
able to resume it.

This field will be mandatory where Auth

Code is available.
BankID 4 AN No BNK1 sent as an empty field.
transaction.
transaction type.
Product of Bank through which payment
has been performed. For e.g. Retail,
Corporate.
ProductID 4A No RETL

request, this field will contain the same
value. Otherwise, ID of the product
chosen by customer at PG will be filled.
As provided in the transaction cycle.
98715632400012
CustomerCardNo 20 N No This field will only be sent if the
3654789
transaction type is MIGS.
9e107d9d372bb6
Used to allow the Merchant to check the
Secure Hash 64 AN No 82607d9d372bb6
integrity of the transaction request.
826bd81d3542a
6.3 Delivery Status

Update
After a transaction has completed its span at Merchant’s end, Merchant will need to send a
confirmation to Payment Gateway. This confirmation message should be sent in the following
scenarios:
1. Transaction has completed successfully and delivery has been made to the customer.
2. Goods or service could not be delivered to the customer for any reason.
In case a confirmation message of successful transaction is received by PG, the transaction will be
marked completed and settlement of the same transaction will be done at PG’s end.
In case confirmation message of reversal transaction is received by PG, the transaction will be
marked ‘Awaiting Reversal’ and reversal for the same transaction will be initiated to the bank. PG
will then send a reversal transaction to bank. On receiving success response from bank the
transaction’s status will be updated to ‘Reversed’.
The signature of Delivery status update web service which the Merchant will call to confirm
transaction’s completion is:
public string DoUpdateDeliveryStatus(string pp_Version, string pp_TxnType, string

pp_DeliveryStatus, string pp_MerchantId, string pp_Password, string pp_TxnRefNo, string
pp_TxnDateTime, string pp_SecureHash)

6.3.1 Request
Parameter Length Mandatory Sample Values Remarks

pp_TxnType 10 AN No PAY Mobile Wallet = MWALLET
Debit/Credit Card = MIGS
Possible values:
pp_DeliveryStat ‘CFM’: to indicate confirmation,
3 AN Yes CFM
us ‘REV’: to indicate reversal and void
Code of Merchant initiating the request

pp_MerchantID 10AN No MERC001
and which initiated the transaction

pp_Password 10 AN Yes 75019F19EA will be used by the PG to identify if the
transaction is from a valid merchant.

‘/’ & ‘.’ request.
9th Sept, 2011

The transaction date time that was
14 N Yes provided at the time of transaction
e sent as
execution
‘20110909203547’
9e107d9d372bb6826
Used to allow the Payment Gateway to
bd81d3542a419d69e
pp_SecureHash 64 AN No check the integrity of the transaction
107d9d372bb6826bd
request.
81d3542a419d6
6.3.2 Response
In response to the above stated function call, Payment Gateway will respond with a string which will
contain the response code and error message if any.

First three characters of the string
denoting the response code. This
response indicates the success or failure
Response Code 3 AN Yes 000
of delivery status update request sent by
the merchant rather than the status of
the actual transaction.

For list of response codes see Appendix

I.
The Response Message field shows
message corresponding to the response
code. It is concatenated with the
Transaction response code. In case Response code is
Response Message 200 AN No
Expired ‘000’ i.e. Success, this field will be all
spaces.
Gateway to indicate when this
transaction will be settled.
For 9th Sept, When the Payment Gateway closes the

Settlement Date 8N No 2011 value will batch at the end of the day, the date will
be 20110909 roll over to the next processing day’s
date.
This date will only be provided in
response to a transaction confirmation
by the merchant.
9e107d9d372b
b6826bd81d35
Secure Hash 64 AN No 42a419d69e10
integrity of the response.
7d9d372bb682
6bd81d3542a4
6.3.3 Processing Details

Merchants will use the Status Update web service to provide the updated status of the
transactions to PG. Merchant will be using Status Update Service in following scenarios
o To provide the confirmation of approved transactions to PG.
o To reverse the transaction after receiving an approval from PG.
o To void the transaction which is in Pending state.
6.3.3.1 Confirmation Of Approved Transactions

o On receiving an approval of pending transaction from Payment Gateway, Merchant will
process and update the status of transaction at its end and once successfully done, will
provide the confirmation to Payment Gateway.
o PG will entertain the confirmation message only for those transactions which are already
Approved and the confirmation is received within Settlement Expiry period.
o On receiving confirmation from Merchant, Payment Gateway will mark the transaction as
’Confirmed’
6.3.3.2 Reversal of Pending Transaction

o If for any reason, Merchant is not able to complete a transaction within Settlement expiry
span, merchant may send a request to reverse the transaction. PG will entertain this

message only for transactions that are already approved and lie within the settlement
expiry.
o After checking the status of transaction, PG will mark the transaction as Reversed in its
database and will update accordingly.
6.3.3.3 Request to VOID Pending Transaction

o If merchant would like to VOID the transaction which is in “Pending State” and lie within
the transaction expiry, merchant may send a request to VOID the transaction to PG.
o After checking the status of transaction, PG will mark the transaction as VOID in its
database and will update accordingly.
For reference, consider the below table which indicates the response that will be sent to Merchant
in case the transaction is in the mentioned status:
Transaction Status Response Returned

Awaiting Reversal Delivery Status cannot be updated
Reversal Delivery Status cannot be updated
Awaiting Void Delivery Status cannot be updated
Void Delivery Status cannot be updated
Success Respective code
Failed Delivery Status cannot be updated
Pending Successful (000) in case of REV, Delivery
Status cannot be updated in case of CFM
Confirmed Delivery Status cannot be updated
Expired Delivery Status cannot be updated
Approved Successful (000) in case of CFM, Delivery
Status cannot be updated in case of REV

Payment Integration Via REST APIs

For merchants who want to enable payment processing of debit/ credit card through Payment
Gateway’s API, are required to integrate with PG payment REST based APIs. The PG payment
portal will process the transaction and return the response which merchant may use to show
the transaction results (success or failure) of the transaction to the customer. This section
describes in detail how to integrate the merchant e-commerce website with the PG Payment
API to perform card payments.
Merchant may integrate with different transactions using API’s provided below:
1. Credit/Debit Card
a. Check 3DS Enrollment
b. Process ACS
c. Auth
d. Void
e. Capture
f. Pay
g. Refund
2. MWallet
3. Voucher
4. Inquiry
a. Payment Status Inquiry
b. Token Inquiry
7.1 Debit/Credit
Card Payment
7.1.1 Authorize Payment
This is a request to obtain an authorization for a proposed funds transfer. An authorization is a

response from a financial institution indicating that payment information is valid and funds are
available in the payers account.
7.1.1.1 Version 1.1
Type POST
URL https://<baseApiUrl>/api/authorize/AuthorizePayment
Headers application/json

{
"AuthorizeRequest":{
"pp_InstrumentType":"CARD",
"pp_TxnRefNo":"T20170425112425",
"pp_Amount":"10000",
"pp_TxnCurrency":"PKR",
"InstrumentDTO":{
"pp_CustomerCardNumber":"4557012345678902",
Request "pp_CustomerCardExpiry":"1020",
"pp_CustomerCardCvv":"101"
},
"pp_MerchantID":"Test00127801",
"pp_Password":"000000000",
"pp_SecureHash":"",
"pp_Frequency": "SINGLE"
}
}
{
Response "responseCode": "",
"responseMessage": ""
}
7.1.1.2 Version 2.0 (Without Token)
Type POST
URL https://<baseApiUrl>/api/2.0/authorize/AuthorizePayment
{
"pp_Frequency" : "SINGLE",
"pp_TxnRefNo":"T20190415174304",
"pp_CustomerCardNumber":"5123456789012346",
"pp_CustomerCardExpiry":"0521",
Request
"pp_CustomerCardCvv":"111" ,
"pp_MerchantID":" Test00127801",
"pp_Password":"000000000",
"pp_CustomerID":"test",
"pp_CustomerEmail":"test@test.com",
"pp_CustomerMobile":"03222852628",
"pp_SecureHash":""
}
{
"pp_InstrToken": "",
"pp_TokenizationResponseCode": "",
"pp_TokenizationResponseMessage": "",
Response
"pp_CustomerCardNumber": "",
"pp_CustomerCardExpiry": "",
"pp_CustomerID": "",
"pp_CustomerEmail": "",

"pp_CustomerMobile": "",
"pp_ShouldTokenizeCardNumber": "",
"pp_IsRegisteredCustomer": "",
"pp_TxnRefNo": "",
"pp_MerchantID": "",
"pp_Password": "",
"pp_Amount": "",
"pp_TxnCurrency": "",
"pp_InstrumentType": "",
"pp_Frequency": "",
"pp_3DSecureID": "",
"pp_SecureHash": "",
"pp_ResponseCode": "",
"pp_ResponseMessage": ""
}
7.1.1.3 Version 2.0 (With Token)
Type POST
URL https://<baseApiUrl>/api/2.0/authorize/AuthorizePaymentViaToken
{
"pp_Frequency" : "SINGLE",
"pp_IsRegisteredCustomer" : "Yes",
"pp_TxnRefNo":"T20190424102755",
"pp_Amount":"100",
Request "pp_TokenizedCardNumber": "9475251683607119",
"pp_Password":"000000000",
"pp_CustomerID":"",
"pp_CustomerEmail":”",
"pp_CustomerMobile":"",
"pp_SecureHash":""
}
{
"pp_IsRegisteredCustomer": "",
"pp_TxnRefNo": "",
"pp_Password": "",
"pp_Amount": "",
"pp_TxnCurrency": "",
"pp_InstrumentType": "",
Response
"pp_Frequency": "",
"pp_InstrToken": "",
"pp_CustomerID": "",
"pp_CustomerEmail": "“,
"pp_CustomerMobile": "",
"pp_TokenizedCardNumber": "",

"pp_ResponseMessage": ""
}
7.1.1.4 Parameter Detail
Max.
Length
Type of instrument used for making
pp_Instrument
4A Yes CARD payment. It should only be CARD in
Type
this case.
Indicates the frequency of the
transaction offered to the payer.
Value could be any one of the

following, based on the usage:
SINGLE: Indicates a single transaction

pp_Frequency 9A Yes RECURRING, SINGLE where a single payment is used to
complete the order.
RECURRING: Indicates a recurring

transaction where the payer
authorizes you to automatically debit
their accounts for bill or invoice
payments.
20 AN & ‘/’ A unique value created by the
& ‘.’ merchant to identify the transaction.
100.00 will be passed
Please note that no decimal places
pp_Amount 13 N Yes as
are included. Decimal place will be
10000
assumed at the default position of
the currency provided.
pp_TxnCurrenc Currency of Transaction amount. It
3A Yes PKR
y has a fixed value ‘PKR’.
5123456789012346 Card number of the customer making
pp_CustomerC
16 N Yes the payment. It should be of
ardNumber
maximum 16 numeric digits.
Yes 1120 Expiry date of the card used for
making payment.
pp_CustomerC
4N
ardExpiry
Format: MMYY (Month Month Year
Year).
pp_CustomerC No 111 Card verification value, as printed on
3N
ardCvv the back or front of the card.
Merchant by PG.
Password is assigned to each
pp_Password 10 AN Yes 75019F19EA merchant and is used to authenticate
merchant at the time of payment.

Password is a system generated

value.
(Provided by Identifier address provided by
pp_CustomerID 255 AN No
Merchant) Merchant. This field can be accessible
in payment version 2.0
255 AN and Registered Customer’s Email address
pp_CustomerE
!#$%&'*+- No sample@gmail.com provided by Merchant. This field can
mail
/=?^_`{|}~ be accessible in payment version 2.0.
Regsitered Customer’s Mobile
pp_CustomerM Number provided by Merchant. This
11 N No 03001237896
obile field can be accessible in payment
version 2.0.
It represents that the request has
pp_IsRegistere
3A Yes Yes been made by the registered or a
dCustomer
guest customer of a merchant.
pp_TokenizedC
16 N No 9113633378227378 This token will be received to the
ardNumber
details when selected by the
customer on Payment portal.
9e107d9d372bb6826
Used to allow the Payment Gateway
bd81d3542a419d69e
pp_SecureHash 64 AN No to check the integrity of the
107d9d372bb6826bd
transaction request.
81d3542a419d6
7.1.2 Capture Payment
This is a request to capture funds previously reserved by an authorization. A Capture transaction

triggers the movement of funds from the payer's account to the merchant's account.
7.1.2.1 Version 1.1
Type POST
URL https://<baseApiUrl>/payaxisapplicationapi/api/authorize/Capture
{
"CaptureRequest" : {
"pp_TxnRefNo":"T20170425112425",
Request "pp_TxnCurrency":"PKR",
"pp_Password":"0123456789",
"pp_SecureHash":""
}
}

{
"pp_TxnRefNo":"T20190415103607",
Response "pp_TxnCurrency":"PKR",
"pp_Password":"0000000000",
"pp_SecureHash":""
}
7.1.2.2 Version 2.0
Type POST
URL https://<baseApiUrl>/api/2.0/authorize/Capture
{
"pp_TxnRefNo":"T20190415103607",
Request
"pp_Password":"0000000000",
"pp_SecureHash":""
}
{
"pp_TxnRefNo": "",
"pp_Password": "",
"pp_Amount": "",
Response "pp_TxnCurrency": "",
"pp_ResponseMessage":”"
}
Max.
Length
A unique value created by the
20 AN &
pp_TxnRefNo Yes Tx2011090901 merchant to identify the
‘/’ & ‘.’
transaction.
10000
Currency of Transaction amount. It
has a fixed value ‘PKR’.
Unique merchant code assigned to
each Merchant by PG.

Password assigned to each

merchant and is used to
pp_Password 10 AN Yes 75019F19EA authenticate merchant at the time
of payment. It is a system generated
value.
9e107d9d372bb6826
bd81d3542a419d69e
107d9d372bb6826bd
81d3542a419d6
7.1.3 Void
This is a request to void a previous transaction. A void will cancel the reservation of funds, done in
AUTHORIZE operation
7.1.3.1 Version 1.1
Type POST
URL https://<baseApiUrl>/payaxisapplicationapi/api/authorize/Void
{
"VoidRequest" : {
"pp_TxnRefNo":"T20170425112425",
Request "pp_MerchantID":"Test00127801",
"pp_Password":"0123456789",
"pp_SecureHash":""
}
}
{
"responseCode": "",
Response
}
Max.
Length
20 AN &
‘/’ & ‘.’
transaction.
of payment. Password is a system
generated value.
9e107d9d372bb6826
bd81d3542a419d69e
107d9d372bb6826bd
81d3542a419d6

7.1.4 Check 3DS Enrollement
This is a request to check a cardholder's enrollment in the 3DSecure scheme.
7.1.4.1 Version 1.1
Type POST
URL https://<baseApiUrl>/API/Purchase/Check3DsEnrollment
{
"pp_Version": "1.1",
"pp_TxnType": "MPAY",
"pp_TxnRefNo": "T20170425112405",
"pp_MerchantID": "Test00127801",
"pp_Password": "0123456789",
"pp_Amount": "20000",
"pp_TxnCurrency": "PKR",
Request "pp_TxnDateTime": "20170512101250",
"pp_TxnExpiryDateTime": "20170514101250",
"pp_BillReference": "billRef",
"pp_Description": "Description of transaction",
"pp_CustomerCardNumber": "5111111111111118",
"pp_CustomerCardExpiry": "0517",
"pp_CustomerCardCvv": "100",
"pp_SecureHash": ""
}
{
"result_CardEnrolled": "",
"c3dSecureID": "",
Response "aR_Simple_Html": "",
"responseCode": "",
}
Type POST
URL https://<baseApiUrl>/API/2.0/Purchase/Check3DsEnrollment
{
"pp_TxnRefNo": "T20170425112405",
"pp_Password": "0123456789",
Request "pp_Amount": "20000",
"pp_TxnDateTime": "20170512101250",

"pp_IsRegisteredCustomer": "Yes",
"pp_SecureHash": ""
}
{
"summaryStatus": "CARD_ENROLLED",
"result_CardEnrolled": "CARD_ENROLLED",
"c3DSecureID": "20190330160531033931",
"aR_Simple_Html": "<!DOCTYPE HTML PUBLIC \"-//W3C//
DTD HTML 4.01 Transitional//EN\" \"https://www.w3.org/TR/
html4/loose.dtd\"><html><head><title>Process Secure
Payment</title><meta http-equiv=\"content-type\"
content=\"text/html;charset=UTF-8\"><meta name=\"description\"
content=\"Process Secure Payment\"><meta name=\"robots\"
content=\"noindex\"><style type=\"text/css\">body
{font-family:\"Trebuchet MS\"sans-serif; background-color:
#FFFFFF; }#msg {border:5px solid #666; background-color:#fff;
margin:20px; padding:25px; max-width:40em;
-webkit-border-radius: 10px; -khtml-border-radius: 10px;
-moz-border-radius: 10px; border-radius: 10px;}
#submitButton { text-align: center ; }#footnote
{font-size:0.8em;}</style></head><body onload=\"
Response return window.document.echoForm.submit()\">
<form name=\"echoForm\" method=\"POST\"
action=\"https://mtf.gateway.mastercard.com/acs/
MastercardACS/
a94a275d-2cf8-4aea-8446-3708137404d7\"
accept-charset=\"UTF-8\">
<input type=\"hidden\" name=\"PaReq\"
value=\"eAFVUctygkAQvFvlP1Dcwy4gita4lu8QBQ2aSq4UbJREQHkE4zFfk+
/Kl2TWZ3Kgiu5mmp4e6OyjjfTB0yxM4rasKlSWeOwnQRiv2v
+vb41ShYpN
Tyxsxc+6J4CakP5SgDWneIfLQhcEfL9NYo6+WM71Hcgte/9etO
vn2CMepaGp6C0ejCl6PgrCJcSyMDvGPQMgYpScT4i9HC
+MzL/LVyu/YtC1WA==\"><input type=\"hidden\"
name=\"TermUrl\" value=\"https://<baseurl>/MerchantSimulator
/Merchant
/TestView\"><input type=\"hidden\" name=\"MD\"
value=\"\"><noscript><div id=\"msg\"><div
id=\"submitButton\"><input type=\"submit\"
value=\"Click here to
continue\" class=\"button\"></div></div></noscript>
</form></body>
</html>\n",
"secureHash": "6B5AB8ABE9DD8CEE7E9BD5786B7ECFA96E76A640E4FC142F

A3DCF32DBB431950",
"responseCode": "435",
"responseMessage": "Card holder is enrolled."
}
Type POST
Example URL https://<baseApiUrl>/api/2.0/purchase/Check3DsEnvironmentViaToken
Production URL Will be communicated after business approval
{
"pp_CustomerID":"test3ds",
"pp_CustomerEmail":"test2@test.com",
"pp_TxnRefNo": "T2019040210283",
"pp_MerchantID": "Merc0003",
"pp_Password": "0123456789",
Request
"pp_Amount": "20000",
"pp_TxnDateTime": "20190402102712",
"pp_TokenizedCardNumber":"9790662127634170",
"pp_SecureHash": "1B7082A29290BF22219343B4C0CEF052D08F7E16"
}
{
"summaryStatus": "CARD_ENROLLED",
"pp_CustomerID": "test3ds",
"pp_CustomerEmail": "test2@test.com",
"pp_CustomerMobile": "035678905432",
"result_CardEnrolled": "CARD_ENROLLED",
"c3DSecureID": "20190402232009270702",
"aR_Simple_Html": "<!DOCTYPE HTML PUBLIC
\"-//W3C//DTD HTML 4.01 Transitional//EN\"
\"https://www.w3.org/TR/html4/loose.dtd\"><html><head>
<title>Process Secure Payment</title><meta
Response http-equiv=\"content-type\" content=\"text/html;charset=
UTF-8\"><meta name=\"description\" content=\"Process
Secure Payment\"><meta name=\"robots\" content=\"noindex\"
><style type=\"text/css\">body {font-family:\"Trebuchet
MS\"sans-serif; background-color: #FFFFFF; }
#msg {border:5px solid #666; background-colo
r:#fff; margin:20px; padding:25px; max-width:40em
; -webkit-border-radius: 10px; -khtml-border-radius: 1
0px; -moz-border-radius: 10px; border-radius: 10px;}
#submitButton { text-align: center ;
}#footnote {font-size:0.8em;}</style></head><body
onload=\"return

window.document.echoForm.submit()\"><form
name=\"echoForm\" method=\"POST\"
action=\"https://mtf.gateway.mastercard.com/acs/
MastercardACS/cd4d9396-fe10-4182-a62d-2da086d5d666\"
accept-charset=\"UTF-8\"><input type=\"hidden\"
name=\"PaReq\" value=\"eAFVUctuwjAQvCPxD1HujZ2E0IAWI15V
U8pDkLbqqbKMBZESBww06bVf0+/ql3QdoLQ3z4x3d3YWum
WWWu9S75N+Y2geRu2qHmhs7
NguiQYEjoPqzYGADGl5Hw6zKW6LDL/Ll6v/QAxQLM6\">
<input type=\"hidden\"
name=\"TermUrl\" value=\"https://<baseurl>/MerchantSimulator
/Merchant
/TestView\"><input type=\"hidden\" name=\"MD\" value=\"\"><noscript>
<div id=\"msg\"><div id=\"submitButton\"><input type=\"submit\" value=
\"Click here to continue\" class=\"button\"></div></div></noscript>
</form></body></html>\n",
"secureHash": "79FC78371135FF982DA695D161A7D5CE43372C129D0B122",
"pp_TokenizedCardNumber": "9790662127634170",
"responseMessage": "Card holder is enrolled."
}
Max. Mandator
Parameter Sample Values Remarks
Length y
API Version.
pp_Version 4 AN Yes 1.1 Fixed value ‘1.1’ or ‘2.0’ should be
used
pp_TxnType 10 AN No MPAY or AUTH MPAY – Direct Pay Mode
AUTH – Authorize/Capture Mode
20 AN & A unique value created by the
‘/’ & ‘.’ merchant to identify the transaction.
merchant and is used to authenticate
merchant at the time of payment. It
is a system generated value.
10000
9th Oct, 2011 10:35:47 Merchant provided date and time of
pp_TxnDateTim
14 N Yes PM will be sent as transaction. The format of date time
e
‘20111009223547’ should be yyyyMMddHHmmss.

Transaction Expiry can be specified

by merchant to indicate to the issuing
9th Oct, 2011 10:35:47
pp_TxnExpiryDa bank that the transaction must be
14 N No PM will be sent as
teTime approved within this period. Please
‘20111009223547’
note that the default and maximum
No Cart001
e ‘.’ Bill/invoice Number being settled.
This field will be parsed to identify
200 Free Payment for 3 Item(s) any malicious data entered by the
pp_Description No
Text Field bought end user. In cases when any of these
characters <>\*=%/:'"{} are inserted,
they will be replaced with a space.
Pipe ‘|’ is not allowed
5123456789012346 Card number of the customer making
pp_CustomerCar
16 N Yes the payment. It should be of
dNumber
maximum 16 numeric digits.
Yes 1120 Expiry date of the card used for
making payment.
pp_CustomerCar
4N
dExpiry
Format: MMYY (Month Month Year
Year).
pp_CustomerCar No 111 Card verification value, as printed on
3N
dCvv the back or front of the card.
This parameter can be accessible
from 2.0 version. It represents that
pp_IsRegistered
3A Yes Yes the request has been made by the
Customer
registered or a guest customer of a
merchant.
(Provided by Registered Customer’s LoginID or
Merchant) Identifier provided by Merchant
255 AN
and
pp_CustomerEm !#$%&'* Registered Customer’s email address
No sample@gmail.com
ail +- provided by Merchant
/=?^_`{|}
~
pp_CustomerM Regsitered Customer’s Mobile
11 N No 03001237896
obile Number provided by Merchant.
It represents the token for returning
pp_TokenizedCa
16 N Yes 9790662127634170 customer against their already saved
rdNumber
card.
9e107d9d372bb6826b Used to allow the Payment Gateway
pp_SecureHash 64 AN No d8d69e107d9d372bb6 to check the integrity of the
826bd81d3542a419d6 transaction request.

7.1.5 Process ACS
This is a request to interprets the authentication response returned from the card Issuer's Access
Control Server (ACS) after the cardholder completes the authentication process. The response
indicates the success or otherwise of the authentication.
7.1.5.1 Version 1.1
Type POST
URL https://<baseApiUrl>/API/Purchase/ProcessACSResult
{
"pp_TxnRefNo": "T20170416122642",
"pp_Password": "0123456789",
"pp_3dSecureID":"159915",
Request "pp_TxnDateTime": "20170425210900",
"paRes":"xxxxx",
"pp_SecureHash": ""
}
{
"c3dSecureID": "",
"gateWayCode": "",
Response
"responseCode": "",
}
Type POST
URL https://<baseurl>/API/2.0/Purchase/ProcessACSResult
{
"pp_TxnRefNo": "T20190330150615",
Request "pp_MerchantID": "Merc0003",
"pp_Password": "0123456789",
"pp_3dSecureID":"20190330160531033931",
"pp_TxnDateTime": "20190330150613",
"paRes":"xxxxx”,

"pp_SecureHash": "1B7082A29290BF222E0B788343B4C0CEF052D08F7E16"
}
{
"c3DSecureID": "20190330160531033931",
"summaryStatus": "AUTHENTICATION_SUCCESSFUL",
"gateWayCode": "AUTHENTICATION_SUCCESSFUL",
Response "secureHash": "958BE413012CFCE5F7DF6050BE3EB97377CCB51FF90E14",
"responseMessage": "The cardholder was successfully authenticated by the card
Issuer."
}
Type POST
URL https://<baseApiUrl>/api/2.0/purchase/ProcessACSResultViaToken
{
"pp_TxnRefNo": "T20190330150615",
Request "pp_Password": "0123456789",
"pp_3dSecureID":"20190330160531033931",
"pp_TxnDateTime": "20190330150613",
"paRes":"xxxxxxxx",
"pp_SecureHash": “A29290BF22219A5F2CE0B788343B4C0CEF052D08F7E16"
}
{
"c3DSecureID": "20190330160531033931",
"summaryStatus": "AUTHENTICATION_SUCCESSFUL",
"gateWayCode": "AUTHENTICATION_SUCCESSFUL",
Response "secureHash": "958BE4135F7DF6050BE3EB97377CCFDB1017B51FF90E14",
"responseMessage": "The cardholder was successfully authenticated by the card
Issuer."
}
Max. Mand
Length atory
pp_TxnType 10 AN No MPAY or AUTH MPAY – Direct Pay Mode
AUTH – Authorize/Capture Mode

20 AN & A unique value created by the merchant

‘/’ & ‘.’ to identify the transaction.
Merchant by PG.
and is used to authenticate merchant at
the time of payment. Password is a
A unique identifier supplied by Jazz
20190604020652762
pp_3dSecureID 64 N Yes Cash to Merchant in Check 3DS
003
Enrollment response.
9th Oct, 2011
10:35:47 PM will be
sent as
‘20111009223547’
9th Oct, 2011 merchant to indicate to the issuing
pp_TxnExpiryDateTi 10:35:47 PM will be bank that the transaction must be
14 N No
me sent as approved within this period. Please
‘20111009223547’ note that the default and maximum
20 AN &
pp_BillReference No Cart001
‘.’ Bill/invoice Number being settled.
screen as desired by the merchant. This
field will be parsed to identify any
200 Free Payment for 3 Item(s) malicious data entered by the end user.
pp_Description No
Text Field bought In cases when any of these characters
<>\*=%/:'"{} are inserted, they will be
replaced with a space. Pipe ‘|’ is not
allowed
An HTML form for the card enrolled
transaction.This form needs to be
rendered by the merchant so that
paRes Yes xxxx customer can input 3DS PIN. Upon
submission ,Base64 encoded string i.e
PaRes, will be received that will have to
be sent in Process ACS request.
pp_IsRegisteredCus
tomer
(Provided by
pp_CustomerID 255 AN No As provided in the request.
Merchant)
255 AN
and
!#$%&'*
pp_CustomerEmail No sample@gmail.com As provided in the request.
+-
/=?^_`{|}
~
pp_CustomerMobil
11 N No 03001237896 As provided in the request
e
9e107d9d372bb6826
bd81d3542a419d69e
request.

7.1.6 Direct Pay
This is a single transaction to authorise the payment and transfer funds from the payer's account to your
Merchant’s account.
7.1.6.1 Version 1.1
Type POST
URL https://<baseApiUrl>/API/Purchase/PAY
{
"pp_TxnRefNo": "T20170518161116",
"pp_Password": "0123456789",
"pp_Amount": "10000",
"pp_TxnDateTime": "20170518161116",
Request
"pp_Frequency": "SINGLE"
}
{
"responseCode": "",
Response
}
Type POST
URL https://<baseApiUrl>/API/2.0/Purchase/PAY
{
"pp_ShouldTokenizeCardNumber" : "Yes",
Request "pp_CustomerMobile":"0336789043",
"pp_TxnRefNo": "T20190329131312",
"pp_Password": "0123456789",
"pp_Amount": "20000",

"pp_TxnDateTime": "20190329131312",
"pp_C3DSecureID":"20190328100447620695",
"pp_SecureHash": "1B7082A235E0B788343B4C0CEF052D08F7E16"
}
{
"pp_MerchantID": "MERC0003",
"pp_Language": "EN",
"pp_SubMerchantID": "",
"pp_BankID": "",
"pp_ProductID": "",
"pp_TxnRefNo": "T20190401095125",
"pp_Amount": "20000",
"pp_TxnDateTime": "20190401095125",
"pp_TxnExpiryDateTime": "",
"pp_ReturnURL": "",
"ppmpf_1": "",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": "",
"ppmbf_1": "",
Response
"ppmbf_2": "",
"ppmbf_3": "",
"ppmbf_4": "",
"ppmbf_5": "",
"pp_Frequency": "SINGLE",
"pp_RetreivalReferenceNo": "190401301391",
"pp_TokenizationResponseCode": "T01",
"pp_TokenizationResponseMsg": "The card tokenizati
on request has been accepted.You will be shortly notified
on your system about its status",
"pp_CustomerID": "test1",
"pp_CustomerEmail": "test2@test.com",
"pp_C3DSecureID": "",
"pp_ShouldTokenizeCardNumber": "No",
"pp_SecureHash": "12DAEC8D45843E2B46CFC983AE320C04C714",
"pp_InstrToken": null,
"responseMessage": "Thank you, your transaction was successful. "
}

Type POST
URL https://<baseApiUrl>/api/2.0/purchase/PayViaToken
{
"pp_CustomerID":"testPay",
"pp_C3DSecureID" :"",
"pp_TxnRefNo": "T20190403093759",
"pp_Password": "0123456789",
Request
"pp_Amount": "20000",
"pp_TxnDateTime": "20190403093750",
"pp_Description": "Description of pay transaction",
"pp_TokenizedCardNumber":"9790662127634170",
"pp_SecureHash": "1B7082A29290BF222194C0CEF052D08F7E16"
}
{
"pp_BankID": "",
"pp_ProductID": "",
"pp_TxnRefNo": "T20190403093759",
"pp_Amount": "20000",
"pp_TxnDateTime": "20190403093750",
"pp_TxnExpiryDateTime": "",
"pp_Description": "Description of pay transaction",
Response
"pp_ReturnURL": "",
"ppmpf_1": "",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": "",
"ppmbf_1": "",
"ppmbf_2": "",
"ppmbf_3": "",
"ppmbf_4": "",
"ppmbf_5": "",
"pp_CustomerID": "testPay",
"pp_CustomerEmail": "test@test.com",

"pp_CustomerCardNo": "512345******2346",
"pp_SecureHash": 61B9869E834E90401597250A4F8E4FC3055D78D1168",
"pp_C3DSecureID": "",
"responseMessage": "Thank you for Using JazzCash, your transaction was successful. "
}
Max. Mand
Length atory
API Version.
used
For this transaction, it will be fixed
pp_TxnType 10 AN No MPAY
value “MPAY”
20 AN &
‘/’ & ‘.’
transaction.
generated value.
10000
Merchant provided date and time
9th Oct, 2011 10:35:47
of transaction. The format of date
pp_TxnDateTime 14 N Yes PM will be sent as
time should be
‘20111009223547’
yyyyMMddHHmmss.
Transaction Expiry can be specified
by merchant to indicate to the
9th Oct, 2011 10:35:47 issuing bank that the transaction
pp_TxnExpiryDateTim
14 N No PM will be sent as must be approved within this
e
‘20111009223547’ period. Please note that the default
and maximum value of this expiry
is 3 months.
20 AN &
pp_BillReference No Cart001
‘.’ Bill/invoice Number being settled.


This field will be parsed to identify
200 Free Payment for 3 Item(s) any malicious data entered by the
pp_Description No
Text Field bought end user. In cases when any of
these characters <>\*=%/:'"{} are
inserted, they will be replaced with
a space. Pipe ‘|’ is not allowed
pp_CustomerCardNu 5123456789012346 Customer Card No.
16 N Yes
mber
pp_CustomerCardExpi Yes 1120 Customer Card Expiry mentioned
4N
ry on card
No 111 Customer Card CVV mentioned on
pp_CustomerCardCvv 3N
back of card
pp_TokenizedCardNu This token will be received to the

16 N Yes 9113633378227378
mber merchant in response of Pay
request when saved card details
was selected by the customer on
Payment portal.
9e107d9d372bb6826b
d81d3542a419d69e10 Checksum to check the integrity of
pp_SecureHash 64 AN No
7d9d372bb6826bd81d the transaction request by PG
3542a419d6
Indicates the frequency of the
transaction offered to the payer.
Value could be any one of the

following, based on the usage:
SINGLE: Indicates a single

transaction where a single
pp_Frequency 9A Yes RECURRING, SINGLE
payment is used to complete the
order.
RECURRING: Indicates a recurring

transaction where the payer
authorizes you to automatically
debit their accounts for bill or
invoice payments.

pp_IsRegisteredCusto
3A Yes Yes, No been made by the registered or a
mer
Its value represents of the

customer has requested to save
pp_ShouldTokenizeCa the card details. If its value is yes,
3A No Yes, No
rdNumber then a token will be generated
against the CHD and will be sent to
merchant via ITN

(Provided by Registered Customer’s LoginID or

Merchant) Identifier provided by Merchant.
255 AN
and
!#$%&'* Registered Customer’s email
pp_CustomerEmail No sample@gmail.com
+- address provided by Merchant.
/=?^_`{|}
~
Registered Customer’s mobile no.
pp_CustomerMobile 11 N No 03001237896
provided by Merchant.
A unique identifier supplied to
201906040206527620
pp_C3DSecureID 64 N No Merchant in Check 3DS Enrollment
03
response.
pp_ResponseCode 3 AN Yes 000 response code of 000 represents
response codes refer to Appendix I.
Not enough balance to
pp_ResponseMessage 200 AN No This field will be mandatory for all
perform transaction
equal to 000.
7.1.7 Refund
The card refund transaction option will allow the merchant to refund a Card transaction processed by the
Payment Gateway. Typically, a Refund is linked to the Capture or Pay through the txnrefno.
7.1.7.1 Version 1.1
Type POST
URL https://<baseApiUrl>/api/authorize/Refund
{
"pp_TxnRefNo":"T20170425112424",
"pp_Amount":"9999",
Request
"pp_Password":"0123456789",
"pp_SecureHash":""
}
{
Response "pp_ResponseMessage": "",
"pp_SecureHash":""
}

Max. Mandator
Length y
20 AN &
‘/’ & ‘.’
transaction.
100.00 will be passed as Please note that no decimal places

pp_Amount 13 N Yes
10000 are included. Decimal place will be
generated value.
9e107d9d372bb6826b
d81d3542a419d69e107
d9d372bb6826bd81d3
542a419d6
pp_ResponseCod success or failure. For a complete list
3 AN Yes 000
e of response codes refer to Appendix
I
pp_ResponseMes Not enough balance to
200 AN No This field will be mandatory for all
sage perform transaction
equal to 000.

7.2 MWallet Payment
7.2.1 Pay
This request is used to make payment against wallet account
7.2.1.1 Version 1.1
Type POST
URL https://<baseApiUrl>/api/Payment/DoTransaction
{
"pp_Version": ”1.1”,
"pp_TxnType": ”MWALLET”,
"pp_Language": ”EN”,
"pp_MerchantID": ”Merc0003”,
"pp_SubMerchantID": ””,
"pp_Password": ”0123456789”,
"pp_BankID": "",
"pp_ProductID": "",
"pp_TxnRefNo": ””,
"pp_Amount": ”10000”,
"pp_TxnCurrency": ”PKR”,
Request
"pp_TxnDateTime": ””,
"pp_BillReference": ””,
"pp_Description": ””,
"pp_TxnExpiryDateTime",: ””
"pp_ReturnURL": ””,
"pp_SecureHash": ””,
“ppmpf_1” : ””,
“ppmpf_2” : ””,
“ppmpf_3” : ””,
“ppmpf_4” : ””,
“ppmpf_5” : ””
}
{
"pp_Amount": "10000",
"pp_AuthCode": "",
"pp_BankID": "",
"pp_MerchantID": "MC0034",
"pp_ResponseCode": "000",
Response "pp_ResponseMessage": "Thank you for Using JazzCash, your transaction was
successful.",
"pp_SubMerchantId": "",
"pp_TxnDateTime": "20191216100946",
"pp_TxnRefNo": "T20191216100943",
"pp_SettlementExpiry": "",
"pp_TxnType": "MWALLET",

"ppmpf_1": "03333333333",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": "",
"pp_SecureHash": ""
}
7.2.1.2 Version 2.0
Type POST
URL https://<baseApiUrl>/api/2.0/Purchase/DoTransaction
{
"pp_Password": ”0123456789”,
“pp_MobileNumber":”03411728699”,
“pp_CNIC”: ”345678”,
"pp_Amount": ”10000”,
“pp_DiscountedAmount”:””,
Request
“ppmpf_1” : ””,
“ppmpf_2” : ””,
“ppmpf_3” : ””,
“ppmpf_4” : ””,
“ppmpf_5” : ””
}
{
"pp_Amount": "10000",
"pp_AuthCode": "",
"pp_ResponseMessage": "Thank you for Using JazzCash, your transaction was
Response successful.",
"pp_RetrievalReferenceNo": "",
"pp_TxnDateTime": "",
"pp_TxnRefNo": "",
"pp_MobileNumber": "03123456789",
"pp_CNIC": "345678",
"pp_DiscountedAmount": "",

"ppmpf_1": "",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": "",
"pp_SecureHash": ""
}
Max.
Length
API version. CNIC support is only present
pp_Version 4 AN Yes 1.1, 2.0
in 2.0

pp_TxnType 10 AN Yes MWALLET
It has the fixed value MWALLET

the page.
Unique code assigned to each Merchant
by PG.
pp_SubMerchantI
D
Transaction reports will be grouped on
the basis of Sub Merchant Id, if available.
time of payment. It is a system generated
value.
available.

20 AN
A unique value created by the merchant
pp_TxnRefNo & ‘/’ & Yes Tx2011090901
to identify the transaction.
‘.’
This field will contain Customer’s Mobile
pp_MobileNumber 11 N Yes 03411728699
Number (used only in version 2.0)

This field will contain Customer’s last 6

pp_CNIC 6N Yes 345678
digits of CNIC (used only in version 2.0)
100.00 will be
pp_DiscountedAm This field will contain final amount after
255 AN No passed as
ount discount (used only in version 2.0)
10000
100.00 will be
included. Decimal place will be assumed
10000
at the default position of the currency
provided.
9th Oct, 2011
10:35:47 PM will be
sent as
‘20111009223547’
20 AN
pp_BillReference Yes Cart001 Bill/invoice Number being settled.
& ‘.’
200
Free Payment for 3
pp_Description Yes entered by the end user. In cases when
Text Item(s) bought
any of these characters <>\*=%/:'"{} are
Field
pp_TxnExpiryDate 10:35:47 PM will be that the transaction must be approved
14 N Yes
Time sent as within this period. Please note that the
‘20111009223547’ default and maximum value of this expiry
is 3 months.
This field is mandatory and merchant
must share this URL before using API as it
Merchant will be a part of merchant profile.URL
pp_ReturnURL 200 AN Yes site/payment/Resu should always be the same in every
lts.aspx request once shared. It is a part of
merchant authentication, difference of
URL will fail the validation.
9e107d9d372bb68
19d6
Mobile Number Field
ppmpf_1 255 AN Yes 03211234567
100.00 will be
discount)
10000

Optional Fields
ppmpf_4 255 AN No
Merchant can send additional
information to PG in this field. These will
255 be returned to Merchant in transaction
ppmpf_5 No
AN response.

pp_AuthCode 12 N No 123456
Appendix I for a list of response codes and
the codes which when sent will require
Auth Code.
Response code representing the success
pp_ResponseCode 3 AN Yes 000 or failure. For a complete list of response
codes refer to Appendix I
Error details in case the transaction failed
Not enough
pp_ResponseMess 200 to be processed.
No balance to perform
age AN This field will be mandatory for all cases
transaction
pp_RetreivalRefer
enceNo
9th Oct, 2011 this time, the PG will mark the transaction
pp_SettlementExpi 10:35:47 PM will as expired and the Merchant will not be
14N No
ry be sent as able to resume it. Used in DD txnType only
‘20111009223547’
successful response code and when the
AuthCode is not blank.
7.2.2 Refund
The wallet refund transaction option will allow the merchant to fully/partially refund a wallet transaction
processed by the Payment Gateway. Typically, a Refund is linked to the wallet transaction through the
transaction reference number. Partial refund and multiple partial refund requires special privileges assigned to
merchant by backoffice user.
7.2.2.1 Version 1.1
Type POST
URL https://<baseApiUrl>/api/Purchase/domwalletrefundtransaction

{
"pp_TxnRefNo":"T20170425112424",
"pp_Amount":"100",
Request "pp_MerchantID":"Test00127801",
"pp_Password":"0123456789",
"pp_MerchantMPIN":"1234",
"pp_SecureHash":""
}
{
Response "pp_ResponseMessage": "",
"pp_SecureHash":""
}
Max. Mandato
Length ry
20 AN
‘.’
100.00 will be passed Please note that no decimal places are

pp_Amount 13 N Yes
as 10000 included. Decimal place will be assumed
provided.
Unique merchant code assigned to each
Merchant by PG.
Password is assigned to each merchant
A four digit number provided by merchant

pp_MerchantMPIN 4N Yes XXXX
that will be validated by PGW.Transaction
of a merchant is secured by this number.
9e107d9d372bb6826b
d81d3542a419d69e10
7d9d372bb6826bd81d
request.
3542a419d6
pp_ResponseMessag Not enough balance to to be processed.
200 AN No
e perform transaction This field will be mandatory for all cases

7.3 OTC Payment
7.3.1 Pay
This request is used to make payment against voucher
7.3.1.1 Version 1.1
Type POST
URL https://<baseApiUrl>/api/Payment/DoTransaction
{
"pp_Version": ”1.1”,
"pp_TxnType": ”OTC”,
"pp_Password": ”0123456789”,
"pp_BankID": "",
"pp_ProductID": "",
"pp_Amount": ”10000”,
Request
"pp_ReturnURL": ””,
“ppmpf_1” : ””,
“ppmpf_2” : ””,
“ppmpf_3” : ””,
“ppmpf_4” : ””,
“ppmpf_5” : ””
}
{
"pp_Amount": "10000",
"pp_AuthCode": "",
"pp_BankID": "",
"pp_MerchantID": "MC0034",
Response "pp_ResponseMessage": "Order is placed and waiting for financials to be received
over the counter.",
"pp_SubMerchantId": "",
"pp_TxnDateTime": "20191216100946",
"pp_TxnRefNo": "T20191216100943",
"pp_TxnType": "OTC",

"ppmpf_1": "03333333333",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": "",
"pp_SecureHash": ""
}
Max.
Length
pp_Version 4 AN Yes 1.1 API version. It will contain fix value of 1.1

pp_TxnType 10 AN Yes OTC
It has the fixed value OTC

the page.
by PG.
pp_SubMerchantI
D
value.
available.

20 AN
‘.’
This field will contain Customer’s Mobile
pp_MobileNumber 11 N Yes 03411728699
Number (used only in version 2.0)


100.00 will be
10000
provided.
9th Oct, 2011
10:35:47 PM will be
sent as
‘20111009223547’
20 AN
pp_BillReference Yes Cart001 Bill/invoice Number being settled.
& ‘.’
200
Free Payment for 3
Text Item(s) bought
Field
pp_TxnExpiryDate 10:35:47 PM will be that the transaction must be approved
14 N Yes
Time sent as within this period. Please note that the
is 3 months.
must share this URL before using API as it
Merchant will be a part of merchant profile.URL
pp_ReturnURL 200 AN Yes site/payment/Resu should always be the same in every
lts.aspx request once shared. It is a part of
9e107d9d372bb68
19d6
Mobile Number Field
ppmpf_1 255 AN Yes 03211234567
100.00 will be
discount)
10000
Optional Fields
ppmpf_4 255 AN No
information to PG in this field. These will
255 be returned to Merchant in transaction
ppmpf_5 No
AN response.



Auth Code.
Not enough
pp_ResponseMess 200 to be processed.
No balance to perform
age AN This field will be mandatory for all cases
transaction
pp_RetreivalRefer
enceNo
pp_SettlementExpi 10:35:47 PM will as expired and the Merchant will not be
14N No
ry be sent as able to resume it.
‘20111009223547’

7.4 Via Account Payment
7.4.1 Auth Token

The PG API will receive an HTTP POST request from the merchant which will contain the merchant
authentication credentials. The Payment Gateway will validate these credentials and response back
to merchant with auth token along with its expiry.
7.4.1.1 Version 1.1

Type POST
URL https://<baseApiUrl>/payaxisapplicationapi/api/connect/token
Content-Type: application/json
Headers Authorization: Basic c2FpYjpzYWli
{
"grant_type":"client_credentials",
Request "client_id":"test_merchant",
"client_secret":"0123456798"
}
{
"token_type": "bearer",
Response "access_token": "k8hg90Ol4AdFoyeT9GAOx4nDwQae3XX7",
"expires_in": 7200
}
Man
Max.
Parameter dato Sample Values Remarks
Length
ry
Header
Content-Type - Yes application/json Will always be “application/json”
Value of Base64Endode(ClientId: Client
Authorization - Yes Basic c2FpYjpzYWli
Secret) provided
Request
Fixed value 'client_credentials' should be
grant_type 50 A Yes client_credentials used
client_id 20 AN Yes test_merchant Client id provided to each merchant
client_secret 20 AN Yes 0123456798 Client secret provided to each merchant
Response
token_type N/A Yes bearer Fixed value “bearer” for KONG server
k8hg90Ol4AdFoyeT9GAOx Auth token that will be used in sent in
access_token N/A Yes 4nDwQae3XX7 subsequent requests
Time (seconds) after which the token will be
expires_in N/A Yes 300 expired

7.4.2 List of Banks

The PG API will receive an HTTP GET request from the merchant which will contain the
merchant id along with the auth token in header. The Payment Gateway will validate these
credentials and response back to merchant with the list of banks associated to the merchant.
7.4.2.1 Version 1.1
Type GET
URL https://<baseApiUrl>/api/merchants/{merchantID}/banks
Request No body as it is a get request
{
"banks": [
{
"bankName": "Habib Bank Limited Pakistan",
"bankID": "HBL"
},
{
Response
"bankName": "Meezan Bank Limited",
"banID": "MBL"
}
],
"responseMessage": "The requested operation has been performed successfully."
}
Max. Manda
Length tory
bankName 200 AN No Habib Bank Limited Bank name
bankID 4 AN No HBL Unique Bank code for each bank
Response code representing the success or
failure. For a complete list of response
responseCode 3 AN Yes 000 codes refer to Appendix I.
Response detail representing the success
responseMessage 200 AN No No banks found message or failure reason.
7.4.3 Generate OTP

The PG API will receive an HTTP POST request from the merchant which will contain the
transaction payload along with the auth token in the header. The Payment Gateway will
validate transaction payload and response back to merchant.
7.4.3.1 Version 1.1

Type POST

URL https://<baseApiUrl>/api/transaction/generateOTP
{
"pp_version": "1.1",
"pp_txnType": "ACC",
"pp_language": "EN",
"pp_merchantID": "NewMerch",
"pp_password": "0123456789",
"pp_txnRefNo": "T20170912000010",
"pp_amount": "100",
"pp_txnCurrency": "PKR",
"pp_txnDateTime": "20170912000000",
Request
"pp_billReference": "123",
"pp_description": "Test payment for Transaction Via Account",
"pp_txnExpiryDateTime": "20170913000000",
"pp_returnURL": "https://localhost/Simulator/DemoServer/Index",
"pp_accountNo": "12345678902222",
"pp_CNIC": "1234512345671",
"pp_bankID": "HBL",
"ppmpf_1": "NIFT",
"pp_secureHash":"706EA02CC51ED4BFA896D6CD88FC527132790"
}
{
"pp_TxnType": "ACC",
"pp_MerchantID": "NEWMERCH",
"pp_TxnRefNo": "T20170912000010",
"pp_Amount": "100",
"pp_TxnDateTime": "20170912000000",
"pp_BillReference": "123",
"pp_ResponseMessage": "",
Response "pp_RetreivalReferenceNo": "170912007540",
"pp_AuthCode": "",
"pp_BankID": "",
"pp_CNIC": "1234512345671",
"pp_AccountNo": null,
"pp_SecureHash": "516FA8F2EB34DF8E8443A1762C56DBC409C9D44A4EDF",
"ppmpf_1": "NIFT",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": ""
}

Max.
Length

API Version

pp_TxnType 10 AN Yes ACC
ACC = ViaAccount

the page.
by PG.
value.
pp_BankID 4AN No HBL Bank Code of the customer’s banks

100.00 will be
10000
provided.
9th Oct, 2011
14 N Yes transaction. The format of date time
e sent as
‘20111009223547’
Yes Cart001
e ‘.’ Bill/invoice Number being settled
200 Free Payment for 3
Text Field Item(s) bought
pp_TxnExpiryDa 10:35:47 PM will be that the transaction must be approved
14 N Yes
teTime sent as within this period. Please note that the
is 3 months.
https://Merchant must share this URL before using API as it
pp_ReturnURL 200 AN Yes site/payment/Resu will be a part of merchant profile.URL
lts.aspx should always be the same in every
request once shared. It is a part of


9e107d9d372bb68
19d6
ppmpf_1 255 AN No
ppmpf_2 255 AN No
Optional Fields
ppmpf_3 255 AN No
ppmpf_4 255 AN No information to PG in this field. These will
be returned to Merchant in transaction
response.
ppmpf_5 255 AN No


Auth Code.
pp_ResponseCo
3 AN Yes 000 or failure. For a complete list of response
de
pp_ResponseMe No Response detail representing the success

200 AN No banks found
ssage message or failure reason

pp_RetreivalRef
erenceNo
7.4.4 Pay Via Account

The PG API will receive an HTTP POST request from the merchant which will contain the
transaction payload along with the auth token in the header and OTP entered by customer. The
Payment Gateway will validate transaction payload and response back to merchant.
7.4.4.1 Version 1.1
Type POST

URL https://<baseApiUrl>/api/transction/viaaccount
{
"pp_ Version ": "1.1",
"pp_ TxnType ": "ACC",
"pp_ Language ": "EN",
"pp_ MerchantID ": "NewMerch",
“pp_ SubMerchantID ": "",
Request
"pp_Password": "0123456789",
"pp_TxnRefNo": "T20170912000001",
"pp_OTP": "233117",
"pp_Securehash": "9e107d9d372bb6826bdd9d372bb6826bd81d3542a419d6"
}
{
"pp_TxnType": "ACC",
"pp_MerchantID": "NEWMERCH",
"pp_TxnRefNo": "T20170912000010",
"pp_Amount": "100",
"pp_TxnDateTime": "20170912000000",
"pp_BillReference": "123",
"pp_ResponseMessage": "",
Response
"pp_AuthCode": "",
"pp_BankID": "HBL",
"pp_CNIC": "1234512345671",
"pp_AccountNo": null,
"pp_SecureHash": "516FA8F2EB34DC5FAAC5A1762C56DBC409C9D44A4EDF",
"ppmpf_1": "NIFT",
"ppmpf_2": "",
"ppmpf_3": "",
"ppmpf_4": "",
"ppmpf_5": ""
}
Max.
Length
API Version

pp_TxnType 10 AN Yes ACC
ACC = ViaAccount


the page.
by PG.
value.
pp_SubMerchantI
D
pp_BankID 4AN No HBL Bank Code of the customer’s banks

OTP provided by the customer, which was
pp_OTP 4-6 N Yes 123456
received on his/her registered mobile no.
100.00 will be
10000
provided.
9th Oct, 2011
10:35:47 PM will be
sent as
‘20111009223547’
20 AN &
pp_BillReference Yes Cart001
‘.’ Bill/invoice Number being settled
200
Free Payment for 3
Text Item(s) bought
Field
pp_TxnExpiryDat 10:35:47 PM will be that the transaction must be approved
14 N Yes
eTime sent as within this period. Please note that the
is 3 months.
https://Merchant must share this URL before using API as it
pp_ReturnURL 200 AN Yes site/payment/Resu will be a part of merchant profile.URL
lts.aspx should always be the same in every
request once shared. It is a part of


9e107d9d372bb68
19d6
pp_RetreivalRefe
renceNo

Auth Code.
pp_SettlementEx 10:35:47 PM will be as expired and the Merchant will not be
14N No
piry sent as able to resume it.
‘20111009223547’
pp_CNIC 13 N 42201767657528 Customer’s CNIC No.
pp_AccountNo 8-32 AN Yes 10123456789 Customer’s Account No.
ppmpf_1 255 AN No NIFT
ppmpf_2 255 AN No
Optional Fields
ppmpf_3 255 AN No
ppmpf_4 255 AN No information to PG in this field. These will
be returned to Merchant in transaction
response.
ppmpf_5 255 AN No

pp_ResponseCod
3 AN Yes 000 or failure. For a complete list of response
e

pp_ResponseMes No Response detail representing the success

200 AN No banks found
sage message or failure reason
7.5 Payment Status

Inquiry
This is a request to inquire the current status of an order, that is request by merchant using any
transaction type.
7.5.1.1 Version 1.1
Type POST
URL https://<baseApiUrl>/api/PaymentInquiry/Inquire
{
"pp_TxnRefNo":"T20170518161115",
Request
"pp_Password":"0123456789",
"pp_SecureHash":""
}
{
"pp_Status": "Completed",
"pp_RetrievalReferenceNo": "191125009663",
"pp_SettlementDate": "20191126120000",
"pp_AuthCode": "",
Response "pp_BankID": "0",
"pp_ProductID": "0",
"pp_SecureHash": "731C0692095E8A7D0AAA94DE955B0DC03DD26287"
“pp_ResponseCode”:”000”,
“pp_ResponseMessage”:” The requested operation has been performed
successfully.”,
}
Max.
Length
20 AN &
‘/’ & ‘.’
transaction.
generated value.

9e107d9d372bb6826b
d81d3542a419d69e10
7d9d372bb6826bd81d
3542a419d6
Status of inquired transaction
pp_Status No Completed Possible values: Completed,
Pending, Failed
Payment Gateway when the
transaction got processed. The
pp_RetrievalRefe
12 N No 000112233445 number should be stored and used
renceNo
for future reference.
The number is unique for any given
date.
Gateway to indicate when this
transaction will be settled.
When the Payment Gateway closes

pp_SettlementDa For 9th Sept, 2011
8N No the batch at the end of the day, the
te value will be 20110909
date will roll over to the next
processing day’s date.
This date will only be provided in
case a transaction is already
confirmed by the merchant.
Confirmation of the transaction by
this time, the PG will mark the
9th Oct, 2011 10:35:47
pp_SettlementEx transaction as expired and the
14N No PM will be sent as
piry Merchant will not be able to resume
‘20111009223547’
it.

successful response code and when
the AuthCode is not blank.
An identifying code issued by the
issuing bank to approve or deny the
transaction.
pp_AuthCode 12 N No 123456 The field is mandatory in case of

Appendix I for a list of response
codes and the codes which when
sent will require Auth Code.
pp_BankID 4AN No BNK01 should be sent as an empty field.
available.
pp_ProductID 4A No RETL DD transaction type, otherwise it


payment will be done. For e.g.
Retail, Corporate.

9e10bd81d3542a419d Checksum to check the integrity of
pp_SecureHash 64 AN No 69e107d9d372bb6826 the transaction request, by Payment
bd81d3542a419d6 Gateway
pp_ResponseCod success or failure. For a complete list
3 AN Yes 000
e of response codes refer to Appendix
I
pp_ResponseMes No Response detail representing the
200 AN No Transaction Found
sage success message or failure reason

Tokenization API
8.1 Delete Token
This request will delete the saved token against the provided field of TokenizedCardNumber.
8.1.1 Version 1.0
Type POST
URL https://<baseApiUrl>/api/v1.0/tokenization/deletetoken
{
"pp_CorrelationId": "Merc0003DEL00013",
Request
"pp_Password": "0123456789",
"pp_InstrumentType": "CARD",
"pp_SecureHash": "94108C9664C1CB49F1D7D277535BFDDC00673"
}
{
"pp_SecureHash": "61180FA21BD32BBF2610C68307B629DEAF3D9F3B8518",
"pp_Password": "0123456789",
Response "pp_InstrumentType": "CARD",
"pp_CorrelationId": "Merc0003DEL00043",
"pp_IsRegisteredCustomer": "yes",
"pp_ResponseCode": "T00",
"pp_ResponseMessage": "The tokenization operation was successfully processed"
}
8.1.2 Parameter Detail
Max. Mandator
Length y
display the page.
It’s a Unique Identifier. It can be
example201904041544
pp_CorrelationId 40 AN Yes alphanumeric and should not be
31243571246
greater than 40
pp_IsRegisteredC
ustomer
Unique Merchant Code assigned to


the time of payment. It is a system
generated value.
Type of instrument used for making
pp_InstrumentTy
4A Yes CARD payment. It should only be CARD in this
pe
case.
pp_TokenizedCar
16 N Yes 9113633378227378 This token will be received to the
dNumber
details when selected by the customer
on Payment portal.
9e10bd81d3542a419d6 Checksum to check the integrity of the
pp_SecureHash 64 AN No 9e107d9d372bb6826b transaction request, by Payment
d81d3542a419d6 Gateway
pp_ResponseCod
3 AN Yes T00 response code of 000 represents
e
success. For a complete list of response
codes refer to Appendix I.
The tokenization failed to be processed.
pp_ResponseMes
200 AN No operation was This field will be mandatory for all cases
sage
successfully processed where response code is not equal to
000.
8.2 Retrieve Token

This request will retrieve the card details against the provided field of TokenizedCardNumber.
8.2.1 Version 1.0
Type POST
URL https://<baseApiUrl>/api/v1.0/tokenization/retrievetoken
{
"pp_CorrelationId": "Transaction10200109010",
Request "pp_MerchantID": "Merc0003",
"pp_Password": "0123456789",
"pp_SecureHash": "10D859C9FFBA5AA0489B831D88607D14155444829B073D"
}

{
"pp_Brand": "MASTERCARD",
"pp_Expiry": "1120",
"pp_FundingMethod": "DEBIT",
"pp_Issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"pp_LocalBrand": "MASTERCARD",
"pp_cardNumber": "545721xxxxxx0019",
"pp_tokenStatus": "VALID",
Response "pp_MerchantID": "Merc0003",
"pp_SecureHash": "81B9A589A3BCE62B71893521F4582A",
"pp_Password": "0123456789",
"pp_CorrelationId": "Transaction10200109010",
"pp_ResponseCode": "T00",
"pp_ResponseMessage": "The tokenization operation was successfully processed"
}
Max.
Length
display the page.

Merchant by PG.

generated value.
pp_IsRegisteredCusto
3A Yes Yes been made by the registered or a
mer
Type of instrument used for
pp_InstrumentType 4A Yes CARD making payment. It should only be
CARD in this case.
pp_TokenizedCardNu 9113633378227
16 N Yes This token will be received to the
mber 378

example2019040
It is an Identifier which will be
pp_CorrelationId 40 AN Yes 4154431243571
unique for each request.
246
9e107d9d372bb Used to allow the Payment

pp_SecureHash 64 AN No 68bd81d3542a4 Gateway to check the integrity of
19d6 the transaction request.
pp_Brand MASTERCARD Brand of card i.e. Master or VISA
Expiry date of card in the format of
pp_Expiry 1120
MM/YY
Nature of card
pp_FundingMethod DEBIT
Possible values: DEBIT/CREDIT
CAPITAL ONE
pp_Issuer BANK (CANADA
BRANCH)
pp_LocalBrand MASTERCARD Brand of card i.e. Master or VISA
545721xxxxxx00
pp_cardNumber Masked Card No.
19
Validity status of the provided
pp_tokenStatus VALID
token
transaction success or failure. For a
pp_ResponseCode 3 AN Yes T00
complete list of response codes
refer to Appendix I.
The tokenization
operation was
successfully
processed
equal to 000.
8.3 Inquire Token

The generated token is sent to merchant through ITN after successful transaction. In case the token is not
received, merchant can inquire the same using Token Inquiry API, against the Transaction Reference No.
8.3.1 Version 1.0
Type POST
URL https://<baseApiUrl>/api/v1.0/tokenization/tokeninquiry
{
"pp_Language":"EN",
"pp_TxnRefNo":"T20191122153988",
Request "pp_MerchantId":"Merc0003",
"pp_Password":"0123456789",
"pp_SecureHash":"FD299444BA350BD96DB289B88284581CB002C8884"
}

{
"pp_Token":"",
"pp_ResponseCode":"",
Response
"pp_ResponseMessage":"",
"pp_SecureHash":""
}
Max.
Length
display the page.
Merchant by PG.
Password is assigned to each merchant
9e107d9d372bb6826
bd81d3542a419d69e
107d9d372bb6826bd
request.
81d3542a419d6
Token generated against the card
pp_Token 16 N Yes 9600921155993837
details provided in given transaction
pp_ResponseCod
3 AN Yes 000 response code of 000 represents
e
success. For a complete list of response
codes refer to Appendix I.
pp_ResponseMes
200 AN No Token Not Found This field will be mandatory for all cases
sage
where response code is not equal to
000.

Web Hook
9.1 Payment Status
Update (IPN)
After the completion of a transaction, PG will update the merchant regarding the transaction status. For this,
merchant will be required to expose a web service for Payment Gateway to receive instant payment
notification (IPN).
In cases when the Payment Status update service response is not received by the Payment Gateway
application on initial request (implying network glitches during the service calling or receiving response), the
update service will be invoked repeatedly for updating the payment status on the merchant for a configurable
number of times until the response is received.
At the merchant end, if the update service is called for the payment which is already updated, only an
acknowledgment response should be sent even if the response was sent earlier.
After retries have been exhausted Payment Gateway will stop sending update request to Merchant. In case
merchant needs to know the status of a transaction, it may invoke Payment Gateway’s inquiry service.
The signature of Payment Status Update Web Service which the Payment Gateway will call to update
transaction status is:
public string DoUpdatePaymentStatus(string pp_Version, string pp_TxnType, string pp_BankId, string

pp_ProductId, string pp_Password, string pp_TxnRefNo, string pp_TxnDateTime, string pp_ResponseCode,
string pp_ResponseMessage, string pp_AuthCode, string pp_SettlementExpiry, string
pp_RetrievalReferenceNo, string pp_SecureHash)
9.1.1 Request
API Version.
pp_TxnType 10 AN Yes OTC Over The Counter = OTC
Bank Id of the bank that has authorized the
transaction.
transaction type, otherwise it should be sent as
an empty field.
transaction type.

Product of Bank through which payment has

been performed. For e.g. Retail, Corporate.

request, this field will contain the same value.
Otherwise, ID of the product chosen by customer
at PG will be filled.
Password assigned to each merchant used to
authenticate the merchant by PG

‘/’ & ‘.’ request.
9th Sept, 2011

10:35:47 PM
pp_TxnDateTim The transaction date time that was provided at
14 N Yes will be sent as
e the time of transaction execution.
‘20110909203
547’
Response Code signifies the transaction
pp_ResponseCo execution status as received from the Bank. For
3 AN Yes 000
de complete details of possible response codes see
Appendix I.
The Response Message field shows message
corresponding to the response code. It is
concatenated with the response code. In case
pp_ResponseM
200 AN No Low Balance Response code is ‘000’ i.e. Success, this field will
essage
be all spaces.
This field will be mandatory for all cases where
response code is not equal to 000.
An identifying code issued by the issuing bank to
approve or deny the transaction. This will be
mandatory for successfully authorized
transactions.
9th Oct, 2011 indicating that if the merchant does not send a
10:35:47 PM Confirmation of the transaction by this time, the
pp_SettlementE
14N No will be sent as PG will mark the transaction as expired and the
xpiry
‘20111009223 Merchant will not be able to resume it.
547’ This will be mandatory for successfully
authorized transactions.
A unique number generated by the Payment
Gateway at the time of transaction processing.
pp_RetreivalRef The number may be stored and used for future
12 N Yes 000112233445
erenceNo reference.
9e107d9d372b
pp_SecureHash 64 AN No b6bb6826bd81
integrity of the transaction message.
d3542a419d6

9.1.2 Response
In response to the above IPN call, the merchant will send a string which will contain the response code and
error message, if any.

First three characters of the string denoting
Response Code 3 AN Yes 000 the response code. For list of response
codes see Appendix I.
The Response Message field shows message
corresponding to the response code. In case
Invalid Secure Response code is ‘000’ i.e. Success, this field
Response Message 200 AN No
Hash will be empty.
9e107d9d372b
b6826bd81d35
42a419d69e10
Secure Hash 64 AN No check the integrity of the transaction
7d9d372bb682
request.
6bd81d3542a4
19d6
9.2 Instant Token

Notification
(ITN)
Merchant will be required to expose a REST based API for Payment Gateway to get notified about the Tokenized
card status whenever any crucial operation is performed at the gateway like (CREATE or UPDATE or DELETE)
token.
In this way, the Merchant will be able to update the token in its system, on the basis of ApiOperation field
received in ITN call.
9.2.1 Version 1.0
Type POST
URL <Merchant URL to receive ITN>
{
"pp_CustomerID": "10000987",
"pp_TxnRefNo": "T20190327181830",
Request "pp_TokenizationResponseCode": "T00",
"pp_TokenizationResponseMsg": "The tokenization operation was successfully
processed",
"pp_CustomerCardNo": "512345******2346",

"pp_LastModificationDateTime: "20190327181830",
“pp_CorrelationId” : “Ref001”,
“pp_ApiOperation” : “CREATE”,
"pp_SecureHash": "413FCCAB4BEDBB352158232DB9A864B3CB707EBD06374"
}
{
Response "pp_ResponseMessage": "Success"
“pp_SecureHash” :” 063E4AADE24337CF8217B11564371CE22AD6B4129B9”
}
Max.
Length
API Version
used

(Provided by
pp_CustomerID 255 AN No Identifier address provided by
Merchant)
Merchant.

20 AN &
‘/’ & ‘.’
transaction.

Merchant by PG.
After the generation of the token,
merchant will be provided 3 digits
pp_TokenizationResp
3 AN Yes T00 response code to inform the status
onseCode
of request to save card details.
This response message is with

The tokenization
respect to the
pp_TokenizationResp operation was
300 A No pp_TokenizationResponseCode
onseMsg successfully
field as define above.
processed
512345******2 Masked Card number of the
pp_CustomerCardNu 346 customer who made the payment.
16 N Yes
mber
This field represents the customer

card expiry against tokenized card.
pp_CustomerCardExpi
4N Yes 0220 Example :
ry
0220 = Feburay 2020


pp_TokenizedCardNu 9113633378227
16 N Yes This token will be received to the
mber 378
This is the date time when the

pp_LastModificationD 2019032718183
14 N No token is updated/created the last
ateTime 0
time
example2019040
It is an Identifier which will be
pp_CorrelationId 40 AN Yes 4154431243571
unique for each request.
246
It indicates the operation

performed on token. Its possible
values are:
pp_ApiOperation 6A Yes CREATE
 CREATE
 DELETE
 UPDATE
9e107d9d372bb Used to allow the Payment
pp_SecureHash 64 AN No 68bd81d3542a4 Gateway to check the integrity of
19d6 the transaction request.
response code of 000 represents
pp_ResponseCode 3 AN Yes 000
response codes refer to Appendix
I.
Error details in case the
Not enough
transaction failed to be processed.
balance to
perform
transaction
equal to 000.

Calculating and Validating the Secure Hash

Secure Hash is used to detect whether a transaction request and response has been tampered
with. The Shared Secret generated for merchant at the time of its registration is added to the
transaction message and then an SHA256 algorithm is applied to generate a secure hash. The
secure hash is then sent to the receiving entity with the transaction message. Because the
receiving entity is the only other entity apart from transaction initiator that knows the shared
secret it recreates the same secure hash and matches it with the one in the request message. If
the secure hash matches, the receiving entity continues processing the transaction. If it doesn’t
match, it assumes that the transaction request has been tampered with and will stop processing
the transaction and send back an error message. This is a security feature to secure the
transaction and is recommended but its not mandatory.
The pp_SecureHash field is used for the SHA256 secure hash of initiator’s
10.1 How the
shared secret and the transaction request. The secure hash value is the
Secure Hash is Hex encoded SHA256 output of the transaction request or response
Created and fields. The order that the fields are hashed in are:
Verified
1. The Shared Secret (shared between the PG and a merchant), the
system generated value, is always first.
2. Then all transaction request fields are concatenated to the Shared Secret
in alphabetical order of the field name. The sort should be in ascending
order of the ASCII value of each field string. If one string is an exact
substring of another, the smaller string should be before the longer string.
For example, Card should come before CardNum.
3. Fields must not have any separators between them and must not include
any null terminating characters. For example, if the Shared Secret is
0F5DD14AE2E38C7EBD8814D29CF6F6F0, and the transaction request
includes the following fields:
Parameter Sample Values
pp_MerchantID MER123
pp_OrderInfo A48cvE28
pp_Amount 2995
Example of a Secure Hash Calculation
In ascending alphabetical order the transaction request fields inputted to the

SHA256 hash would be:
0F5DD14AE2E38C7EBD8814D29CF6F6F02995MER123A48cvE28

Merchant should also ensure that:
1. UTF-8 encoding should be used to convert the input from a printable

string to a byte array. Note that 7-bit ASCII encoding is unchanged for
UTF-8.
2. The hash output must be hex-encoded.
The SHA-256 HMAC is calculated as follows:

10.2 How is
SHA256- HMAC 1. The SHA-256 HMAC calculation includes all PP fields, that is, all fields
Calculated beginning with "PP"
2. All transaction fields are concatenated in alphabetical order of the

ASCII value of each field string with ‘&’ after every field except the
last field.
3. To this concatenated string, Shared Secret is prepended.
4. This string is first converted into UTF8 bytes and then it is converted
into ISO-8859-1 encoding.
5. The ISO-8859-1 string is then hashed using HMAC with UTF-8 encoded
Shared Secret as key.
6. The generated hash is then converted into hexadecimal
Example of a Secure Hash Calculation
Parameter Sample Values
pp_MerchantID MER123
pp_OrderInfo A48cvE28
pp_Amount 2995
In ascending alphabetical order the transaction request fields inputted to the

SHA256-HMAC hash would be:
0F5DD14AE2&2995&MER123&A48cvE28
Merchant should also ensure that:
7. UTF-8 encoding should be used to convert the input from a printable

string to a byte array. Note that 7-bit ASCII encoding is unchanged for
UTF-8.
The hash output must be hex-encoded.

Padding Rules
Following are the padding rules that should be followed for all the messages described in this
document:
Message Format Data Type Formatting

Fixed Length AN Postfix with spaces to reach
the prescribed length
Fixed Length N Prefix with 0

Web service invoke AN Not required
Web service invoke N Not required

Appendix I – Response Code
12.1 Payment Response

Code
Payment
Response Code Description
Response Code
000 Thank you for Using JazzCash, your transaction was successful.
001 Limit exceeded
002 Account not found
003 Account inactive
004 Low balance
014 Warm card
015 Hot card
016 Invalid card status
024 Bad PIN
055 Host link down
058 Transaction timed out
059 Transaction rejected by host
060 PIN retries exhausted
062 Host offline
063 Destination not found
066 No transactions allowed
067 Invalid account status
095 Transaction rejected
101 Invalid merchant credentials
102 Card blocked
103 Customer blocked
104 BIN not allowed for use on merchant
105 Transaction exceeds merchant per transaction limit
106 Transaction exceeds per transaction limit for card
107 Transaction exceeds cycle limit for card
108 Authorization of customer registration required
109 Transaction does not exist.
110 Invalid value for <field name>
111 Transaction not allowed on Merchant/Bank
112 Transaction Cancelled by User
113 Transaction settlement period lapsed
115 Invalid hash received
116 Transaction Expired
117 Transaction not allowed on Sub Merchant
118 Transaction not allowed due to maintenance
119 Transaction is awaiting Reversal
120 Delivery status cannot be updated
121 Transaction has been marked confirmed by Merchant
122 Reversed

124 Order is placed and waiting for financials to be received over the counter.
125 Order has been delivered
126 Transaction is disputed
127 Sorry! Transaction is not allowed due to maintenance.
128 Awaiting action by scheme on Dispute
129 Transaction is dropped.
131 Transaction is Refunded.
132 Sorry! The selected transaction cannot be refunded.
134 Transaction has been timed out.
135 Invalid BIN was entered for discount.
156 Wallet with provided combination of CNIC & Mobile number does not exist.
157 Transaction is pending.(for Mwallet and MIgs)
199 System error
200 Transaction approved – Post authorization
210 Authorization pending
Sorry! Your transaction could not be processed at this time, please try again
401
after few minutes.
402 Your transaction was declined by your bank, please contact your bank
403 Your transaction has timed out, please try again
Your transaction was declined because your card is expired, please use a valid
404
card
405 Your transaction was declined because of insufficient balance in your card
Sorry! Your transaction could not be processed at this time due to system
406
error, please try again after few minutes
Sorry! Your transaction could not be processed at this time due to internal
407
system error, please try again after few minutes
408 Your bank does not support internet transactions, please contact your bank
409 Transaction declined - do not contact issuer
You have aborted the transaction, Our team will contact you shortly to assist
410
you or you can share your feedback with us via emailing us at :
Sorry! Your transaction is blocked due to risk, please use any other card and try
411
again
You have aborted the transaction, Our team will contact you shortly to assist
412
you or you can share your feedback with us via emailing us at :
414 Sorry! Your transaction was declined, please contact your bank
415 Your 3D Secure ID verification was failed, please use correct ID and try again.
Your CVV verification was failed, please use correct CVV and try again, click the
416
help button “?” In CVV tab to find out the details of CVV.
417 Order locked - another transaction is in progress for this order
Your Card is not enrolled in 3D secure, please contact your bank and active
419
your 3D secure ID
421 Your retry limit is exhausted, please contact your bank
422 Your transaction was declined due to duplication, please try again
Your transaction was declined due to address verification failed, please try
423
again
Your transaction was declined due to wrong CVV, please try again with correct
424
CVV, click the help button “?” In CVV tab to find out the details of CVV

425 Transaction declined due to address verification and card security code
426 Transaction declined due to payment plan, please contact your issuer bank
Your transaction has not been processed this time, please try again or contact
429
your issuer bank.
430 Request_rejected
431 Server_failed
432 Server_busy
433 Not_enrolled_no_error_details
434 Not_enrolled_error_details_provided
435 Card_enrolled
436 Enrollment_status_undetermined_no_error_details
437 Enrollment_status_undetermined_error_details_provided
438 Invalid_directory_server_credentials
439 Error_parsing_check_enrollment_response
440 Error_communicating_with_directory_server
441 Mpi_processing_error
442 Error_parsing_authentication_response
443 Invalid_signature_on_authentication_response
444 Acs_session_timeout
446 Authentication_failed
448 Card_does_not_support_3ds
449 Authentication_not_available_no_error_details
450 Authentication_not_available_error_details_provided
Transaction failed. This response code will be sent when the transaction fails
999
due to some technical issue at PG or Bank’s end.
12.2 Tokenization
Response Code
Tokenization
Response Code Description
Response Code
T00 The tokenization operation was successfully processed
T99 The tokenization operation was declined or rejected by the gateway, acquirer
or issuer
T98 The tokenization operation resulted in an internal error and hence cannot be
processed
T97 The tokenization operation resulted in an external error and hence cannot be
processed
T95 Token not found
T89 The tokenization operation resulted in an internal error,while inserting token
and hence cannot be processed
T88 Request validation failed
110 Validation Errors at the time of tokenization with complete error details
T49 Tokenized Card Number Provided is Invalid

T59 The delete token operation resulted in an internal error and hence cannot be
processed
T48 Tokenized Card Number Provided is Expired.
T89 The create token operation resulted in an internal error and hence cannot be
processed
144 The customer has selected to discontinue the transaction.
198 Transaction cannot be processed because customer has selected to delete the
Expired card.

Appendix II – Fixed Length

In response to a service call, the output returned will always be a fixed length string, the details of
which are mentioned below.
In case if any numeric value is less than the required length or empty it will be left padded with zeros.
In case if any alpha numeric field is less than the required length or empty it will be right padded with
spaces.

Payment Gateway Integration Guide For Merchants-V4.6

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Payment Gateway Integration Guide For Merchants-V4.6

Uploaded by

Copyright:

Available Formats

INTEGRATION GUIDE FOR MERCHANTS

This is unpublished, confidential document of TPS Pakistan Pvt Ltd.

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - ii -

Date Author Status Change Reference

Added new sections for 1.1.1.1.1.1 Added: Section 9 and 7.3

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - iii -

Added tokenization description for payment

Rename response code field of existing table

Add new table for Tokenization Response

Adding Instant Token Notification API.

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - iv -

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. -v-

7.1 DEBIT/CREDIT CARD PAYMENT .............................................................................. 32

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. - vi -

The Payment Gateway’s Payment Portal provides the online merchants

The document is intended for application developers and business

A Merchant Portal by Payment gateway is also available to all merchants

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 1 of 85

The online user experience will be divided between two portals:

1. Merchant’s Web site

Merchant’s Web Site:

Customer will be presented with Payment Method Selection covering:

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 2 of 85

2.1.1 Debit/Credit Card

2.1.1.1 Offline Pay Integration

2.1.1.2 Direct Pay Integration

2.1.2 Mobile Wallet

Note: MPIN will be sent by CPS to the customer.

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 3 of 85

2.1.3 Over the Counter

2.1.4 Via Account

Bank: Customer will be asked to select bank of his/her account

2.1.5 Direct Debit

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 4 of 85

2.2.1 Payment Status Inquiry

2.2.2 Token Inquiry

2.3 Status Update

2.3.1 Payment Status Update

2.3.2 Delivery Status Update

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 5 of 85

2.4.1 Instant Payment Notification (IPN)

2.4.2 Instant Token Notification (ITN)

2.5 Token Operation

2.5.1 Delete Token

2.5.2 Retreive Token

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 6 of 85

Merchant Setup Process

There are 2 ways of registering merchant at Payment Gateway:

a. Payment Gateway Payment Portal Integration Guide

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 7 of 85

Payment Gateway Test System

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 8 of 85

Payment Integration via Payment Portal

<input type="hidden" id="pp_Version" value="1.0">

5.1 Version 1.1

Parameter Max. Length Mandatory Sample Values Remarks

Payment Portal Version.

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 9 of 85

Debit/Credit Card = MIGS

Fixed values: ‘RETL’, ‘CORP’

COPYRIGHT  2021 BY TPS Paksitan Pvt Ltd. Page 10 of 85

9th Oct, 2011

255 AN and xxxx will be replaced by any value from