# Payment API

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

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

## 支払いを作成する

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

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

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `amount` | decimal | yes | 通貨での支払い金額。例：`100.00` |  |
| `currency` | string | yes | 法定通貨（USD、EUR、RUB、…）または暗号資産（USDT、TRX、BTC、…） | `USD`, `EUR`, `RUB`, `KZT`, `UAH`, `UZS`, `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `order_id` | string | yes | 注文 ID。例：`ORDER-12345`（最大 128 文字） |  |
| `to_currency` | string | no | 事前選択する暗号資産 | `USDT`, `USDC`, `BTC`, `ETH`, `GRAM`, `SOL`, `TRX`, `BNB`, `POL`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `network` | string | no\* | ネットワークコード（`to_currency` が指定されているか、`currency` が暗号資産の場合は必須） | `TRX-TRC20`, `ETH-ERC20`, `BASE`, `BSC-BEP20`, `AVAX-C`, `POL-MATIC`, `TON`, `SOL`, `BTC`, `LTC`, `DASH`, `DOGE`, `ZEC`, `XRP`, `XMR` |
| `url_return` | string | no | 支払い後のリダイレクト URL。例：`https://your-site.com/return` |  |
| `url_success` | string | no | `url_return` の代替 |  |
| `url_callback` | string | yes | 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`。支払者の通貨が選択されると埋まります。

> Use your project UUID and the endpoint-appropriate API key from the merchant dashboard.

#### Interactive request: `POST /v1/payment`
  - `amount` (decimal, required)
  - `currency` (enum, required): USD,EUR,RUB,KZT,UAH,UZS,USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `order_id` (string, required)
  - `to_currency` (enum): USDT,USDC,BTC,ETH,GRAM,SOL,TRX,BNB,POL,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `network` (enum): TRX-TRC20,ETH-ERC20,BASE,BSC-BEP20,AVAX-C,POL-MATIC,TON,SOL,BTC,LTC,DASH,DOGE,ZEC,XRP,XMR
  - `url_return` (string)
  - `url_success` (string)
  - `url_callback` (string, required)
  - `invite_code` (string)
  - `fee_split` (decimal)
  - `price_markup` (decimal)
  - `description` (string)
  - `ttl_seconds` (integer)

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

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

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

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

```json
{
  "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 呼び出し中にブロックチェーン請求書を作成するため、カスタマーをリダイレクトせずにチェックアウト内で正常なレスポンスを表示できます。

```json
{
  "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` — カスタムチェックアウトが完了できない場合の便利なホスト型バックアップ。

> **DANGER:** 住所を生成したり、他の請求書の住所を使い回したり、公開スポット価格から`payer_amount`を計算したりしてはいけません。APIの応答が権威あるものです。

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

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

```json
{
  "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`とともにそのセッションを返します。

> **WARNING:** 同じ`order_id`での再試行は**「この請求書を更新する」ことを意味する**わけではありません。既存のセッションが返されるため、変更された金額、通貨、コールバック、マークアップ、TTL、または方向フィールドは無視される場合があります。最初のリクエストを保持し、競合する再試行は自分のアプリケーションで拒否してください。

推奨作成アルゴリズム:

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

## 支払いのエッジケース

| 状況 | 正しい処理 |
|-----------|------------------|
| `address` / `qr` は `null` です | 支払者方向が初期化されていません。`url` にリダイレクトするか、新しい `order_id` を使って正しく指定された新しい H2H 請求書を作成してください。 |
| HTTP `400` バリデーションエラー | フィールドレベルの `errors` を読み取って、入力を変更せずに再試行しないでください。 |
| HTTP `429` | ジッター付き指数バックオフで再試行し、同じ `order_id` を保持してください。 |
| HTTP `503` / `direction_disabled` | リフレッシュ `/v1/directions`; 方向を一時的に非表示にするか、後で再試行してください。 |
| クライアントのリクエストがタイムアウトしました | 結果を不明として扱います。他のものを作成する前に `order_id` で問い合わせてください。 |
| `underpaid_check` | 部分的なイベントを保存し、追加または後のステータスを待ちます。追加のtxidが届いた場合でも二重でクレジットしないでください。 |
| `underpaid` | 最終未払い状態。実際にクレジットされた金額に対して、設定した履行/手動確認ポリシーを適用してください。 |
| `overpaid` | 余剰資金を伴う成功した支払い。冪等的に履行し、実際の金額を照合/払い戻しポリシーのために保持してください。 |
| `aml_lock` | 自動で履行や資金解放を行わず、コンプライアンス/サポートワークフローにルーティングしてください。 |
| `cancel` | 請求書は期限切れになったか、キャンセルされました。遅延したオンチェーンの送金が不可能だと推測しないでください。後のイベントはサポートと照合してください。 |

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

## 支払い情報

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

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

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

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

#### Interactive request: `POST /v1/payment/info`
  - `uuid` (string)
  - `order_id` (string)

## 支払い一覧

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

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

| Field | Type | Required | Description | Values |
|-------|------|----------|-------------|--------|
| `status` | string | no | 支払いステータスでフィルタ（[References](/docs/references) を参照） | `pending`, `check`, `paid`, `underpaid_check`, `underpaid`, `overpaid`, `cancel` |
| `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` |  |

#### Interactive request: `POST /v1/payment/list`
  - `status` (enum): pending,check,paid,underpaid_check,underpaid,overpaid,cancel
  - `date_from` (string)
  - `date_to` (string)
  - `page` (integer)
  - `per_page` (integer)