JazzCash Documentation v4.2

Features

Payment Solutions

JazzCash Payment Gateway allows merchants to accept payments for their businesses in secure & easy to use manner. Our integration guide provides comprehensive details for seamless integration of JazzCash Payment Gateway.

  • Debit/ Credit Card

    The Payment Gateway allows to perform card transaction (Credit/Debit) via any channel like Page Redirection,Api or Hosted Pay.There are two types of card payment :

    Direct Pay : It is a mode where the Authorize and Capture operations are completed at the real time.

    Authorzie Capture : It is a mode where the Authorize and Capture operations are completed at the different time.

  • Mobile Wallets

    This payment mode is provided via the online web page hosted by the Payment Gateway. Merchant provides the transaction details (transaction amount, order number, etc.) to the Payment Page. Payment page takes the mobile account details and debits it.

  • Voucher Payment

    Voucher Payment enables customers to make a transaction by paying through JazzCash Agents. Customer receives a 12 digit Voucher Number with required amount to be paid via SMS.

Supported card scheme

JazzCash, to entertain both its valuable customers and merchants provides extensive support of card payment and is integrated with MasterCard Payment Gateway Services – MPGS. JazzCash uses the features of MPGS as it is being continuously enhanced to provide a unique and superior global payments solution for merchants, banks and partners.

Following are some benefits:

  • Provides full control on the entire payment experience.
  • Integrates with any application, website, call center, billing, Interactive Voice Response (IVR).
  • Allows the merchant to communicate directly with the MasterCard Payment Gateway and then receive a real-time response to the API call both via JazzCash. This is a synchronous connection and the payer does not leave the merchant’s application.
  • Supports advanced MasterCard Payment Gateway operations such as capture, refund, void and queries where the payer is not directly involved.

Tokenization

JazzCash, allows merchants to store card payment details in exchange for a token against their customer profile. The token will be generated by the MPGS (MasterCard Payment Gateway Solution) on Jazz Cash request, after a complete authorization process. Hence the token will be replaced the card details in the transaction request sent to the gateway.

Following are some benefits:

  • Since the gateway handles the payment details collected from the payer thereby reducing your PCI compliance obligations.
  • If the token is stored with the payer/customer data, it may be used when the payer/customer returns to make another purchase.
  • Improve payment processing time for the customer,since he will not need to enter complete card details over and over again
  • Merchant will always notify by the gateway whenever any crucial operation performed against the token

Additionally merchant will have a configurable option to apply an extra security for the returning customer transaction like CVV or Check 3DS verification for each request including 3DS Limit Profile rules. Further, some independent tokenized Api will also available for integration Like Retrieve and Delete Token. Example if customer wants to delete his/her store card details then merchant can request gateway securely delete token stored against the card.

3D Secure

3-Domain Secure™ (3-D Secure or 3DS) authentication is designed by MPGS to protect online purchases against credit card fraud by allowing the e-commerce website to authenticate the payer before submitting an Authorization or Pay transaction. 3DS authentication works by redirecting the payer to their card issuer where they enter a previously registered password.

The JazzCash via MPGS supports 3DS authentication using MasterCard SecureCode™, Verified by Visa™, J/Secure™, American Express SafeKey™, and Diners Club ProtectBuy™.

Hashing Scheme


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 HMAC-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 it’s not mandatory.
On sandbox home screen, an online hash calculation reference has been provided under the Hash Calculator feature so that merchant can also verify the calculated hash.

How is HMAC-SHA256 calculated?

  • The SHA-256 HMAC calculation includes all PP fields, that is, all fields beginning with "PP"
  • All transaction fields are concatenated in alphabetical order of the ASCII value of each field string with ‘&’ after every field except the last field.
  • To this concatenated string, Shared Secret is prepended.
  • This string is first converted into UTF8 bytes and then it is converted into ISO-8859-1 encoding.
  • The ISO-8859-1 string is then hashed using HMAC with UTF-8 encoded Shared Secret as key.
  • The generated hash is then converted into hexadecimal

    • Let us see the example

    Consider the following payment parameters and their respective values and assuming the shared secret as '0F5DD14AE2':

    Parameter Sample Values
    pp_MerchantID MER123
    pp_OrderInfo A48cvE28
    pp_Amount 2995

    In ascending alphabetical order and separating each value with '&', the transaction request fields would be: 2995&MER123&A48cvE28

    After prepending the shared secret to the message, the transaction request fields would be: 0F5DD14AE2&2995&MER123&A48cvE28

    Now calculating the hash with the hashing scheme 'HMAC-SHA256' with the secret key 0F5DD14AE2

    Resultant hash: c7689cda7474eb1adcd343fd0c0b676bad0ba66361cc46db589bdb0da4c1c867

    Merchant should also ensure that UTF-8 encoding is used to convert the input from a printable string to a byte array. Also Note that 7-bit ASCII encoding is unchanged for UTF-8.

    IPN web hook

    To entertain the merchant with the useful features, JazzCash provides the merchant a way to be notified if it’s payment is marked successful. To integrate with it, merchant will be required to expose a transaction status update SOAP web service for Payment Gateway to update status of transactions which are not executed instantaneously.

    There is a possibility that at the time of voucher transaction creation, the transaction is not executed right away but requires certain procedure to actually process. This is a common scenario for voucher based transactions. In such cases, when Payment Gateway generates the voucher, customer has to visit the JazzCash outlet for the payment of voucher, Payment Gateway will in turn call the merchant Status update SOAP web service to update the status at merchant’s end against the voucher number.

    Instant payment notifications can be send in real time or scheduled to be send from windows service depending upon the configuration of merchant.

    If real time IPN is enable for merchant then IPN will send in real time to the SOAP webservice of merchant. If JazzCash received failure response in real time IPN then IPN will be schedule to send from windows service.

    In windows service, JazzCash will send instant payment notifications to the SOAP webservice of merchant. If failure response received from merchant then it will retry 3 times with some delay between each try.

    Merchant have to send string response in specific format i.e. 3 digits ResponseCode concate with 200 letters ResponseMessage with Hash of response code and message if hashing is enable for merchant. For successfull response, merchant have to send '000' as response code.

    ITN web hook

    To entertain the merchant with the useful feature of tokenization, JazzCash provides the merchant a way to be notified about the crucial operation performed against the token like Create/Update and Delete. To integrate with it, merchant will be required to expose a Rest based Api for Payment Gateway to update status about the token.