決済と出金/固定ウォレット

固定ウォレット

特定の注文やユーザーに紐付く永続的な入金アドレス。継続的および長期の支払いに最適です。

Markdown で表示·llms.txt

固定ウォレットは、暗号資産の支払いを受け取るための永続的なアドレスです。特定の order_id にリンクされ、project_id + order_id + currency + network の組み合わせで一意になります。

固定ウォレットの用途：

同一ユーザーからの繰り返し入金
ユーザープロフィールに表示される長期的な支払いアドレス
ユーザーごとに安定したアドレスを必要とする大量入金フロー

固定ウォレットを作成する

POST/v1/static-wallet

リクエストパラメータ

Field	Type	Required	Description
`currency`	string	yes	暗号資産（USDT、BTC、ETH など）
`network`	string	yes	ネットワークコード
`order_id`	string	yes	注文／ユーザー ID（最大 255 文字）
`label`	string	no	ウォレットラベル（最大 255 文字）
`url_callback`	string	yes	Webhook 通知の URL
`invite_code`	string	no	紹介コード

リクエスト例

JSON

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

レスポンス例

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

ウォレット情報

uuid または address で固定ウォレット情報を取得します。

POST/v1/static-wallet/info

リクエストパラメータ

Field	Type	Required	Description
`uuid`	string	yes*	固定ウォレット UUID
`address`	string	yes*	ブロックチェーンウォレットアドレス

uuid または address のいずれかが必須です。

レスポンス例

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

total_received — このウォレットで受け取ったすべての入金の合計（currency 単位）。
transactions_count — これまでに受け取った入金回数。
qr — 入金アドレスの Base64 エンコード QR の data URI（固定ウォレットでは常に存在し、アドレスは作成時に割り当てられます）。

ウォレット一覧

POST/v1/static-wallet/list

リクエストパラメータ

Field	Type	Required	Description
`status`	string	no	ステータスでフィルタ（`active`、`inactive`）
`currency`	string	no	通貨でフィルタ
`network`	string	no	ネットワークでフィルタ
`order_id`	string	no	order_id でフィルタ
`page`	int	no	ページ番号（デフォルト：1）
`per_page`	int	no	1 ページあたりの件数（デフォルト：20、最大：100）

レスポンス例

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

ウォレットの有効化／無効化

固定ウォレットが新規支払いを受け付けるかどうかを切り替えます。

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

リクエスト

両方のエンドポイントは単一のパラメータを受け取ります：

JSON

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

レスポンス例

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

enable の場合、status は "active" になり、message は "Static wallet enabled successfully" となります。

ウォレットのトランザクション

固定ウォレットで受け取ったすべての入金の一覧を取得します。

POST/v1/static-wallet/transactions

リクエストパラメータ

Field	Type	Required	Description
`uuid`	string	yes	固定ウォレット UUID
`date_from`	date	no	開始日（YYYY-MM-DD）
`date_to`	date	no	終了日（YYYY-MM-DD）
`page`	int	no	ページ番号（デフォルト：1）
`per_page`	int	no	1 ページあたりの件数（デフォルト：15、最大：5000）

レスポンス例

JSON

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

fee_amount — この入金から差し引かれたプラットフォーム手数料（currency 単位）。
net_amount — 手数料控除後にマーチャント残高にクレジットされた金額。

固定ウォレットの Webhook

固定ウォレットで支払いが受領されると、システムが url_callback に Webhook を送信します。

固定ウォレットの Webhook 形式は、通常の支払い Webhook と異なります。特に、固定ウォレットの Webhook には merchant_amount フィールドが含まれており、クレジット計算にはこれを使用してください。

Webhook ペイロード

JSON

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "tx_explorer_url": "https://tronscan.org/#/transaction/8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

固定ウォレットの Webhook には url および expires_at は 含まれません（アドレスが永続的でセッションではないため）。exchange_rate および created_at は 含まれます。

フィールドリファレンス

Field	Type	Description
`uuid`	string	この入金のトランザクション（インボイス）UUID
`order_id`	string	固定ウォレットの `order_id`
`amount`	decimal (8 dp)	受領した暗号資産の金額
`currency`	string	受領した暗号資産（ウォレットの `currency` と一致）
`amount_usd`	decimal (8 dp)	受領時点の USD 換算額
`exchange_rate`	decimal	使用された暗号資産 / USD レート
`payer_currency`	string	固定ウォレットでは `currency` と同じ
`payer_amount`	decimal (8 dp)	固定ウォレットでは `amount` と同じ
`network`	string	ブロックチェーンネットワーク
`address`	string	固定ウォレットアドレス
`payment_status`	string	??????????? `paid` ????AML???????????????? `aml_lock` ??????????
`txid`	string	ブロックチェーントランザクションハッシュ
`tx_explorer_url`	string \| null	ブロックチェーンエクスプローラーのトランザクション URL。`txid` がない場合、または内部 P2P 送金の場合は `null`。
`payment_amount`	decimal (8 dp)	`amount` と同じ
`merchant_amount`	decimal (18 dp)	手数料控除後の金額 — クレジット計算にはこれを使用
`created_at`	string (ISO 8601)	入金が受領された日時
`sign`	string (hex)	ペイロードの HMAC-SHA256 署名

ベストプラクティス

ユニークな order_id — ユーザーや注文ごとにユニークな order_id を使用する
冪等性 — 重複クレジットを避けるため、処理前に txid をチェックする
署名の検証 — 資金をクレジットする前に必ず sign を検証する
merchant_amount を使用する — クレジットには payment_amount ではなく merchant_amount を使用する

ライフサイクルと冪等性

静的ウォレットは再利用可能な入金用IDであり、請求書ではありません。期待される金額も有効期限もありません。1つのアドレスはそのライフタイムの間に任意の数の入金トランザクションを生成できます。

作成は同じマーチャントプロジェクト、order_id、currency、network に対して冪等です：既存のウォレットが返されます。そのタプルを安定させ、返されたウォレットを uuid に保存してください；同じ顧客が入金画面を開くたびに新しい order_id を使用しないでください。

入金の冪等性はウォレットの冪等性とは異なります：

order_id は再利用可能なウォレット/顧客のマッピングを識別します；
ウォレット uuid は恒久的なウォレットレコードを識別します；
webhook uuid は検出された入金トランザクションの1つを識別します;
txid はオンチェーンの転送を識別し、顧客の内部残高にクレジットするための主要な重複排除キーです。

処理済みのチェーン/ネットワーク/txid の識別子に対してデータベースの一意制約を使用し、顧客の内部残高にクレジットする同じトランザクションで請求します。

有効化および無効化の意味

ウォレットを無効にすると、アプリケーションがそれをアクティブな入金先として処理するのを防ぎます; これはアドレスやその履歴を消去するものではなく、ユーザーによって既に送信されたブロックチェーン転送を止めることはできません。

ユーザーに対して、非アクティブなアドレスに送金された資金が自動的に返金されると伝えないでください。ブロックチェーンの送金は取り消しできません。UIからアドレスを削除した後にのみ無効化し、遅延入金に備えた運用上の回復手順を維持してください。

再有効化は同じウォレットIDおよびアドレスを保持します。ラベルを変更するためだけに新しいアドレスを作成しないでください。ラベルは決済識別子ではありません。

静的ウォレットのエッジケース

状況	正しい取り扱い
重複作成リクエスト	新しいアドレスを期待するのではなく、返却された既存のウォレットを受け入れ、その永続化されたタプルを確認してください。
1つのアドレスへの複数入金	各取引ごとに個別のローカル入金行を作成してください `uuid`/`txid`; ウォレット自体を「支払い済み」とマークしないでください。
ウェブフックの重複	すでにコミットされたtxidを見つけた後にHTTP 200を返してください; 再度クレジットしないでください。
確認遅延またはチェーンの再観察	処理を冪等性に保ち、`/v1/static-wallet/transactions`から調整してください。
自動変換の最小値未満の入金	完了した`convert`ブロックなしでソース通貨のクレジットを期待
自動変換成功	ソース支払い値と対象の`convert`結果を別々に保存
間違ったトークンまたは間違ったネットワーク	クレジットを捏造しないでください。証拠を記録し、回復可能性はチェーンごとに異なるため、サポート/回復部門にエスカレーションしてください。
メモ／タグベースのチェーン	プラットフォームが返すすべての宛先フィールドを表示して検証してください。メモが必要な場合、住所だけでは不十分な場合があります。
AMLロック	権限付与されたステータスがコンプライアンスプロセスを通じて解除されるまで、エンドユーザーにクレジットしないでください。
アドレス表示後にウォレットが無効化される	UIからただちに削除してください。それでも、遅延送金のオペレーショナルアラートは引き続き監視してください。

照合モデル

定期的なジョブを実行して/v1/static-wallet/transactionsをページングし、txidで入金をアップサートし、それらのmerchant_amount、ステータス、および任意のコンバージョン結果を内部台帳と比較します。Webhook配信は照合を迅速にするはずですが、照合は完全に行わなければなりません。