開発者向け導入ガイド:製品に稳付payを接続する
あなたのサイト、デジタルコード販売システム、アプリが業務注文の作成と商品提供を担当し、稳付payが決済チャネルの接続と結果通知を担当します。実際の導入順に、必要な設定、呼び出すAPI、支払い済みにできるタイミングを説明します。
この記事の目次
導入するサービスを確認
このドキュメントで説明するのは、開通済み決済チャネルの 収納代行の注文作成・注文照会・支払い成功通知 です。振込代行はまだ提供していません。利用可能なチャネル、本番ゲートウェイ、精算方法、加盟店権限は、利用開始時に稳付payの技術担当者と確認します。
収納代行後の精算と、顧客が加盟店所有のUSDTウォレットへ直接送金するオンチェーン監視サービスは、資金経路が異なります。この収納代行APIはUSDTオンチェーン直接受取APIではありません。
本文のURL、注文番号、認証情報はすべて例です。技術担当者との接続を済ませ、あなた専用の設定を取得してください。デモのパラメーターを本番でそのまま使わないでください。
ステップ1:加盟店設定を申請
| 設定項目 | 使用箇所 | 確認する内容 |
|---|---|---|
API_BASE_URL | 加盟店サーバー | 割り当てられた実際のゲートウェイ。本文では https://gateway.example.com を例にしています。 |
MERCHANT_ID | 加盟店サーバー | あなたの加盟店番号。リクエストの項目名は mchId。 |
MD5_SECRET | 環境変数またはシークレット管理 | 注文作成と照会に使用するAPIシークレット。 |
CALLBACK_SECRET | サーバー側のシークレット管理 | 個別設定の通知用シークレット。未設定の場合はAPIシークレットを使用します。 |
wayCode | 決済方法の対応付け | その加盟店で実際に開通した実チャネルまたは集約コード。 |
notifyUrl | 公開HTTPSバックエンドAPI | 例: https://merchant.example.com/pay/notify。 |
シークレットはバックエンドだけに保存し、フロントエンドには業務注文と表示を許可した決済リンクだけを渡します。テスト用と本番用の設定は分離し、ログではシークレットと署名元文字列中のシークレット部分をマスクしてください。
ステップ2:決済フロー全体を接続
- 業務注文を作成サーバーで商品、金額、通貨、一意の加盟店注文番号を決定し、支払い待ち記録を保存します。
- サーバーで署名して注文作成現在のミリ秒タイムスタンプを生成して署名し、収納代行の注文作成APIを呼び出します。
- 有効な決済リンクを表示実際に返されたpayUrlを確認して決済へ誘導します。リンクがない場合は照会または例外処理へ進みます。
- 成功通知を検証バックエンドで署名、加盟店、注文、通貨、金額を確認し、ブラウザー遷移だけで着金を判断しません。
- 冪等な更新と商品提供決済状態を永続化し、一意の提供記録でコード、チャージ、発送の重複を防ぎます。
- 照会と照合タイムアウト、通知漏れ、長時間支払い待ちの注文を能動的に照会し、処理記録を保持します。
ステップ3:製品内に4つの接続箇所を用意
| システム上の箇所 | 接続時の役割 | 保持する記録 |
|---|---|---|
| 注文作成サービス | 業務注文を検証し、署名して作成APIを呼び出します。 | 加盟店注文番号、分単位の金額、通貨、プラットフォーム注文番号。 |
| 決済表示画面 | 実際の決済リンクとローカル状態を表示します。 | 関連注文と顧客のアクセス権限。 |
| 非同期通知API | 署名・内容を検証し、成功結果を冪等に永続化します。 | 通知の要約、検証結果、受信時刻。 |
| 照会タスク | 不明な結果を補完し、同じ提供フローへ渡します。 | 照会結果、回数、最終照合時刻。 |
既成のデジタルコード販売システムを使う場合は、これらの処理を決済プラグインまたはサーバー拡張へ組み込みます。独立した加盟店注文番号の保存、元のパラメーターによる署名検証、冪等な納品に対応しているか確認してください。遷移リンクを追加するだけでは接続完了ではありません。
本番公開前の導入検収チェックリスト
- 合意したテスト注文を完了し、分単位の金額で、正しいプラットフォーム注文と決済入口に関連付けられること。
- 正しい署名が通り、項目不足、金額改変、不正署名を識別・記録できること。
- 利用者がブラウザーを閉じても、サーバーが通知または照会で状態を更新できること。
- 重複通知や通知と照会の同時成功でも、商品提供が一度だけになること。
- 作成タイムアウト時は元の注文を先に照会し、むやみに新番号で作り直さず、不明な結果は確認待ちにすること。
- 支払い成功後の提供失敗を安全に再試行でき、決済と提供の両方に記録があること。
- 通知APIへ公開インターネットからアクセスでき、シークレットがページソース、公開添付物、ログに出ないこと。
テスト金額、チャネル権限、例外処理は技術担当者と確認します。支援が必要な際は、マスクした注文番号、リクエスト時刻、エラー要約を提示し、スクリーンショットにシークレットを載せないでください。
APIの接続を続ける
次の順にお読みください:収納代行の注文作成と照会、リクエスト署名ルールおよびコールバック署名検証と冪等な商品提供。開発フレームワーク、コード販売システム、開通済みチャネルに合わせて技術担当者が接続を支援します。
本文は稳付pay接続仕様に基づいています。例は呼び出し箇所とパラメーター構造を説明するもので、正式な接続テストではあなたに割り当てられた設定を使います。