The Basics


Getting Started

JazzCash enables quick and easy integration for its merchants with our next generation payment gateway. Merchants can Self-Register, Test transactions and Go-Live to start accepting payments. JazzCash offers a variety of integration modes depending on merchant’s functionality.

To start integration, follow these steps:

  • 1. Get Started with a free account and Generate Credentials.
  • 2. Start testing with different modes of integration. You will be guided through each integration mode individually.
  • 3. Go through a comprehensive guide Go Live to help familiarize yourself with the on-boarding process.

Generate credentials

To start testing, provide a Return URL and generate credentials.

Mode Selection

JazzCash allows merchants to integrate their website with our payment gateway via following modes:

HTTP POST (Page Redirection)

For an HTTP Post mode of integration, merchant can choose from Custom Development or Plugins while developing his e-commerce website.

  • Custom Development 1. The merchant may choose to develop a customized website using online resources including different platforms available over the World Wide Web. The following criteria has to be followed in order to further proceed with the integration:

  • The merchant would then be required to select a transaction type from the below mentioned list:
  • i. Card Payment
  • ii. Mobile Account
  • iii. Voucher Payment
  • iv. Direct Debit
  • After selecting the preferred transaction type, a list of codes become available for the merchant to copy (a ‘copy’ button is also visible on the bottom left).
  • For Direct Debit:
    <script> function submitForm() { document.jsform.submit(); } </script> <form name="jsform" method="post" action="https://payments.jazzcash.com.pk/CustomerPortal/transactionmanagement/merchantform"> <input type="hidden" name="pp_Version" value="1.1"> <input type="hidden" name="pp_TxnType" value="DD"> <input type="hidden" name="pp_Language" value="EN"> <input type="hidden" name="pp_MerchantID" value=""> <input type="hidden" name="pp_SubMerchantID" value=""> <input type="hidden" name="pp_Password"> <input type="hidden" name="pp_BankID" value="TBANK"> <input type="hidden" name="pp_ProductID" value="RETL"> <label class="">Ref Number: </label> <input type="text" name="pp_TxnRefNo" value="T2017061995819"> <label class="">Amount: </label> <input type="text" name="pp_Amount" value="1000"> <input type="hidden" name="pp_TxnCurrency" value="PKR"> <input type="hidden" name="pp_TxnDateTime" value="2017061995819"> <label class="">Bill Reference: </label> <input type="text" name="pp_BillReference" value="billRef"> <label class="">Description: </label> <input type="text" name="pp_Description" value="Description of transaction"> <input type="hidden" name="pp_TxnExpiryDateTime" value="2017062095819"> <label class="">Return URL: </label> <input type="text" name="pp_ReturnURL"> <input type="hidden" name="pp_SecureHash" value=""> <input type="hidden" name="ppmpf_1" value="1"> <input type="hidden" name="ppmpf_2" value="2"> <input type="hidden" name="ppmpf_3" value="3"> <input type="hidden" name="ppmpf_4" value="4"> <input type="hidden" name="ppmpf_5" value="5"> <button type="button" onclick="submitForm()">Submit</button> </form>
    For Card Payment:
    <script> function submitForm() { document.jsform.submit(); } </script> <form name="jsform" method="post" action="https://payments.jazzcash.com.pk/CustomerPortal/transactionmanagement/merchantform"> <input type="hidden" name="pp_Version" value="1.1"> <input type="hidden" name="pp_TxnType" value="MIGS"> <input type="hidden" name="pp_Language" value="EN"> <input type="hidden" name="pp_MerchantID" value=""> <input type="hidden" name="pp_SubMerchantID" value=""> <input type="hidden" name="pp_Password"> <input type="hidden" name="pp_BankID" value="TBANK"> <input type="hidden" name="pp_ProductID" value="RETL"> <label class="">Ref Number: </label> <input type="text" name="pp_TxnRefNo" value="T2017061995819"> <label class="">Amount: </label> <input type="text" name="pp_Amount" value="1000"> <input type="hidden" name="pp_TxnCurrency" value="PKR"> <input type="hidden" name="pp_TxnDateTime" value="2017061995819"> <label class="">Bill Reference: </label> <input type="text" name="pp_BillReference" value="billRef"> <label class="">Description: </label> <input type="text" name="pp_Description" value="Description of transaction"> <input type="hidden" name="pp_TxnExpiryDateTime" value="2017062095819"> <label class="">Return URL: </label> <input type="text" name="pp_ReturnURL"> <input type="hidden" name="pp_SecureHash" value=""> <input type="hidden" name="ppmpf_1" value="1"> <input type="hidden" name="ppmpf_2" value="2"> <input type="hidden" name="ppmpf_3" value="3"> <input type="hidden" name="ppmpf_4" value="4"> <input type="hidden" name="ppmpf_5" value="5"> <button type="button" onclick="submitForm()">Submit</button> </form>
    For Mobile Voucher:
    <script> function submitForm() { document.jsform.submit(); } </script> <form name="jsform" method="post" action="https://payments.jazzcash.com.pk/CustomerPortal/transactionmanagement/merchantform"> <input type="hidden" name="pp_Version" value="1.1"> <input type="hidden" name="pp_TxnType" value="MWALLET"> <input type="hidden" name="pp_Language" value="EN"> <input type="hidden" name="pp_MerchantID" value=""> <input type="hidden" name="pp_SubMerchantID" value=""> <input type="hidden" name="pp_Password"> <input type="hidden" name="pp_BankID" value="TBANK"> <input type="hidden" name="pp_ProductID" value="RETL"> <label class="">Ref Number: </label> <input type="text" name="pp_TxnRefNo" value="T2017061995819"> <label class="">Amount: </label> <input type="text" name="pp_Amount" value="1000"> <input type="hidden" name="pp_TxnCurrency" value="PKR"> <input type="hidden" name="pp_TxnDateTime" value="2017061995819"> <label class="">Bill Reference: </label> <input type="text" name="pp_BillReference" value="billRef"> <label class="">Description: </label> <input type="text" name="pp_Description" value="Description of transaction"> <input type="hidden" name="pp_TxnExpiryDateTime" value="2017062095819"> <label class="">Return URL: </label> <input type="text" name="pp_ReturnURL"> <input type="hidden" name="pp_SecureHash" value=""> <input type="hidden" name="ppmpf_1" value="1"> <input type="hidden" name="ppmpf_2" value="2"> <input type="hidden" name="ppmpf_3" value="3"> <input type="hidden" name="ppmpf_4" value="4"> <input type="hidden" name="ppmpf_5" value="5"> <button type="button" onclick="submitForm()">Submit</button> </form>
    For Voucher Payment:
    <script> function submitForm() { document.jsform.submit(); } </script> <form name="jsform" method="post" action="https://payments.jazzcash.com.pk/CustomerPortal/transactionmanagement/merchantform"> <input type="hidden" name="pp_Version" value="1.1"> <input type="hidden" name="pp_TxnType" value="OTC"> <input type="hidden" name="pp_Language" value="EN"> <input type="hidden" name="pp_MerchantID" value=""> <input type="hidden" name="pp_SubMerchantID" value=""> <input type="hidden" name="pp_Password"> <input type="hidden" name="pp_BankID" value="TBANK"> <input type="hidden" name="pp_ProductID" value="RETL"> <label class="">Ref Number: </label> <input type="text" name="pp_TxnRefNo" value="T2017061995819"> <label class="">Amount: </label> <input type="text" name="pp_Amount" value="1000"> <input type="hidden" name="pp_TxnCurrency" value="PKR"> <input type="hidden" name="pp_TxnDateTime" value="2017061995819"> <label class="">Bill Reference: </label> <input type="text" name="pp_BillReference" value="billRef"> <label class="">Description: </label> <input type="text" name="pp_Description" value="Description of transaction"> <input type="hidden" name="pp_TxnExpiryDateTime" value="2017062095819"> <label class="">Return URL: </label> <input type="text" name="pp_ReturnURL"> <input type="hidden" name="pp_SecureHash" value=""> <input type="hidden" name="ppmpf_1" value="1"> <input type="hidden" name="ppmpf_2" value="2"> <input type="hidden" name="ppmpf_3" value="3"> <input type="hidden" name="ppmpf_4" value="4"> <input type="hidden" name="ppmpf_5" value="5"> <button type="button" onclick="submitForm()">Submit</button> </form>
  • i. The merchant copies and pastes the codes in the custom created website.
  • ii. This generates a mockup HTTP POST request for payment via page redirection.
  • iii. The merchant can then view the call log to track the request's validation status.
  • Plugins 2. JazzCash also offers a portfolio of plugins to choose from. Merchants only need to download their preferred plugin to start integration. These plugins include:

API Testing

For API testing, merchant will follow the following steps:

1. Merchant will select from list of available options as given below:

  • i. Mobile Account
  • ii. Voucher Payments
  • iii. Card (VISA/Mastercard)
    • i. Pay
    • ii. Authorize
    • iii. Capture
    • iv. Refund
    • v. Void
  • iv. Status Inquiry
    • i. Transaction Status Inquiry
    • ii. Transaction Status Update

2. An API URL will be visible to the merchant using which the merchant can also invoke the API from other channels.

3. In the Random Request Parameters box, the following information needs to be provided by the merchant:

  • a. Transaction Reference Number
  • b. Amount
  • c. Mobile Number

4. JSON Payload will be updated according to the given information. Once the merchant hits ‘run’ button, the API will give its response.

Hosted Payment Checkout

Hosted Payment makes the checkout process seamless and consistent with the merchant’s ecommerce website. The biggest advantage of hosted checkout is that the merchant does not need to save any customer’s information which ultimately eradicates a number of PCI reservations regarding the storage of buyer’s confidential and sensitive data.

Merchant will follow below mentioned steps:

  • Select preferred code language from the drop-down list.
  • A chunk of code appears in a box below which the merchant needs to copy in order to begin testing.
  • Once the testing completes, the merchant can see the results on their own eCommerce website.
  • Looking forward the change in technology and cutting edge features being developed in 21st century, JazzcCash adopts the versatile approach and provide the ease of integration via Hosted Payment Checkout for the:

  • MERCHANTS USING PHP
  • MERCHANTS USING .NET MVC
  • How to integrate Hosted Payment Checkout using PHP?

      1. Create a directory on your root folder with the name "hpc".

      2. Save markup1 with the name "action_POST.php" and place it in "hpc" folder.

      3. Save markup2 with any name of your choice and place it in "hpc" folder.

      4. Run the markup2 file from your local server.

      PHP Markup 1:
      <!--?php // Retrieve order echo 'Hello'; $_ResponseMessage = $_REQUEST['pp_ResponseMessage'] ; $_ResponseCode = $_REQUEST['pp_ResponseCode']; $_InstrToken = $_REQUEST['pp_InstrToken']; $_RRN = $_REQUEST['pp_RetreivalReferenceNo']; echo $_ResponseMessage; echo $_ResponseCode; echo $_InstrToken; echo $_RRN; ?-->
      PHP Markup 2:
      { "Frequency": "SINGLE", "InstrToken": "", "Version": "1.1", "MerchantID": "", "Language": "EN", "TxnType": "MPAY", "SubMerchant": "", "Password": null, "TxnRef": "<?php echo(json_encode($_TxnRefNumber)); ?>", "Amount": "<?php echo(json_encode($_AmountTmp)); ?>", "DiscountedAmount": "", "DiscountBank": "", "TxnCurrency": "PKR", "TxnDate": "<?php echo(json_encode($TxnDateTime)); ?>", "TxnExpiry": "", "BillReference": "ref bill", "Description": "Hello", "ReturnURL": null, "mpf_1": "", "mpf_2": "", "mpf_3": "", "mpf_4": "", "mpf_5": "", "SecureHash": "" }
      How to integrate Hosted Payment Checkout using .NET MVC?

      1. Copy content from Mark up 1 … it is a sample form that will process payment. Change form contents according to instructions mentioned in comments in mark up 1.

    • Merchant will include the JS file for relevant transaction type payment in that form
    • Merchant will initialize payload required by pay axis to process payment on the form that will submit the payment request and call populatePayaxisFields
    • Merchant will define action to be redirected to after Pay axis processes the payment in form tag of html
    • A submit button is placed in Merchant form
    • 2. Create a server side action on Controller as defined in step 3. Markup 2 shows the sample action. This action takes the response after request submission in terms of form collection and sets it in Session or a model if Model binding is being used.

      3. Copy content from Mark up 3 and place it in a view on which you wish to show response that was set in above step. This view contains html that holds response by processing the request in markup 1

      Markup 1:
      @{ var tDate = DateTime.Now.ToString("yyyyMMddHHmmss"); var Txn = "T" + tDate; var amount = "5600"; } <html> <head> <script type="text/javascript" src="https://code.jquery.com/jquery-2.2.4.min.js"></script> <!--Merchant will include the JS file for relevant transaction type payment in that form--> <script type="text/javascript" src="~/Scripts/ChkOut.js"></script> <script type="text/javascript"> $(document).ready(function () { var pp_payload = { Frequency: "SINGLE", InstrToken: "", Version: "1.1", MerchantID: "MC0021", Language: "EN", TxnType: "MPAY", SubMerchant: "", Password: "z39v3s4czy", TxnRef: "@Txn", Amount: "@amount", DiscountedAmount: "", DiscountBank: "", TxnCurrency: "PKR", TxnDate: "@tDate", TxnExpiry: "", BillReference: "", Description: "", ReturnURL: "", mpf_1: "", mpf_2: "", mpf_3: "", mpf_4: "", mpf_5: "", SecureHash: "" }; //Merchant will initialize payload required by payaxis to process payment on the form that //will submit the payment request and call populatePayaxisFields. populatePayaxisFields(pp_payload); $('.errorDiv').hide(); }); </script> </head> <body> <h2>Check Out Fields</h2> <!--Merchant will define action to be redirected to after Pay axis processes the payment in form tag of html. --> <form id="onlineform" action="@Url.Action("Index","Purchase")" method="post"> <div id="PayaxisFields"></div> <div id="merchant"> <br /> <br /> <input type="text" placeholder="Delivery Address" name="pp_Addr" id="pp_Addr"><br /> <input type="text" placeholder="Opt Field 1" name="pp_op1" id="pp_op1"><br /> <input type="text" placeholder="Opt Field 2" name="pp_op2" id="pp_op2"><br /> </div> @if (Convert.ToBoolean(Session["DoShow"]) == true) { <div class="responseDiv"> <p> <label>Response Message: </label> <span class="bar"></span> @{ var value = Session["rmsg"] == null ? "-" : Session["rmsg"]; @value; } </p> <p> <label>Response Code: </label> <span class="bar"></span> @{ value = Session["rcode"] == null ? "-" : Session["rcode"]; @value; } </p> <p> <label>Instrument Token: </label> <span class="bar"></span> @{ value = Session["rit"] == null ? "-" : Session["rit"]; @value; } </p> <p> <label>RRN of request: </label> <span class="bar"></span> @{ value = Session["RRN"] == null ? "-" : Session["RRN"]; @value; } </p> </div> } <!--A submit button is placed in Merchant form --> <button class="login" id="buttonsubmitPay" type="submit">Continue</button> </form> </body> </html>
      Markup 2:
      [HttpPost] public ActionResult Index(FormCollection Fc) { string Source = ControllerName + "Index"; Session["rmsg"] = Fc["pp_ResponseMessage"]; Session["rcode"] = Fc["pp_ResponseCode"]; Session["rit"] = Fc["pp_InstrToken"]; Session["RRN"] = Fc["pp_RetreivalReferenceNo"]; return View(); }
      Markup 3:
      <div class="responseDiv"> <p> <label>Response Message: </label> <span class="bar"></span> @{ var value = Session["rmsg"] == null ? "-" : Session["rmsg"]; @value; } </p> <p> <label>Response Code: </label> <span class="bar"></span> @{ value = Session["rcode"] == null ? "-" : Session["rcode"]; @value; } </p> <p> <label>Instrument Token: </label> <span class="bar"></span> @{ value = Session["rit"] == null ? "-" : Session["rit"]; @value; } </p> <p> <label>RRN of request: </label> <span class="bar"></span> @{ value = Session["RRN"] == null ? "-" : Session["RRN"]; @value; } </p> </div>

      Mobile SDK

      Prerequisites

      Following cordova plugins are required for the 'Pay with JazzCash' button to work. Make sure you install them before integrating the button.

      Getting Started

      Copy the jazzcash-button.min.js file into your project directory e.g. MyApp/www/scripts.

      Now add the following script tag to the html file in which you want to use the 'Pay with JazzCash' button e.g. product-checkout.html.

      <script type="text/javascript" src="Scripts/jazzcash-button.min.js"></script>

      Also add or replace the following meta tag in the head of the html file.

      <meta http-equiv="Content-Security-Policy" content="default-src * gap://ready file:; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline' 'unsafe-eval'">
      Adding Button

      Create an empty <div></div> tag where you want the button to appear and give it an id.

      <div id="button"></div>

      Now in the onLoad() function of your page, initialize the button by calling jazzCashButton.init() passing the div id and payment configuration.

      //Sample PaymentConfig object var paymentConfig = { pgUrl: 'https://jazzcash.com.pk/CustomerPortal/TransactionManagement/DoTransactionViaSDK/', // Merchant specific payment gateway base url hmacSalt: '0123456789', // HMAC hash key merchantId: 'TestMerc0003', //Merchant id subMerchantId: 'TestMerc0005', //Sub Merchant id [Optional] merchantPassword: '0123456789', //Merchant password transactionRefNumber: 'T20170307171825', //Transaction reference number amount: '875045', //Transaction amount (Format: 875045 for Rs. 8,750.45) discountedAmount: '765045', //Discounted amount (Format: 765045 for Rs. 7,650.45) [Optional] discountedBank: '765045', //Discount bank [Optional] transactionDateTime: '20170302112731', //Transaction date time (Format: YYYYMMddHHmmss) invoiceRefNumber: 'INV4455454', //Invoice number description: 'iPhone 7 Plus - 32GB', //Transaction description expiryDateTime: '20170309112731' //Transaction expiry date time (Format: YYYYMMddHHmmss) }; //Initialize button //Pass div id and payment configuration as arguments jazzCashButton.init('button', paymentConfig);
      Transaction Status

      JazzCash button provides the following two callbacks for transaction completion status.

      //Consume the callbacks in your code jazzCashButton.onSuccess = function (transactionResponse) { // Code to execute if transaction is completed successfully }; jazzCashButton.onFailure = function (transactionResponse) { // Code to execute if transaction failed }; //TransactionResponse object var transactionResponse = { transactionReferenceNumber: 'T20170307171825', //Transaction reference number responseCode: '200', //Response code responseDescription: 'Transaction successful', //Response message rrn: '56541242448' //Retreival Reference Number };
      Download

      Click on the image provided below to download the 'Pay with JazzCash' button library.

      Cordova

      Transaction testing

      To start testing transactions, the merchants can signup for free on the Sandbox Portal. They can log in and proceed with the integration process. Our testing simulator is configured to generate predictable results based on the transaction request and cart details provided. Click here to signup on the Sandbox Portal.

      Going live

      1. Merchant Registration

      Click on the “Get Started” button and signup as a merchant. The merchant is directed to a pop-up with multiple options for easy signup. After signup, merchant will receive an email with a link for registration.

      The above email will be received by the merchant along with a link to follow. As soon as the merchant hits the link, a screen appears asking for merchant's contact details to proceed.

      The merchant registration form requires the following information from the merchant:

      • • Merchant Name
      • • Merchant contact person name
      • • Merchant contact person email address
      • • Merchant contact person phone number
      • • Merchant contact person designation number
      • • Merchant contact person category
      • • Password
      • • Merchant Phone Number

      If all goes smoothly, the merchant gets the successufhl response message displayed on the screen.

      2. Merchant Verification

      First Step:

      To proceed with the registration, the merchant needs to sign-in with the registered username and password. There are three steps that lead to the verification of the merchant:

      • • Basic Information
      • • Documents Uploading
      • • Account Verification

      Second Step:

      Merchant will upload required documents. Step by step guide & sample documents will be available for merchant’s ease. The merchant can either upload the documents one by one, in multiple days or simply upload all the documents in one go and send for authentication. The uploaded documents can be deleted or replaced only before passing authentication.

      3. Merchant Types

      Following three merchant types are available and for every merchant, the number and type of documents vary.

      • i. Sole Proprietor
      • ii. Partnership
      • iii. Private/ Public Limited Company
      • i. Sole Proprietor

      • Sole proprietorship is an unincorporated business owned and run by one individual with no distinction between the business and the owner.

        Following documents are required for this category:

        • 1. Photocopy of CNIC
        • 2. Declaration of Sole Proprietorship, Account Opening Request, NTN Number

      • ii. Partnerships

      • Partnership is an arrangement where the parties agree to cooperate in order to advance their mutual interests and benefits. The partners in a partnership may be individuals, businesses, interest-based organizations, schools, governments and combinations of any of these entities. Following documents are required for this category:

        • 1. Photocopies of CNICs of all the partners
        • 2. Attested copy of ‘Partnership Deed’ duly signed by all partners
        • 3. Authority letter from all partners (original)

      • iii. Private and Public Limited Companies

      • Private and Public Limited Companies can be taken as business structures combining the pass-through taxation of a partnership or sole proprietorship with the limited liability of a corporation. Following documents are required for this category:

        • 1. Resolution of Board of Directors for opening of account
        • 2. Memorandum and Articles of Association
        • 3. Certificate of Incorporation
        • 4. Certificate of Commencement of Business
        • 5. Photocopies of CNIC of all the directors
        • 6. List of Directors on ‘Form-A/Form-B’ issued under Companies Ordinance 1984
        • 7. List of Directors on Form-29
        • 8. Account opening requisition on business letterhead
        • 9. NTN Number

      Once all the documents have been authenticated by the bank teams, merchant receives an email containing the status of the verification request. In case of any discrepancy, merchant is requested to upload the required document again.