WeChat H5決済の連携手順:ブラウザ起動・注文照会・残高反映

WeChat H5決済は、スマートフォンのブラウザ上のサイトから支払いを開始し、WeChatの決済画面を開く方式です。画面遷移に加え、サーバーでの支払確認とサイト残高への反映まで設計します。本記事は公式の流れを解説します。稳付pay経由のH5対応、商戸権限、実際のAPIは技術担当者に確認してください。

テーマ別に読む

1.H5・WeChat内のページ・APP決済を区別する

公式H5決済の対象は、WeChat内ブラウザ以外のモバイルWebページです。WeChat内のページは通常JSAPI決済、ネイティブアプリはAPP決済を利用します。アプリにWebページを埋め込んでも、公式H5の対象になるわけではありません。参考リンクの2つ目はAPP開発ガイドで、OpenSDK、sendReq、onRespは別方式の機能です。

通常の商戸が直接接続する場合、対象となる事業者資格、H5利用権限、商戸番号とAPPIDの紐付け、H5決済ドメインの設定が必要です。申請条件は最新の公式説明を確認してください。稳付payではドメイン、事業内容、ページを開く環境を伝え、割り当てチャネルのH5対応を確認します。本記事の公開で全商戸へ開通するわけではありません。

ブラウザ名やネイティブチャネルという名称だけでAPIを選ばず、利用環境、権限、チャネルを確定してから方式を決めます。

2.稳付payの接続手順:チャネル確認から本番運用まで

手順1:@tonyyydsへドメイン、事業内容、ブラウザやアプリの利用環境、チャージ・購読の流れ、注文量、USDT精算の希望を伝えます。技術担当者がH5対応、利用チャネル、料金、精算条件、テスト方法を確認します。名称だけで開通済みとは判断しません。

手順2:実際のゲートウェイ、商戸番号mchId、許可されたwayCode、サーバー用の鍵を受け取り、公開notifyUrlと注文テーブルを用意します。鍵はバックエンドで管理します。集約コードの例はWeChatが90001、Alipayが80001ですが、利用権限が必要で、個別チャネルコードが指定される場合もあります。

手順3:一意のoutTradeNoと信頼できる金額を保存し、バックエンドからPOST /api/pay/collect/createへJSONを送ります。amountは人民元の分単位の整数で、1000は10元です。reqTimeは現在のミリ秒時刻を整数で指定し、signは資料のMD5規則で生成します。以下は本記事の決済方式の項目例で、仮の値を置き換え、サーバーで署名する必要があります。

回収フィールド例:仮の値を置き換え、reqTimeを現在のミリ秒整数にし、バックエンドで署名します。そのまま送信しないでください。
{
  "mchId": "YOUR_MERCHANT_ID",
  "wayCode": "90001",
  "outTradeNo": "YOUR_UNIQUE_ORDER_NO",
  "amount": 1000,
  "currencyCode": "CNY",
  "notifyUrl": "https://merchant.example.com/pay/notify",
  "subject": "WENFUPAY_H5_DEMO",
  "reqTime": "CURRENT_UNIX_MILLISECONDS",
  "sign": "GENERATE_MD5_ON_SERVER"
}

手順4:プラットフォーム注文番号を保存し、有効なpayUrlを受け取ってから所定の表示・遷移を行います。決済URLを独自に組み立てません。code=0は要求受付であり、支払完了でも残高加算の根拠でもありません。アプリが直接起動するかはチャネルとブラウザのテストで確認します。

手順5:稳付payの共通JSON通知を受け、署名、商戸、注文、金額、通貨を確認して一度だけ記帳します。永続保存後にHTTP 200とプレーンテキストOKを返します。通知未着や注文作成結果が不明な場合は、元の注文をバックエンドからGET /api/pay/collect/queryで照会します。照会金額の単位は接続時に確認してください。

手順6:担当者と調整したテスト環境で支払、キャンセル、タイムアウト、重複通知、残高反映を確認し、最初の本番注文を照合してから流量を増やします。下記に相談先と詳細資料を用意しています。

3.稳付payを利用する理由:チャネルと支援内容

決済手段の選択:現在はWeChat個人コード回収、WeChatネイティブ回収、Alipayネイティブ回収と集約接続を提供しています。事業に合う方式を設定し、個別チャネルとの接続作業を減らせます。H5対応は開通済みチャネル次第です。現在の稼働状況は安定していますが、注文、端末環境、チャネル状況で結果は変わるため固定の成功率を保証しません。

注文と通知の統一:返された決済入口と共通の注文作成・照会・JSON通知により、チャージ、購読、カード発行、TGボット注文を自社システムへ連携できます。プラットフォームは支払状態を通知し、残高や権限は商戸が検証済み結果から更新します。通知受信だけですべての提供処理が自動完了するわけではありません。

T0リアルタイムUSDT精算:顧客の支払確認後、合意した条件で商戸へUSDT精算を行えます。対象金額、料金、換算方法、ネットワーク、受取先を接続時に確認します。処理とブロックチェーン着金には条件や承認があり、手数料無料、承認不要、全件無条件の即時着金を意味しません。

技術担当者の支援:商戸設定、チャネル、署名、照会、通知異常について相談できます。WeChat・Alipay回収後のUSDT精算と、商戸の自有アドレスへのUSDT監視は別の資金経路です。後者は顧客が商戸ウォレットへ直接送り、稳付payが確認を監視して通知するサービスです。

4.公式H5パラメータと稳付payの決済リンクを区別する

バックエンドで利用者、商品またはチャージプラン、金額、通貨を紐付けた注文を作成します。価格はサーバー情報から取得し、ブラウザ入力を信用しません。公式API v3ではPOST /v3/pay/transactions/h5へ一意のout_trade_noとnotify_url、amount、scene_infoなどを送ります。amount.totalは人民元の分単位の整数で、10元なら1000です。署名と秘密鍵はサーバーで管理します。稳付payでは実際の資料の項目、単位、署名方式を使い、公式パラメータをそのまま流用しません。

設定済みH5ドメイン上のページからh5_urlへ遷移します。戻り先を指定するときは元の決済パラメータを保ち、redirect_urlを追加して戻り先URLを正しく一度エンコードします。そのドメインもH5決済用の設定が必要です。URL構築ツールでの二重エンコードに注意してください。redirect_urlはブラウザの戻り先、notify_urlはサーバー通知先で、代用できません。

公式ガイドのh5_url有効期間は5分で、注文全体の支払期限とは異なります。期限切れ時は注文を照会し、支払可能なら仕様に従い元のパラメータで新しいリンクを取得します。支払期限後は照会してから終了処理または再作成し、画面のカウントダウンだけで失敗とは扱いません。

5.支払確定後に通知と残高反映を処理する

完了後もキャンセル後も同じ商戸ページへ戻る場合があります。戻り先への到達、成功表示、支払画像だけで残高を加算してはいけません。結果確認ボタンからバックエンドへ照会を依頼し、利用者に閲覧権限のある注文の確定結果か確認待ちを表示します。戻りURLの金額やsuccessパラメータは入金根拠にしません。

公式API v3では仕様に沿って通知検証と復号を行い、稳付payでは実際のコールバック資料に従います。受取先、商戸注文番号、取引番号、予定金額、通貨を照合してください。照会と通知は同じ状態処理へ集約し、遅れて届いた未払い情報で確定済みの成功を上書きしません。

チャージでは注文ごとに一意の加算記録を作り、注文更新と残高台帳を同じデータベーストランザクションで処理します。通知再送、再照会、画面更新で再加算しません。会員権限や商品提供も重複を防ぎます。支払後の権限付与だけが失敗したら再処理タスクを残し、再払いを求めません。通知を永続保存した後、APIの規定に沿って応答します。

6.起動失敗・白画面・残高反映の遅延を検証する

起動しない場合は注文番号、時刻、OS、ブラウザ、利用環境、エラー、機密を除いたリクエスト識別子を記録します。H5権限、ドメイン、リンク期限、遷移経路、外部アプリ起動許可を確認します。送信元の偽装やドメイン検証の回避はせず、全ブラウザでの自動起動も約束しません。

白画面ならURLエンコード、戻り先ドメイン、ルーティング、ログイン復元を確認します。支払確定後も残高が変わらない場合は取引、通知検証、注文状態、加算台帳を追跡します。通知がなければ注文照会で補完し、支払済み注文を安易に作り直しません。ログは機密を除去し、決済リンクや鍵を公開問い合わせへ載せないでください。

正常支払、キャンセル、リンク期限切れ、ページ終了、遅延・重複通知、照会との同時処理、残高書き込み失敗からの復旧を検収します。一度だけの加算と取引から台帳までの追跡を確認してください。稳付payは接続設計の確認を支援します。手数料、対応範囲、USDT精算条件は別途合意し、画面が起動しただけで支払や精算の完了とは扱いません。

よくある質問

H5なら事業者資格やドメイン設定は不要ですか?

不要にはなりません。公式H5には資格、製品権限、決済ドメインが必要です。稳付pay経由では事業内容、ドメイン、利用環境、パラメータを技術担当者が確認します。審査やWeChatのルールを回避する仕組みではありません。

完了を押しても通知がない場合は残高を増やせますか?

画面操作だけでは加算できません。バックエンドで支払結果、受取先、金額、通貨を確認し、共通の重複防止処理で反映します。確認できないときは確認待ちと表示し、注文番号で調査して二重払いを防ぎます。

参考資料