支付与提现/Payment API

支付 API

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

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

创建支付

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

请求参数

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

请求参数

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

支付列表

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

请求参数

字段	类型	必需	描述
`status`	string	否	按支付状态过滤（详见 References）
`date_from`	date	否	起始日期（YYYY-MM-DD），例如 `2026-01-01`
`date_to`	date	否	结束日期（YYYY-MM-DD），例如 `2026-01-31`
`page`	int	否	页码，默认 `1`
`per_page`	int	否	每页条数，默认 `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.