USDT入金の導入手順:TRC20・ERC20の受取、オンチェーン承認、残高記帳
USDT入金とは、利用者が加盟店自身のブロックチェーンアドレスへ支払い、加盟店システムが利用者のサイト内残高を増やすことです。稳付payは取引監視、承認条件の確認、業務通知を担当し、資金は加盟店ウォレットへ直接入り、代理受取や保管は行いません。実際のオンチェーン入金とサイト内残高は別々に記録し、確実な注文紐付けと冪等な記帳で接続してください。
この記事の目次
1.2つのネットワークと加盟店所有のウォレット
| 当サイトが対応するネットワーク | 資産の形式 | 導入時の照合事項 |
|---|---|---|
| Tron | USDT TRC20 | Tronネットワーク、検証済みUSDTコントラクト、加盟店の受取アドレス。 |
| Ethereum | USDT ERC20 | Ethereumネットワーク、検証済みUSDTコントラクト、加盟店の受取アドレス。 |
「USDT」という名称やトークンのアイコンだけで判断しないでください。Tether公式の対応プロトコル・コントラクト一覧 で該当ネットワークの資産を確認できます。同名トークンが自動的に対応USDTになるわけではありません。末尾数文字だけでなく完全なアドレスを照合してください。
顧客は加盟店が管理するウォレットへ直接支払います。監視の利用開始には必要な受取情報だけを提供し、稳付payへ秘密鍵やシードフレーズを渡しません。サイト内USDT残高は加盟店の業務台帳、ウォレット残高はオンチェーン資産であり、同じアカウントとして扱ってはいけません。
2.利用者注文を先に紐付け、識別方法を確認
加盟店は利用者ID、元チャージ注文番号、選択ネットワーク、資産、受取アドレス、支払予定数量、有効期限、記帳ルールを先に保存します。サイト内でポイントなど別の計価単位を使う場合は、今回の換算、精度、ボーナス規則のスナップショットも保存し、支払い後に勝手に変更しないでください。
送金を元注文へ対応付ける方法は、開通時に技術チームと確認する必要があります。注文ごとの新アドレス割当、memo入力、金額の自動微調整があると想定してはいけません。同じアドレスで複数利用者が同額を同時に払う場合、金額とおおよその時刻だけでは識別不十分です。確認済みの方法で照合し、一意に特定できなければ手動確認へ回します。
利用者に表示するネットワーク、加盟店アドレス、支払予定数量は、バックエンドの保存済み注文を元にします。本文はMERCHANT_WALLET_ADDRESS、ORDER_IDなどのプレースホルダーのみを使い、実際に送金できるサンプルアドレスは掲載しません。
アドレス変更は版と適用範囲を保持し、既存注文は元設定で照合します。分割払いの可否、累積方法、注文失効後の処理も事前合意が必要で、複数の同額送金を自動的に1人へまとめてはいけません。
3.オンチェーン支払いからサイト内残高までの6段階
- チャージ注文を作成利用者とネットワーク、資産、受取アドレス、支払予定数量を紐付けます。
- 利用者が確認して送金正しいネットワークを選び、加盟店自身のアドレスへUSDTを送ります。
- 候補取引を監視関連する送金イベントを識別し、取引とイベントの識別子を保存します。
- 実行結果と承認を検証実入金を照合し、選択ネットワークに設定された承認条件を待ちます。
- 加盟店が通知を認証専用の合意に従い送信元と内容を検証し、元注文と照合します。
- 原子的に記帳イベントの紐付け、チャージ台帳、利用者残高を同時に永続化します。
4.送金の検出だけでは承認条件を満たしたことにならない
ウォレットの「送信済み」表示、取引ハッシュの取得、ブロードキャスト成功、Transfer検出のいずれも、それ単独では残高記帳の根拠になりません。正しいネットワークでの実行結果、検証済みトークンコントラクト、実際の受取アドレス、USDT数量を照合してから承認条件の達成を判断します。取引が呼び出すコントラクトとイベント内の受取人も混同しないでください。
TRONの承認セマンティクス文書 はブロードキャスト、実行レシート、確定状態を区別します。確定チェーンに入っていても実行成功の確認が必要です。Ethereumの ファイナリティの説明 も、ブロックへの取り込みとファイナリティ達成を別の段階として扱います。
承認条件はネットワークと接続設定で決め、共通の固定秒数にはしません。ノードの索引遅延や一時的な照会失敗では元記録を保持して確認を続け、それだけで送金失敗と判断したり再送金を求めたりしないでください。
5.USDTコールバック仕様は個別に確認
開通時に技術担当者と通知認証、項目定義、承認規則、再送計画、応答内容、能動的な確認方法を明確にします。当サイトの既存Alipay・WeChat収納代行文書をそのままUSDT仕様として使い、そのMD5項目、通知回数、OK応答、状態一覧を流用してはいけません。
加盟店バックエンドは通知の真正性を検証してから、元注文、ネットワーク、トークンコントラクト、受取アドレス、実USDT数量、取引識別子、承認状況を照合します。利用者の所属は保存済み注文で決定し、ブラウザーの「支払い成功」申告や未認証通知を信頼しません。情報不足なら先に確認し、残高を直接加算しないでください。
通知を受け取ってもデータベース保存に失敗したら、合意した失敗処理と補完を行います。重複通知と能動確認の結果は同じ記帳入口へ渡します。認証と処理の記録を保持し、公開ログにはシークレットやウォレットの秘密情報を記録しません。
6.送金イベントで重複排除し、残高を原子的に更新
1件のオンチェーン取引に複数の送金イベントが含まれる場合があり、取引ハッシュだけで重複排除すると記録漏れや誤認につながります。「ネットワーク+txHash+logIndexまたはイベント順序番号」で内部の一意イベントキーを設計できます。これは業務識別子の例で、公開済みのプラットフォーム項目ではありません。索引の基準を統一し、対応ブロックとイベント証跡を保持して、同じ入金イベントを複数注文の支払いに重複充当しないようにします。
Ethereumのログ説明 には取引ハッシュ、ログ索引、チェーン再編で削除されたことを示すフラグがあります。承認の後退やイベント変化があれば自動処理を停止して元記録を確認し、新しい送金として再加算しないでください。
元注文の計上可能金額と状態もロックして照合します。重複支払い、過払い、分割払いは合意した規則で処理し、新しいイベントを見つけるたびに注文全額を再加算してはいけません。
通知を認証し、承認済みの入金イベントを検証
データベーストランザクション開始
元チャージ注文と利用者アカウントをロック
イベント一意キーと既存の関連注文を確認
このイベントをこの注文へ計上済みなら:再加算しない
他注文へ紐付け済みなら:競合を記録し、重複充当しない
それ以外:イベント紐付け、一意のチャージ記録、残高更新を保存
トランザクションをコミット
合意に従って処理結果を返す検証済みトークンコントラクトのdecimalsに従って最小単位の整数を扱い、固定小数点または正確な十進演算を使用し、USDT数量にfloatを使いません。元数量、換算結果、ボーナスを別々に保存し、失敗時は全体をロールバックします。重複や並行処理にはデータベース一意制約を使い、存在確認後の書き込みだけに頼らないでください。
例えばEVENT_AをORDER_Aへ計上済みなら、通知や確認結果が再び来ても元の処理結果を返します。別注文ORDER_BがEVENT_Aを紐付けようとした場合は競合として確認待ちにします。取引内の他イベントを記録することと、それらすべてが現在のチャージ注文に属することは別です。
7.遅延入金・金額差異・ネットワーク費用への対応
| 状況 | 処理原則 |
|---|---|
| 遅延入金 | 実入金を保持し、注文有効期限の規則で確認後、補完記帳または購入後対応を行います。 |
| 不足払い・過払い | 支払予定と実受取の差を記録し、合意に従って確認します。勝手に別注文へまとめません。 |
| 誤ったネットワーク・トークン | 自動記帳を止め、資産、アドレス、管理権限を確認して技術担当者へ連絡します。 |
| 承認の後退・結果不明 | イベントと元注文を保持して確認し、二重加算や即座の再送金要求をしません。 |
返金は相手、ネットワーク、数量、費用、権限を別途確認し、監視サービスが自動返金すると想定してはいけません。サイト内の取消仕訳は独立記録を残し、元記録削除で帳簿を変えません。サイト内状態を変更してもオンチェーン送金は自動で撤回されません。
自己所有のウォレットからのTRC20送信にはTronの帯域幅、エネルギー、場合によってTRX消費が関わり、Ethereumのガス代はETHで支払います。取引所からの出金では手数料と実際の送金数量も確認してください。費用はその時点のネットワークと送信ツールで確認し、全注文へ固定料率を当てはめません。
8.個別突合と導入検収
ネットワーク、コントラクト、アドレス、取引イベント、チャージ注文、記帳履歴、利用者残高を関連付けます。ウォレット総残高には他の入出金も含まれるため、増加額だけで特定利用者へチャージしません。加盟店所有ウォレットへの直接受取と、WeChat・Alipay収納代行後のUSDT精算も同じ資金経路として扱わないでください。
接続テストでは少なくとも、正常支払い、重複通知、能動確認との並行処理、1取引内の複数イベント、同アドレス同額注文、不足・過払い、遅延入金、データベースのロールバック、承認異常を検証します。イベント紐付けと最終残高を個別に照合し、記録漏れも重複もなく、同じイベントを2人へ割り当てないことを確認します。
資金は先に稳付payのウォレットへ入りますか?
いいえ。顧客は加盟店自身のアドレスへ直接支払い、プラットフォームは監視と通知だけを提供し、代理受取や保管を行いません。
オンチェーンで取引を見つけたらすぐ残高を増やしますか?
実行、資産、アドレス、金額、設定した承認条件を先に確認し、バックエンドで冪等に記帳します。
現在の対応範囲と料金はどう確認しますか?
TronとEthereumの2ネットワークの監視・通知は中小サイト運営者向けに無料です。企業向けサービスは別料金となります。技術チームと注文識別・通知設定を確認してください。独立した振込代行APIはまだ公開していません。
参考資料
公式資料は資産、オンチェーン承認、ネットワーク費用の確認に使用します。USDT監視・コールバックの実際の仕様、承認条件、注文識別ルールは、利用開始時に技術チームと確認した設定に従います。