オンチェーン入金

コード販売基盤とUSDTの連携:自己保有アドレス・チェーン承認・確実な通知

チェーン上で送金を発見しても、注文への入金が確実に確認できたとは限りません。通知を受け取っても、コードを重複発行してよいわけではありません。ウォレット、取引証拠、支払い状態、在庫納品を分けることで、加盟店が資金を自ら管理しながら、デジタル商品の納品を追跡可能にできます。

この記事の目次

1.資金の扱いを明確にする:アドレスは加盟店保有、監視サービスは資産を保管しない

ここでいうコード販売基盤とは、デジタル商品、ライセンスキー、引換コードを自動納品するシステムです。USDT導入時、顧客は加盟店自身の受取アドレスへ直接支払います。稳付payは取引の監視・識別、着金状態の確認、加盟店システムへの通知を担当します。資金は稳付payを経由せず、プラットフォームによる収納代行や保管も行いません。

ウォレットと署名権限は加盟店が自分で管理します。公開受取アドレスがあれば読み取り専用監視ができるため、監視担当にシードフレーズ、秘密鍵、ウォレットファイル、遠隔操作権限を渡すべきではありません。「設定を代行する」という理由でも、これらの情報を要求してよいことにはなりません。資金を自分で管理する以上、アドレスのバックアップ、入金確認、返金承認も加盟店の責任です。

2.ネットワーク・トークン・承認条件を注文時に固定する

稳付payは現在、USDTのTron(TRC20)とEthereum(ERC20)に対応しています。USDTは資産名、TRC20とERC20は異なるネットワーク上のトークン規格であり、同名でも注文とアドレスを混同できません。決済画面ではネットワークを明示して確認を求め、「USDT支払い」とだけ表示しないようにします。

確認項目Tron / TRC20Ethereum / ERC20
オンチェーン取引の証拠正常に実行された対象コントラクトの送金イベントを検証する成功レシート内の対象コントラクトのTransferログを検証する
承認の判断基準取り決めに従い、承認・固化済みデータを確認する合意したブロック承認数、またはsafe/finalizedの方針に従う
共通要件ネットワーク・対象コントラクト・加盟店アドレス・金額・注文照合結果を確認する

TRONの取引ドキュメントはブロックへの取り込みと固化を区別しており、EthereumのJSON-RPCドキュメントも異なるブロック状態を区別しています。承認方針は導入双方で合意し、一定の秒数で置き換えてはいけません。稳付payの秒単位コールバックとは、合意した承認条件を満たした後の通知速度であり、チェーン自体の秒単位承認を保証するものではありません。

3.注文との紐付けは「同額」だけで判断しない

同価格の商品を2人が同時購入することも、1取引に複数のトークン送金イベントが含まれることもあります。注文には少なくとも内部注文番号、ネットワーク識別子(EthereumならchainIdなど)、対象トークンコントラクト、受取アドレス、整数金額、有効期限を紐付けます。取引証拠には取引ハッシュ、イベント番号、ブロック番号、ブロックハッシュも記録し、顧客が入力した取引ハッシュだけを着金証明にしてはいけません。

注文ごとに加盟店管理下の専用アドレスを割り当てるか、共有アドレス方式なら支払いセッションと競合規則を明確にします。金額に差を付ける方式でも、ネットワーク、コントラクト、アドレス、有効セッション、取引の所属を併せて判断します。候補注文が複数あれば手動照合へ進み、「最初の1件に紐付ける」ことは禁止します。

Ethereumの単一ログは通常、ネットワーク識別子、取引ハッシュ、logIndexで特定します。TRONではAPIが提供するイベント番号で安定した対応を作ります。元イベントとブロックハッシュを保持し、再編時は正規チェーン上の所属を再検証します。これは現在の正規チェーン上のイベントの特定であり、logIndexが再編をまたいでも永久不変という意味ではありません。取引ハッシュだけでイベント単位の一意性を代用してもいけません。

4.金額は最小単位で扱い、アドレスとコントラクトを個別に検証する

支払い金額を浮動小数点で比較しないでください。信頼できる対象トークン設定から精度を確認し、最小単位の整数で保存します。精度が6なら12.34は12340000最小単位です。これは換算例であり、USDTと名乗る任意のコントラクトを信頼してよいという意味ではありません。チェーン、コントラクトアドレス、精度は管理された許可リストから取得し、顧客が指定した同名トークンを採用しません。

アドレスはネットワークごとの形式を検証し、確認画面で全体を照合します。送金額とウォレットが支払うネットワーク手数料も区別し、顧客の手数料を自動的に商品代へ加算しません。初回は少額で検証し、実際の受取アドレスとイベントを確認して、画面の成功表示をオンチェーン着金成功と同一視しないようにします。

5.取引監視とコード納品の間に明確な状態を設ける

  1. 支払いセッションの作成注文・ネットワーク・アドレス・金額・有効期限を固定する
  2. 送金の検出と検証正常に実行された対象トークンのイベントを確認する
  3. 合意した承認を待つブロック情報を保持し、取引の所属を再確認する
  4. 入金通知の永続化業務側で署名検証・重複排除を行い、注文を更新する
  5. 在庫の納品コード納品の結果と補償ジョブを別途記録する
取引の検出、承認、コールバック受領、商品の納品は別々の状態であり、1つの「成功」にまとめてはいけません。

監視処理はスキャン位置を保存し、切断後に欠落区間を補完し、範囲を少し重ねた再スキャンを可能にします。重複は「理論上再送されない」と仮定せず、一意制約で排除します。承認条件を満たさない送金は確認待ちにし、ノードの遅延やイベント取消があれば状態の進行を止め、納品を続けません。

たとえば加盟店のデータベースでは、支払いイベントにNOT NULLの複合一意キーを設け、注文ごとに一意の納品記録を作ります。PostgreSQLの制約ドキュメントでは複合一意制約の役割を説明しています。具体的なキーはネットワークのイベントモデルに合わせ、すべてのチェーンへ機械的に当てはめないでください。

6.確実な通知には送信元確認・永続化・冪等性が必要

コールバックはHTTPSを使い、双方で合意した仕様に従って署名、タイムスタンプ、イベントの識別情報を検証し、内部注文、通貨、ネットワーク、金額も照合します。署名が生のリクエストボディを対象にするなら、JSONを解析・並べ替える前に元のバイト列を保持します。鍵の更新、時計の許容誤差、再送規則は接続試験で明確にします。本稿で稳付payのAPIアドレスや署名項目を架空に定義することはありません。

参考にできるのは、Stripe公式Webhookガイドの重複イベントと署名検証に関する原則ですが、これは稳付payのAPI仕様ではありません。検証後は通知をデータベースか永続キューへ確実に保存してから、合意した成功応答を速やかに返します。保存失敗時に先に受領を確定してはいけません。時間のかかるコード納品はバックグラウンドジョブで処理します。

同じ通知が10回届いても、入金状態の進行と納品はそれぞれ1回だけです。支払い更新と納品待ちジョブを同一トランザクションで保存し、納品ジョブでは注文と在庫をロックします。失敗時は既存ジョブを再試行し、2つ目のコードを新規発行しません。通知の一時的な失敗には再送と追加照会で対応でき、ブラウザーの遷移でサーバー側検証を代用してはいけません。

7.障害事例:重複通知と承認前のチェーン再編

事例1:コード納品後、通知リクエストがタイムアウトして再送される

最初のリクエストはトランザクションを確定済みで、応答だけが途中で失われた可能性があります。2回目はイベント情報で重複排除し、注文の納品状態を読み、処理済みの結果を返します。「今回のリクエストは新しい」というだけで在庫をもう1つ取り出してはいけません。通知記録、注文トランザクション、納品記録を照合して初めて、再送と本当の納品漏れを区別できます。

事例2:送金を発見して即納品した後、取引の所属ブロックが変わる

未承認の取引はチェーン再編の影響を受ける可能性があります。監視処理では所属ブロックを確認し、Gethのサブスクリプション資料にあるように、Ethereumログにremovedフラグが付く場合も考慮します。変化を検知したら承認待ちの監視状態へ戻し、再スキャンして検証します。承認条件を満たす前に納品していたら手動のインシデント対応へ進み、証拠を残します。利用者のウォレットから自動で資金を取り戻そうとしてはいけません。

8.期限後入金・在庫切れ・返金の規則を個別に決める

注文の期限が切れても、そのアドレスが入金を受け付けなくなるわけではありません。期限後に検出した支払いは要照合の入金として記録し、新しい注文へ自動流用しません。不足、過払い、分割入金も事前の取り決めに従います。在庫予約の失効後に入金が承認されたら、在庫を再確認して納品するか、手動返金へ進みます。

支払い完了と納品成功は別々に記録します。入金確認後に在庫がなければ入金の事実を残し、対応待ちと顧客に伝え、注文を「未払い」へ戻しません。返金は加盟店ウォレットから行う新しいオンチェーン取引です。個別承認、返金先ネットワークとアドレスの確認、手数料と取引ハッシュの記録が必要です。取引所の代行送金アドレスは顧客が直接受け取れるとは限らないため、送金元へ自動返金してはいけません。

9.本番前の確認:異常経路を検証してから取引量を増やす

  • 受取ウォレットを加盟店が管理し、導入情報に秘密鍵やシードフレーズが含まれないことを確認する。
  • TRC20とERC20のコントラクト・精度・アドレス・承認方針をそれぞれテストする。
  • 同価格注文、重複イベント、通知タイムアウト、切断後の補完スキャン、承認前のチェーン再編を検証する。
  • 期限後入金、不足・過払い、在庫切れ、納品失敗、照合、手動返金を訓練する。
  • 注文から支払いイベントと納品ジョブをログで追跡でき、鍵や販売コードは秘匿されている。

稳付payは現在、中小サイト運営者向けに上記2ネットワークの監視・コールバックを無料で提供し、企業向けサービスは別途有料です。加盟店管理画面は開発中のため、現段階ではお問い合わせによる設定・連携が可能です。資金は常に加盟店自身のウォレットで管理されます。承認方針、通知仕様、異常処理は本番前の接続試験で確認してください。

参考資料・技術ドキュメント

以下の公式資料は、プロトコルと実装原理の確認に使用しています。コードと事例は技術説明のためのもので、具体的な環境と正式な連携仕様はそれぞれ検証してください。

  1. TRON公式:取引ライフサイクルと固化
  2. TRON公式:TRC-20トークン規格
  3. Ethereum公式:JSON-RPC・ログ・ブロック状態
  4. Geth公式:ログ購読と再編時のremovedフラグ
  5. Stripe公式:Webhook署名検証・重複イベント・応答処理
  6. PostgreSQL公式:一意制約と複合キー

サイトをさらに整える

ネットワーク、注文、資金通知まで、業務に合わせて各段階を確認します。決済導入やUSDT監視については、お問い合わせページからご相談ください。

稳付payに問い合わせる ↗