JazzCash Documentation v3.9

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

    This payment mode is provided via 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 user’s card details, performs online transaction authorization and returns the response to the merchant’s website.

  • 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.

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 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 web service to update the status at merchant’s end against the voucher number.