# JazzCash

> Collect Pakistani mobile wallet payments with JazzCash. The payer enters their wallet number and CNIC digits, then approves in the JazzCash app. Setup guide.

Source: https://docs.centipidbilling.com/billing/payment-gateways/jazzcash

## Collect payments with JazzCash

`JAZZCASH` collects by **wallet push**. The payer enters their JazzCash number
and the last 6 digits of their CNIC on the portal, then approves the payment in
their JazzCash app. They never leave the portal page.

Offered in the country catalog for **Pakistan (PK)**, in Pakistani rupees. An
ISP that prices in another currency is refused at checkout, so a USD 10 plan is
never charged as PKR 10.

Centipid Billing uses two calls from JazzCash's Mobile Wallet REST API v2.0:

1. `DoMWalletTransaction` sends the payment request.
2. `PaymentInquiry/Inquire` reports whether it was paid.

Every request is signed with your Integrity Salt, and every answer is checked
against its `pp_SecureHash` before it is trusted. Nothing is credited until a
verified inquiry reads completed.

## Where the CNIC is asked for

JazzCash refuses a wallet payment without the last 6 digits of the payer's CNIC,
so Centipid asks for it on:

- the captive portal (full and lite pages),
- the client portal: top-ups and invoice payments.

It cannot be collected, so JazzCash is refused with a clear message, when an
admin sends a payment prompt from an invoice and on agent float top-ups. Ask the
payer to pay from the captive portal or the client portal instead.

## Configure the gateway

#### Get your credentials from JazzCash

In the JazzCash merchant portal, copy your **Merchant ID**, **Password** and
**Integrity Salt**.

#### Open Settings → Payments → JazzCash in Centipid

Enter the three values. There is no return URL to register: Centipid reads
each payment back from JazzCash.

#### Run a controlled test payment

Pay PKR 10 from the captive portal, approve it in the JazzCash app, and
confirm the payment reaches the ledger.

## Credentials

| Field | Required | Notes |
|---|---|---|
| Merchant ID | Yes | Sent as `pp_MerchantID`. |
| Password | Yes | Sent as `pp_Password`. |
| Integrity salt | Yes | Signs requests and checks answers. Never sent to JazzCash. |

## How a payment completes

JazzCash answers the request at once with `000` (paid) or `157` (waiting for the
payer). Either way, Centipid then asks JazzCash for the payment's status every
5 seconds for about 3 minutes and credits it only when a signed answer says it is
completed. The request itself expires after those 3 minutes, so a payment the
payer approves later is not taken.

If JazzCash does not answer, or its answer fails the signature check, Centipid
still checks the payment's status in case the request reached the payer. Only a
signed refusal is shown to the payer as a failure.

## Troubleshooting

- **"Unable to send the JazzCash payment prompt"**: JazzCash refused the
  request, usually a wrong Merchant ID or password. The detail is in the
  application log. A wrong Integrity Salt shows instead as a prompt that never
  arrives, because no answer verifies.
- **"Enter a Pakistani mobile number"**: the number is not a `03…` mobile number.
- **"JazzCash needs the last 6 digits of the payer's CNIC"**: the payment was
  started from a screen that cannot ask for it. Pay from the captive or client
  portal.
- **"JazzCash bills in PKR, but your prices are in …"**: the ISP's prices are in
  another currency. Contact Centipid support to change it.
- **"Your billing currency is not set"**: contact Centipid support.
