Sign in
简介/基本信息

概述

与 2328.io 集成加密货币支付处理和提现的技术规范。

查看 Markdown·llms.txt

欢迎阅读 2328.io API 文档。本参考文档介绍如何将加密货币支付处理和提现集成到您的应用程序中。

快速开始

开始集成的步骤：

  1. 在 2328.io 创建商户账户和项目
  2. 从项目设置中获取您的 project UUID 和 API key
  3. 如果计划使用提现功能，请生成一个独立的 Payout API key
  4. 阅读 Authentication 部分，了解如何对请求签名
  5. 进行第一次 Create Payment 调用

基础 URL

所有生产环境 API 请求均使用以下基础 URL：

Text
https://api.2328.io/api

所有请求必须通过 HTTPS 发起。未使用 HTTPS 的请求将被阻止。

您可以做什么

借助 2328.io API，您可以：

  • 接受加密货币支付 — 创建支付会话，并将客户重定向至托管收银台或 Telegram MiniApp
  • 提现资金 — 通过编程方式将商户余额发送到任意区块链地址
  • 查询余额 — 查看每种币种的商户账户余额、美元等值以及因 AML 锁定的金额
  • 使用静态钱包 — 生成与用户或订单绑定的永久存款地址
  • 获取汇率 — 实时获取法币和加密货币交易对的汇率
  • 接收 webhook — 在支付状态变化时立即收到通知

频率限制

API 限制为 每个项目每秒 10 次请求。超过限制的请求会收到 HTTP 429 Too Many Requests，请等待后重试。

选择正确的集成模式

要求推荐图案为什么
让客户选择付款方式Hosted checkout创建付款并重定向至 result.url； 2328.io 呈现当前可用的方向。
让顾客留在您自己的结账台内直接地址 H2H invoice创建付款时发送to_currency和network；渲染返回的address、payer_amount和qr。
准确收费 25 USDT 或 0.001 BTC加密货币计价 invoice将加密货币放入 currency，将精确的小数金额放入 amount。
为每个用户提供一个可重复使用的充值地址Static wallet该地址是永久的，可以接收许多独立的存款。
将传入资产标准化为一种平衡货币Auto-convert在仪表板中配置项目规则，并在转换完成时使用 convert 结果。
兑换现有 merchant 余额Manual convert使用 /v1/convert/price 进行预览，然后使用 /v1/convert 执行。
将资金发送到区块链地址支出使用单独的付款 API 密钥，首先计算并核对付款状态。

Hosted checkout 和 H2H 是同一支付 API 的两个呈现。 H2H 不会创建较弱或未签名的付款：backend 仍然创建 invoice，2328.io 仍然拥有地址和状态，并且签名的 webhooks 仍然具有权威性settlement。

积分不变量

这些规则适用于每个 production 集成：

  • 仅后端 — 使 API 密钥远离浏览器、移动应用程序、日志、分析和支持屏幕截图。
  • 十进制字符串 — 以字符串形式发送和存储资金。切勿使用二进制浮点运算对加密货币或汇率进行舍入。
  • Immutable idempotency keys — 在第一个请求之前生成 order_id 并用它保存完整的请求。具有相同 order_id 的 retry 可以返回原始对象，而不是应用更改的字段。
  • Webhook-first 结算 — 重定向、客户端轮询、用户提供的交易哈希和 HTTP 超时不是付款证明。
  • 验证、删除重复，然后进行变异 — 验证 HMAC，自动声明 idempotency 记录，更新订单/余额一次，并快速返回 HTTP 200。
  • Reconciliation — 定期查询付款、静态钱包和付款状态，因此丢失的 webhook 不会留下永久的分歧。
  • 动态可用性 — 使用 /v1/directions 验证货币/网络对；支持的资产仍可以暂时禁用一个存款或取款方向。
  • 显式状态策略 — 决定您的产品在上线前如何处理部分付款、超额付款、到期、AML 锁定、转换 fallback 以及不明确的上游超时。

对于付款，至少存储 uuid、order_id、原始请求正文、amount、currency、payer_currency、payer_amount、 network、address、expires_at、最新payment_status、txid、payment_amount、 merchant_amount、可选的 convert 块和原始验证的 webhook payload。

对于 static wallets，请将钱包 uuid、地址、货币、网络、客户/账户参考、状态和回调 URL 与存款记录分开保存。每笔存款需要有自己的交易uuid、txid、状态、收到金额、merchant金额和转换结果。