# Payment API

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

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

## 支払いを作成する

<TwoCol>

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

### リクエストパラメータ

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

<TwoColAside>

<Credentials />

<TryIt endpoint="POST /v1/payment">
  <Param name="amount" type="decimal" required />
  <Param name="currency" type="enum" required values="USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="order_id" type="string" required />
  <Param name="to_currency" type="enum" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" />
  <Param name="network" type="enum" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" />
  <Param name="url_return" type="string" />
  <Param name="url_success" type="string" />
  <Param name="url_callback" type="string" />
  <Param name="invite_code" type="string" />
  <Param name="fee_split" type="decimal" />
  <Param name="price_markup" type="decimal" />
  <Param name="description" type="string" />
  <Param name="ttl_seconds" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>

## 支払い情報

<TwoCol>

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

### リクエストパラメータ

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `uuid` | string | yes\* | 支払い UUID（作成時の `result.uuid`） | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | yes\* | 注文 ID | <InputValue name="order_id" placeholder="ORDER-12345" /> |

> **INFO:** `uuid` または `order_id` のいずれかが必須です。

<TwoColAside>

<TryIt endpoint="POST /v1/payment/info">
  <Param name="uuid" type="string" />
  <Param name="order_id" type="string" />
</TryIt>

</TwoColAside>

</TwoCol>

## 支払い一覧

<TwoCol>

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

### リクエストパラメータ

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `status` | string | no | 支払いステータスでフィルタ（[References](/docs/references) を参照） | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | no | 開始日（YYYY-MM-DD）。例：`2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | no | 終了日（YYYY-MM-DD）。例：`2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | no | ページ番号、デフォルトは `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | no | 1 ページあたりの件数、デフォルトは `15`、最大 `5000` | <InputValue name="per_page" type="integer" example="15" /> |

<TwoColAside>

<TryIt endpoint="POST /v1/payment/list">
  <Param name="status" type="enum" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" />
  <Param name="date_from" type="string" />
  <Param name="date_to" type="string" />
  <Param name="page" type="integer" />
  <Param name="per_page" type="integer" />
</TryIt>

</TwoColAside>

</TwoCol>