integrate-jazzcash

JazzCash を統合する

加盟店向けに現在承認されている JazzCash のドキュメントを使用してください。利用可能な製品、バージョン、フィールド、エンドポイント、認定要件は加盟店や環境によって異なる場合があるため、公開サンプルは参考情報としてのみ扱ってください。

変更前の確認

リポジトリ内で、JazzCash のパッケージ、プラグイン、SDK、決済フォーム、pp_ フィールド、加盟店 ID、パスワード、インテグリティソルト、セキュアハッシュのビルダー、サンドボックス／本番環境の URL、リターンまたはコールバックのルート、ステータス／返金ロジック、取引テーブル、照合ジョブ、テスト、デプロイ用シークレットを検索してください。

• JazzCash がすでに存在する場合は、統合モード、API／ドキュメントのバージョン、環境、有効な決済方法、ハッシュのルール、注文のライフサイクル、障害を特定してください。最も安全なアップグレード方法を説明し、動作中または認定済みの挙動を維持してください。
• 存在しない場合は、その加盟店向けに提供された最新ドキュメントを使用し、プロジェクトで現在使用しているスタックに合わせて統合を設計してください。
• エンドポイント URL、認証情報の名前、署名対象のフィールド、フィールドの順序、エンコーディング、アルゴリズム、レスポンスコード、ステータスの意味を推測したり、コピーしたりしないでください。加盟店ポータル、最新のガイド、テストベクトルで確認してください。

製品の確認

現在公開されている JazzCash サンドボックスのドキュメントには v4.2 と記載されており、HTTP POST によるページリダイレクトと API テストについて説明されています。公開されている機能ページでは、モバイルウォレット、バウチャー、カード、ホステッド／リダイレクトなどのゲートウェイ機能が紹介されています。実際に加盟店が利用承認を受けているものを確認してください。

オンライン決済ゲートウェイを、個人ウォレットへの送金、ビジネス用 QR／Raast QR、決済リンク、一括決済、小売代理店サービス、または別の JazzCash 法人向け API と混同しないでください。実装前に必要な製品を確認してください。

ワークフロー

1. 最新の加盟店向けガイド、選択した統合モード、有効な決済方法、サンドボックス認証情報、リターン／コールバックのルール、ハッシュの例、ステータス／返金の操作、レスポンスコード表、認定テストケース、精算条件、本番環境用パッケージを入手してください。
2. ドキュメント、プラグイン、または API の正確なバージョンを記録してください。編集前に既存の実装と比較してください。
3. 一意の加盟店取引 ID／参照 ID を使用して、サーバー側で保留中の注文を作成してください。
4. 商品、金額、通貨、割引、配送、期限、顧客の所有権をサーバー側で計算してください。
5. ドキュメントどおりに最終リクエストを構築し、ハッシュを計算してください。加盟店のパスワード、インテグリティソルト、キー、証明書はサーバー側に保管してください。
6. 承認されたホステッド、リダイレクト、ウォレット、バウチャー、またはカードのフローに従って顧客を遷移させてください。契約上の PCI 準拠方式で明示的に許可されていない限り、JazzCash の MPIN、OTP、カード情報を収集しないでください。
7. ブラウザーのリターンは表示用途としてのみ扱ってください。サーバー通知を認証して重複を排除し、注文と金額を検証してください。結果が不明確な場合は、承認済みのステータス情報源で確認してください。
8. 正式な成功を確認した後、一度だけ商品を提供してください。ゲートウェイ取引、レスポンス、決済方法、取消／返金、精算の各識別子を永続化してください。
9. キャンセル、拒否、期限切れ、タイムアウト、レスポンスの消失、重複／遅延コールバック、取消／返金、精算の不一致に対処してください。
10. 本番環境の有効化を申請する前に、サンドボックスと加盟店認定のテストに合格してください。

必ず守るルール

• フロントエンドのコード、モバイルバイナリ、リポジトリ、ログ、URL、スクリーンショット、エラーに、認証情報や完全性を検証するための情報を決して露出させないでください。
• リダイレクト、クエリパラメーター、クライアントからの応答、SMS、スクリーンショットだけを根拠に、注文を支払い済みとして処理しないでください。
• 正規化とセキュアハッシュの検証は、仕様どおりに正確に実装してください。該当する場合は、タイミングセーフなダイジェスト比較を使用してください。
• 内部注文参照と JazzCash の取引識別子の一意性を確保してください。支払いの状態遷移とフルフィルメントは冪等にしてください。
• ステータスの検証または照合によって結果が確定するまで、タイムアウトは不明として扱ってください。二重請求を盲目的に作成しないでください。
• 整数の最小通貨単位、またはガイドで指定された正確な金額形式を使用してください。二進浮動小数点数は使用しないでください。
• 明示的な承認なしに、実環境での支払い、売上確定、返金、取消、認証情報の変更を決して行わないでください。

参照先の確認

• モード、注文状態、リクエスト処理、コールバック、ステータス復旧、プラグイン、テストについては、references/integration-workflow.md を参照してください。
• ハッシュ、シークレット、冪等性、監視、照合、本番稼働の管理策を実装する前に、references/security-and-operations.md を参照してください。
• 日付付きの情報源と再確認が必要な詳細については、references/research-notes.md を参照してください。

検証と報告

プロジェクトのフォーマッター、静的解析／型チェック、テスト、ビルドを実行してください。JazzCash が既存だったか新規に実装したか、ガイド／API／プラグインのバージョン、有効化した決済方法、実装したフロー、コールバックとハッシュの検証、冪等性、不明状態からの復旧、照合、認定状況、残っている加盟店ポータルの設定を報告してください。公開情報の調査、加盟店の仕様、サンドボックスでの証拠、実環境での承認は、それぞれ分けて記載してください。