Back to Details

integrate-jazzcash

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Integrate JazzCash

集成JazzCash

Use the merchant's current approved JazzCash documentation. Treat public samples as orientation only because enabled products, versions, fields, endpoints, and certification requirements can differ by merchant and environment.
使用商户当前已获批的JazzCash文档。仅将公开示例作为参考，因为启用的产品、版本、字段、端点及认证要求可能因商户和环境而异。

Inspect before changing anything

修改前的检查

Search the repository for JazzCash packages, plugins, SDKs, payment forms, 
pp_
fields, merchant IDs, passwords, integrity salts, secure-hash builders, sandbox/live URLs, return or callback routes, status/refund logic, transaction tables, reconciliation jobs, tests, and deployment secrets.
  • If JazzCash exists, identify its integration mode, API/document version, environment, enabled payment methods, hashing rules, order lifecycle, and failures. Explain the safest upgrade path and preserve working or certified behavior.
  • If it does not exist, design the integration in the project's current stack using the latest documentation supplied for that merchant.
  • Never guess or copy endpoint URLs, credential names, signed fields, field ordering, encodings, algorithms, response codes, or status meanings. Confirm them against the merchant portal, current guide, and test vectors.
在代码仓库中搜索JazzCash相关的包、插件、SDK、支付表单、
pp_
字段、商户ID、密码、完整性盐值、安全哈希生成器、沙箱/生产环境URL、返回或回调路由、状态/退款逻辑、交易表、对账任务、测试及部署密钥。
  • 若已存在JazzCash集成，需确定其集成模式、API/文档版本、运行环境、启用的支付方式、哈希规则、订单生命周期及故障情况。说明最安全的升级路径，并保留已验证或合规的功能。
  • 若不存在JazzCash集成，则使用该商户提供的最新文档，基于项目当前技术栈设计集成方案。
  • 切勿猜测或复制端点URL、凭证名称、签名字段、字段顺序、编码方式、算法、响应码或状态含义。需通过商户门户、当前指南及测试用例进行确认。

Confirm the product

确认产品类型

The current public JazzCash sandbox documentation is labeled v4.2 and describes HTTP POST page redirection and API testing. Its public feature pages describe Mobile Wallet, voucher, card, hosted/redirection, and related gateway capabilities. Confirm what the merchant has actually been approved to use.
Do not confuse the Online Payment Gateway with personal wallet transfers, business QR/Raast QR, payment links, bulk payments, retail agent services, or another JazzCash corporate API. Confirm the required product before implementation.
当前公开的JazzCash沙箱文档版本为v4.2，涵盖HTTP POST页面重定向及API测试内容。其公开功能页面介绍了移动钱包、代金券、卡片、托管/重定向及相关网关功能。需确认商户实际获批使用的功能。
请勿将在线支付网关与个人钱包转账、商业二维码/Raast二维码、支付链接、批量支付、零售代理服务或其他JazzCash企业API混淆。在实现前需确认所需的产品类型。

Workflow

工作流程

  1. Obtain the latest merchant guide, selected integration mode, enabled methods, sandbox credentials, return/callback rules, hash examples, status/refund operations, response-code table, certification cases, settlement terms, and production pack.
  2. Record the exact documentation, plugin, or API version. Compare it with any existing implementation before editing.
  3. Create a server-side pending order with a unique merchant transaction/reference ID.
  4. Calculate products, amount, currency, discounts, delivery, expiry, and customer ownership on the server.
  5. Build and hash the final request exactly as documented. Keep merchant passwords, integrity salts, keys, and certificates server-side.
  6. Send the customer through the approved hosted, redirection, wallet, voucher, or card flow. Never collect a JazzCash MPIN, OTP, or card details unless the contracted PCI-compliant method explicitly permits it.
  7. Treat the browser return as presentation only. Authenticate and deduplicate the server notification, validate the order and amount, and verify ambiguous outcomes through the approved status source.
  8. Fulfill once after authoritative success. Persist gateway transaction, response, payment method, reversal/refund, and settlement identifiers.
  9. Handle cancellation, decline, expiry, timeout, lost response, duplicate/delayed callback, reversal/refund, and settlement mismatch.
  10. Pass sandbox and merchant certification tests before requesting production activation.
  1. 获取最新的商户指南、选定的集成模式、启用的支付方式、沙箱凭证、返回/回调规则、哈希示例、状态/退款操作说明、响应码表、认证用例、结算条款及生产环境包。
  2. 记录文档、插件或API的准确版本。在编辑前与现有实现进行对比。
  3. 在服务器端创建待处理订单，并生成唯一的商户交易/参考ID。
  4. 在服务器端计算商品信息、金额、货币类型、折扣、配送费用、有效期及客户归属信息。
  5. 严格按照文档要求构建并哈希最终请求。将商户密码、完整性盐值、密钥及证书保留在服务器端。
  6. 引导客户通过已获批的托管、重定向、钱包、代金券或卡片支付流程完成支付。除非合同约定的PCI合规方式明确允许，否则切勿收集JazzCash的MPIN、OTP或卡片详情。
  7. 仅将浏览器返回结果用于展示。对服务器通知进行鉴权和去重，验证订单及金额，并通过获批的状态来源确认模糊的交易结果。
  8. 在确认交易权威成功后完成一次履约。持久化存储网关交易信息、响应数据、支付方式、撤销/退款及结算标识。
  9. 处理订单取消、支付拒绝、过期、超时、响应丢失、重复/延迟回调、撤销/退款及结算不匹配等情况。
  10. 在申请生产环境激活前，需通过沙箱测试及商户认证测试。

Non-negotiable rules

不可违反的规则

  • Never expose credentials or integrity material in frontend code, mobile binaries, repositories, logs, URLs, screenshots, or errors.
  • Never mark an order paid from a redirect, query parameter, client response, SMS, or screenshot alone.
  • Implement canonicalization and secure-hash verification exactly as specified; use timing-safe digest comparison where applicable.
  • Enforce uniqueness for internal order references and JazzCash transaction identifiers. Make payment transitions and fulfillment idempotent.
  • Treat timeouts as unknown until status verification or reconciliation proves the outcome. Never blindly create a second charge.
  • Use integer minor units or the guide's exact amount format; never binary floating point.
  • Never perform live payments, captures, refunds, reversals, or credential changes without explicit approval.
  • 切勿在前端代码、移动应用二进制文件、代码仓库、日志、URL、截图或错误信息中暴露凭证或完整性相关材料。
  • 切勿仅通过重定向、查询参数、客户端响应、短信或截图标记订单为已支付。
  • 严格按照指定要求实现规范化及安全哈希验证；在适用场景下使用时序安全的摘要比较方法。
  • 确保内部订单参考ID及JazzCash交易标识的唯一性。使支付状态转换及履约操作具备幂等性。
  • 在通过状态验证或对账确认结果前，将超时视为未知状态。切勿盲目发起第二次扣费。
  • 使用整数最小单位或指南指定的精确金额格式；切勿使用二进制浮点数。
  • 未经明确批准，切勿执行生产环境支付、扣款、退款、撤销或凭证变更操作。

Reference routing

参考文档指引

  • Read references/integration-workflow.md for modes, order states, request handling, callbacks, status recovery, plugins, and testing.
  • Read references/security-and-operations.md before implementing hashes, secrets, idempotency, monitoring, reconciliation, or go-live controls.
  • Read references/research-notes.md for dated sources and details that must be rechecked.
  • 阅读references/integration-workflow.md了解集成模式、订单状态、请求处理、回调、状态恢复、插件及测试相关内容。
  • 在实现哈希、密钥、幂等性、监控、对账或上线控制前，阅读references/security-and-operations.md。
  • 阅读references/research-notes.md了解需重新核对的过时资料及细节。

Verify and report

验证与报告

Run the project's formatter, static/type checks, tests, and build. Report whether JazzCash existed or was added from scratch; the guide/API/plugin version; enabled methods; implemented flows; callback and hash verification; idempotency; unknown-state recovery; reconciliation; certification status; and remaining merchant-portal configuration. Separate public research, merchant specifications, sandbox evidence, and live approval.
运行项目的格式化工具、静态/类型检查、测试及构建流程。报告JazzCash集成是已存在还是从零开始添加；指南/API/插件版本；启用的支付方式；已实现的流程；回调及哈希验证情况；幂等性；未知状态恢复机制；对账功能；认证状态；以及商户门户剩余的配置项。区分公开研究资料、商户规格说明、沙箱测试证据及生产环境批准文件。