Sign in
はじめに/一般情報

概要

2328.io と統合して暗号資産の決済処理および出金を行うための技術仕様。

Markdown で表示·llms.txt

2328.io API ドキュメントへようこそ。本リファレンスでは、暗号資産の決済処理および出金をアプリケーションに統合する方法を説明します。

はじめに

統合を始めるには：

  1. 2328.io でマーチャントアカウントとプロジェクトを作成します
  2. プロジェクト設定から project UUID と API key を取得します
  3. 出金機能を利用する場合は、別途 Payout API key を生成します
  4. Authentication セクションを参照し、リクエストへの署名方法を確認します
  5. 最初の Create Payment 呼び出しを行います

ベース URL

すべての本番 API リクエストは以下のベース URL を使用します：

Text
https://api.2328.io/api

すべてのリクエストは HTTPS で行う必要があります。HTTPS を使用しないリクエストはブロックされます。

できること

2328.io API を利用することで、以下が可能です：

  • 暗号資産による決済の受付 — 決済セッションを作成し、ホスト型のチェックアウトページまたは Telegram MiniApp に顧客をリダイレクトします
  • 資金の出金 — マーチャント残高から任意のブロックチェーンアドレスへプログラム的に出金します
  • 残高確認 — 通貨ごとのマーチャント残高、USD 換算、AML でロックされた金額を確認できます
  • 固定ウォレットの利用 — ユーザーや注文に紐付く永続的な入金アドレスを生成します
  • 為替レートの取得 — 法定通貨と暗号資産のリアルタイムレートを取得します
  • Webhook の受信 — 支払いステータスが変化した際に即座に通知を受け取ります

レート制限

API はプロジェクトごとに 1 秒あたり最大 10 リクエスト を許可しています。制限を超えたリクエストは HTTP 429 Too Many Requests レスポンスを受け取ります — バックオフして再試行してください。

正しい統合パターンを選択してください

要件推奨パターン理由
顧客に支払い方法を選ばせるホスト型チェックアウト支払いを作成してresult.urlにリダイレクトします；2328.ioは現在利用可能な方向を提示します。
顧客を自分のチェックアウト内に留める直接アドレスH2H請求書支払いを作成するときにto_currencyとnetworkを送信します；返されたaddress、payer_amount、およびqrを表示します。
正確に25 USDTまたは0.001 BTCを請求する暗号通貨建て請求書暗号通貨をcurrencyに入れ、正確な小数点以下の金額をamountに入れてください。
各ユーザーに再利用可能な入金アドレスを提供する静的ウォレットこのアドレスは永久的で、複数の独立した入金を受け取ることができます。
入金された資産を1つの残高通貨に正規化する自動変換ダッシュボードでプロジェクトルールを設定し、変換が完了したらconvertの結果を使用します。
既存のマーチャント残高を交換する手動変換/v1/convert/priceでプレビューし、/v1/convertで実行します。
ブロックチェーンアドレスに資金を送金する支払い別のPayout APIキーを使用し、まず計算してから、支払いステータスを照合します。

ホスト型チェックアウトとH2Hは、同じPayment APIの二つの提示方法です。H2Hは弱いまたは署名されていない支払いを作成するわけではありません：バックエンドは引き続き請求書を作成し、2328.ioは引き続きアドレスとステータスを所有し、署名付きWebhookは決済において依然として権威を持ちます。

統合不変条件

これらのルールはすべての本番統合に適用されます:

  • バックエンド限定 — APIキーをブラウザ、モバイルアプリケーション、ログ、分析、サポートのスクリーンショットに含めないでください。
  • 10進文字列 — お金を文字列として送受信および保存します。暗号通貨や為替レートを二進浮動小数点算術で丸めてはいけません。
  • 不変の冪等性キー — 最初のリクエスト前にorder_idを生成し、リクエスト全体をそれと共に保持します。同じorder_idでの再試行は、変更されたフィールドを適用するのではなく、元のオブジェクトを返すことができます。
  • Webhook優先の決済 — リダイレクト、クライアントポーリング、ユーザー提供のトランザクションハッシュ、およびHTTPタイムアウトは支払いの証明にはなりません。
  • 検証、重複排除、その後に変更 — HMACを検証し、冪等性レコードを原子的に取得し、注文/残高を一度更新して、HTTP 200を迅速に返します。
  • 照合 — 支払い、静的ウォレット、支払い状況を定期的に確認し、ウェブフックの損失が恒久的な不一致を残さないようにする。
  • 動的な可用性 — /v1/directionsで通貨/ネットワークペアを検証する。サポートされている資産でも、入金または出金の一方向が一時的に無効になる場合がある。
  • 明示的なステータスポリシー — 製品を本番稼働させる前に、部分支払い、過払い、期限切れ、AMLロック、変換フォールバック、不明確な上流タイムアウトの処理方法を決定する。

支払いについては、最低でも uuid、order_id、元のリクエスト本文、amount、currency、payer_currency、payer_amount、network、address、expires_at、最新の payment_status、txid、payment_amount、merchant_amount、オプションの convert ブロック、および検証済みの生ウェブフックペイロードを保存してください。

静的ウォレットについては、ウォレット uuid、アドレス、通貨、ネットワーク、顧客/アカウント参照、ステータス、コールバックURLを入金記録とは別に保持してください。それぞれの入金には、独自のトランザクション uuid、txid、ステータス、受領額、マーチャント金額、変換結果が必要です。