決済と出金/Payment API

Payment API

2328.io Payment API で暗号資産決済セッションを作成・管理します。

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

支払いを作成する

決済セッションを作成し、顧客が支払うための URL を返します。

リクエストパラメータ

Field	Type	Required	Description
`amount`	decimal	yes	通貨での支払い金額。例：`100.00`
`currency`	string	yes	法定通貨（USD、EUR、RUB、…）または暗号資産（USDT、TRX、BTC、…）
`order_id`	string	yes	注文 ID。例：`ORDER-12345`（最大 128 文字）
`to_currency`	string	no	事前選択する暗号資産
`network`	string	no*	ネットワークコード（`to_currency` が指定されているか、`currency` が暗号資産の場合は必須）
`url_return`	string	no	支払い後のリダイレクト URL。例：`https://your-site.com/return`
`url_success`	string	no	`url_return` の代替
`url_callback`	string	no	Webhook 通知の URL。例：`https://your-site.com/webhook`
`invite_code`	string	no	紹介コード
`fee_split`	decimal	no	支払者に転嫁するマーチャント手数料の割合、0〜100（%）。0 = マーチャントが全額負担、100 = 支払者が全額負担。プロジェクトレベルの設定を上書きします。例：`30`（支払者が手数料の 30% を負担）。
`price_markup`	decimal	no	請求金額の上乗せまたは値引き、−99〜100（%）。プロジェクトレベルの設定を上書きします。例：`5`（+5%）または `-10`（10% 割引）。
`description`	string	no	任意の請求説明（最大 200 文字）。決済ページで支払者に表示されます。例：`Premium plan — Order #12345`。
`ttl_seconds`	int	no	請求の有効期間（秒）。`300`（5 分）〜`86400`（24 時間）。この期間を過ぎると請求は失効し、支払いできなくなります。デフォルト：`3600`（1 時間）。例：`3600`。

レスポンス

JSON

{
  "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..."
  }
}

顧客を result.url にリダイレクトして支払いを完了させます。
tg_deeplink — Telegram MiniApp 経由で支払うための Telegram ボットディープリンク。
qr — 入金アドレスの Base64 エンコード QR コード（data URI）。アドレスがすでに割り当てられているとき（network が to_currency と一緒に指定されているか、currency が暗号資産のとき）に存在します。それ以外は null です。
txid、payment_amount — 顧客が支払うまでは null。トランザクションがオンチェーンで検出されると埋まります。タイミングを知るには payment_status: paid の Webhook を待ち受けてください。
exchange_rate — まだ換算が適用できない場合（例：法定通貨 → 暗号資産のレートが固定されていない場合）は null。支払者の通貨が選択されると埋まります。

Credentials

Project UUIDAPI key

RequestPOST/v1/payment

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"

Response

Click Try it to see the response here.

支払い情報

uuid または order_id で現在の支払いステータスを取得します。

リクエストパラメータ

Field	Type	Required	Description	Values
`uuid`	string	yes*	支払い UUID（作成時の `result.uuid`）
`order_id`	string	yes*	注文 ID

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

RequestPOST/v1/payment/info

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"

Response

Click Try it to see the response here.

支払い一覧

フィルタリングおよびページネーション付きで、すべての支払いの一覧を取得します。

リクエストパラメータ

Field	Type	Required	Description
`status`	string	no	支払いステータスでフィルタ（References を参照）
`date_from`	date	no	開始日（YYYY-MM-DD）。例：`2026-01-01`
`date_to`	date	no	終了日（YYYY-MM-DD）。例：`2026-01-31`
`page`	int	no	ページ番号、デフォルトは `1`
`per_page`	int	no	1 ページあたりの件数、デフォルトは `15`、最大 `5000`

RequestPOST/v1/payment/list

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"

Response

Click Try it to see the response here.