Payment API

Payment API を使用すると、決済セッションの作成、ホスト型チェックアウトへの顧客のリダイレクト、決済ステータスの追跡が可能です。

支払いを作成する

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

ホスト型チェックアウト、H2H、および正確な暗号通貨の金額

同じエンドポイントは、3つの異なる請求書形式をサポートします。1つを意図的に選択してください。金額の意味を混同しないでください。

支払者選択付きホスト型チェックアウト

amount、currency、order_id、およびurl_callbackを送信しますが、to_currencyおよびnetworkは省略します。レスポンスにはresult.urlが含まれます；address、qr、および場合によっては支払者フィールドは、支払者がホストページで方向を選択するまでnullのままです。

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

直接アドレスH2H請求書

両方の to_currency と network を送信してください。2328.io は API 呼び出し中にブロックチェーン請求書を作成するため、カスタマーをリダイレクトせずにチェックアウト内で正常なレスポンスを表示できます。

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

これらの値は返されたまま正確に表示してください:

• payer_amount と payer_currency — 支払い指示;
• network と address — この請求書の唯一の送付先;
• qr — 同じアドレスのデータURI;
• expires_at — 請求書の期限;
• url — カスタムチェックアウトが完了できない場合の便利なホスト型バックアップ。

正確な暗号通貨の量に対する請求書

請求書自体が暗号通貨で表示されている場合、暗号通貨をcurrencyに入れてください:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

要求された暗号通貨の値はpayer_currency / payer_amountで保持されます。サービスは会計およびレートフィールド用に内部でUSD評価額を保持することもできますが、正確な暗号通貨の指示をその評価額に置き換えないでください。小数点以下の精度を含む返された文字列はそのまま保持してください。

サポートされているネットワークが1つしかない暗号通貨の場合、ネットワークは自動的に選択されることがあります。決定論的な統合のためには、明示的にnetworkを指定することを推奨します。ステーブルコインのようなマルチネットワーク資産の場合は、必ず送信してください。

冪等性と再試行

order_idは認証されたマーチャントプロジェクトにスコープされ、作成の冪等性キーとして機能します。支払いがすでに存在する場合、APIはstate: 0とともにそのセッションを返します。

推奨作成アルゴリズム:

1. ローカルの支払い試行とユニークなorder_idを1つのデータベーストランザクションで挿入してください。
2. 署名済みAPIリクエストを送信してください。
3. 返されたuuidと完全なレスポンスを保持してください。
4. HTTP結果が失われた場合、同一のリクエストを再試行するか、/v1/payment/infoをorder_idで照会してください。
5. 上流のリクエストがタイムアウトしたからといって、二つ目のローカル注文を作成してはいけません。

支払いのエッジケース

ブラウザの戻りURLはナビゲーション用のみです。顧客は支払いをせずに開くことも、支払い後に閉じることも、後で再度開くこともできます。商人の注文を確定できるのは、確認済みのAPI/ウェブフック状態のみです。

支払い情報

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

支払い一覧

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"