# EasyPaisa & JazzCash Integration

## Manual vs. Live Gateway

Each payment method can operate in two modes:

| Mode | `has_live_gateway` | How it works |
|---|---|---|
| Manual | `false` | Staff records the payment after the customer sends money |
| Live | `true` | System initiates payment request via API; customer pays on phone |

---

## Enabling Live Gateway

1. Go to **Configuration → Payment Methods**
2. Select EasyPaisa or JazzCash
3. Toggle **Enable Live Gateway**
4. Enter your API credentials:
   - **EasyPaisa**: `store_id`, `hash_key`
   - **JazzCash**: `merchant_id`, `password`, `integrity_salt`
5. Save — credentials are stored **encrypted** in the database

---

## Payment Flow (Live Gateway)

### Initiate Payment
```
Customer/Staff → POST /api/v1/payments/initiate
→ System builds signed request
→ Sends to EasyPaisa/JazzCash API
→ Customer receives OTP on phone
→ Customer enters OTP
→ Gateway confirms
```

### Webhook Callback
```
EasyPaisa/JazzCash → POST /api/v1/webhooks/easypaisa
                   → POST /api/v1/webhooks/jazzcash
→ System verifies HMAC signature
→ Updates PaymentGatewayTransaction record
→ Updates Bill and Payment status
```

---

## HMAC / Signature Verification

**Every webhook request is verified before processing.** The raw payload
is hashed using the configured secret key and compared to the signature
in the request headers. If they do not match, the webhook is rejected with
`HTTP 400`.

---

## Gateway Transaction Log

All raw requests and responses are stored in `payment_gateway_transactions`
with the payloads **encrypted**. This provides an audit trail for disputes.

---

## Test Mode

Do not enable live gateway in development. Use manual mode and record test
payments manually. Gateway credentials should only be set in production.
