# 支付 API

> 使用 2328.io 支付 API 创建并管理加密货币支付会话。

支付 API 让您可以创建支付会话、将客户引导至托管支付页面，并跟踪支付状态。

## 创建支付

<TwoCol>

创建一个支付会话并返回供客户付款的 URL。

### 请求参数

| 字段 | 类型 | 必需 | 描述 | 取值 |
|------|------|------|------|------|
| `amount` | decimal | 是 | 该币种下的支付金额，例如 `100.00` | <InputValue name="amount" type="decimal" example="100.00" /> |
| `currency` | string | 是 | 法币（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 | 是 | 您的订单 ID，例如 `ORDER-12345`（最多 128 个字符） | <InputValue name="order_id" example="ORDER-12345" /> |
| `to_currency` | string | 否 | 预选的加密货币 | <EnumValues name="to_currency" values="USDT,USDC,BTC,ETH,TON,SOL,TRX,BNB,MATIC,XMR" optional /> |
| `network` | string | 否\* | 网络代码（当 `to_currency` 已设置或 `currency` 为加密货币时必填） | <EnumValues name="network" values="TRX-TRC20,ETH-ERC20,BSC-BEP20,TON,SOL,BTC,MATIC,XMR" optional /> |
| `url_return` | string | 否 | 支付完成后的跳转 URL，例如 `https://your-site.com/return` | <InputValue name="url_return" placeholder="https://your-site.com/return" /> |
| `url_success` | string | 否 | `url_return` 的替代项 | <InputValue name="url_success" placeholder="https://your-site.com/success" /> |
| `url_callback` | string | 否 | webhook 通知 URL，例如 `https://your-site.com/webhook` | <InputValue name="url_callback" example="https://your-site.com/webhook" /> |
| `invite_code` | string | 否 | 推荐人代码 | <InputValue name="invite_code" placeholder="ref_xyz" /> |
| `fee_split` | decimal | 否 | 由付款人承担的商户手续费比例（0–100，单位 %）。0 = 商户全额承担，100 = 付款人全额承担。覆盖项目级设置。**示例：`30`**（付款人承担 30%）。 | <InputValue name="fee_split" type="decimal" placeholder="30" /> |
| `price_markup` | decimal | 否 | 在账单金额上的加价或折扣（−99 到 100，单位 %）。覆盖项目级设置。**示例：`5`**（+5%）或 `-10`（10% 折扣）。 | <InputValue name="price_markup" type="decimal" placeholder="5" /> |
| `description` | string | 否 | 可选的账单描述（最多 200 个字符），将展示在付款页面。**示例：`Premium plan — Order #12345`**。 | <InputValue name="description" placeholder="Premium plan — Order #12345" /> |
| `ttl_seconds` | int | 否 | 账单有效期（秒），范围 `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 编码二维码（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` 获取当前支付状态。

### 请求参数

| 字段 | 类型 | 必需 | 描述 | 取值 |
|------|------|------|------|------|
| `uuid` | string | 是\* | 支付 UUID（创建时来自 `result.uuid`） | <InputValue name="uuid" example="abc123-def456-..." /> |
| `order_id` | string | 是\* | 您的订单 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>

获取所有支付的列表，支持筛选与分页。

### 请求参数

| 字段 | 类型 | 必需 | 描述 | 取值 |
|------|------|------|------|------|
| `status` | string | 否 | 按支付状态过滤（详见 [References](/docs/references)） | <EnumValues name="status" values="pending,check,paid,underpaid_check,underpaid,overpaid,cancel,aml_lock" optional /> |
| `date_from` | date | 否 | 起始日期（YYYY-MM-DD），例如 `2026-01-01` | <InputValue name="date_from" example="2026-01-01" /> |
| `date_to` | date | 否 | 结束日期（YYYY-MM-DD），例如 `2026-01-31` | <InputValue name="date_to" example="2026-01-31" /> |
| `page` | int | 否 | 页码，默认 `1` | <InputValue name="page" type="integer" example="1" /> |
| `per_page` | int | 否 | 每页条数，默认 `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>