JazzCash Hosted Payments — setup and reference

Module and release scope

This guide covers JazzCash Hosted Payments 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Environment	select	Yes	Default: "sandbox" Choices: sandbox = Sandbox, live = Live
merchant_id — Merchant ID	text	Yes	Use the account-specific value described below.
password — Merchant password	secret	Yes	Use the account-specific value described below.
integrity_salt — Integrity salt / hash key	secret	Yes	Use the account-specific value described below.
transaction_type — Approved hosted payment instrument	select	Yes	Default: "MWALLET" Choices: MWALLET = JazzCash mobile wallet, MIGS = Hosted card payment, OTC = Voucher / over the counter
inquiry_url — Assigned HTTPS PaymentInquiry/Inquire URL	url	Yes	Obtain this endpoint from JazzCash onboarding. The live URL is assigned after business approval; only the official JazzCash environment hostname is accepted.
test_reference — Existing transaction reference for connection test	text	No	Optional reference of an existing transaction in the selected environment. Used only for a read-only inquiry.
currencies — Invoice currency	select	Yes	Default: "PKR" Choices: PKR = PKR

This module uses JazzCash's provider-hosted POST checkout in PKR, with one approved instrument per connection: mobile wallet, hosted card (MIGS) or OTC voucher. Enable only the instrument approved for your merchant account. It does not collect cards, mobile OTPs or CNIC values within EmailaBiller.

1. Obtain merchant ID, password, integrity salt/hash key and approved instrument from JazzCash merchant onboarding.
2. Obtain the assigned HTTPS PaymentInquiry/Inquire URL from JazzCash. The public integration guide explicitly says the production URL is communicated after business approval. No universal endpoint is guessed. This package accepts only the official sandbox.jazzcash.com.pk or payments.jazzcash.com.pk hostname appropriate for the environment, without userinfo, custom port or query. If JazzCash assigns another host, obtain a reviewed module update rather than bypassing this restriction.
3. Configure the provider return URL and notification URL, where supported, using the exact URLs displayed by the connection. The return URL is included in the hosted form. Ensure custom fields ppmpf_1 to ppmpf_3 are returned and signed, and success replies include the retrieval reference number. These carry the original invoice association.
4. Without a reference, Test validates local configuration and explicitly reports no provider authentication. Supply an existing transaction reference to perform a read-only provider inquiry without creating a charge.
5. Complete a sandbox payment for the chosen instrument and verify callback signatures and inquiry responses before live enablement. Signed fields use ASCII to avoid ambiguous legacy encoding.

The request uses a deterministic 20-character transaction reference and original attempt/invoice metadata. Callback HMAC-SHA256 follows the official alphabetically sorted nonempty PP-field algorithm. Signed success (000) must match merchant, amount, PKR, original transaction reference and metadata. A fresh read-only inquiry must confirm Success or Confirmed status and the exact retrieval reference number. Pending vouchers, voids, reversals, expiry and failures remain unpaid. The assigned inquiry contract returns status/RRN rather than original amount/currency, so it is deliberately combined with the signed money-bearing callback; a naked status query is never treated as settlement.

Official references: Hosted checkout sandbox examples, API retrieve reference, Merchant integration guide, sections 12.11–12.12 and 14.2.

Install this signed package under System → Payment gateways → Install module. New installations are disabled. Create a separate connection, enter your own merchant credentials, run Test, and explicitly enable that connection after completing sandbox checkout and callback testing. No merchant credentials or business settings are included in this package.

The module uses verified HTTPS with fixed official provider endpoints, no redirects or automatic API retries, bounded uncompressed responses, exact two-decimal invoice accounting, and credential-safe errors. Network timeouts leave payment under review: inspect the provider before retrying. Provider methods depend on merchant approval, payer location, currency and device; installing this module does not promise every payment method. The module never collects card numbers, expiry dates or CVV.