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)
• API Testing
• Hosted Payment Checkout(V1.1)
• Hosted Payment Checkout(V2.0)
• Mobile SDK

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
• 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 Card Payment:
<script> function submitForm() { document.jsform.submit(); } </script> <form name="jsform" method="post" action='@System.Configuration.ConfigurationManager.AppSettings["PAYMENT_PORTAL_URL"]'> <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 Account:
<script> function submitForm() { document.jsform.submit(); } </script> <form name="jsform" method="post" action='@System.Configuration.ConfigurationManager.AppSettings["PAYMENT_PORTAL_URL"]'> <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='@System.Configuration.ConfigurationManager.AppSettings["PAYMENT_PORTAL_URL"]'> <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

• 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 (V1.1)

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:

Hosted Payment Checkout (V2.0)

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.

• cordova-plugin-whitelist
• cordova-plugin-inappbrowser

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: 'TestRafayKhan7', //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.