创建订单

订单创建订单创建区块链订单加密货币收款单

本文档描述了 Spell 中的订单创建，以及其 API 的使用方式。

已注册并完成认证的商户/个人可以通过 Web 界面或 API 请求来创建加密货币收款订单。在 Web 界面创建订单时，以下字段不可用：

  • 组编号group_no（不支持）
  • 订单号order_no（自动生成）
  • 跳转地址return_url（不支持）
  • 超时时间timeout（默认 30 分钟）

创建收款单 Invoice

预配置收款单支持默认的两种链上确认方式：

  • ID确认：将订单 ID 作为额外数据进行编译后加入区块链的转账信息中，支付完成后通过匹配订单 ID 进行支付确认。
  • 尾额确认：在订单金额后添加一个尾额（tail），当用户发起区块链转账时，将订单金额+尾额作为定位订单的方式来进行支付确认。

准备工作

发起 API 请求前需要先进行如下准备：

  • 获取支持的区块链列表：GET /api/v1/chain
  • 获取支持的币种列表：GET /api/v1/token
  • 获取已经创建的地址列表：GET /api/v1/address

预创建的地址列表中选择的区块链、币种必须完全匹配。请求到的数据可以做本地缓存，从而加快请求的准备。

请求

  • 端点：POST /api/v1/order/create/invoice
  • 请求头：
    • X-API-Key: '<API Key>'
    • X-Signature: '<SIGNATURE>'（签名生成请参考：API密钥）
  • 请求体限制条件：
    • 每个地址address下的订单号order_no不可重复，即：UNIQUE(address, order_no)
    • 采用尾额确认方式的待支付订单中，地址、币种、金额、尾额不能重复，即：UNIQUE(address, token, amount, tail) WHERE status = 0 AND type = 'tail'

      因为我们需要这样的唯一组合来匹配对应的区块链转账交易

请求体：
参数名称类型必填其他要求参数描述
typestring是“id” 或 “tail”订单确认类型
chainstring是15位从支持的区块链列表中获取的链ID
tokenstring是15位从支持的币种列表中获取的币种ID，注意不是直接填写代币合约地址
addressstring是15位从获取的已创建地址列表中获取的地址ID，注意不是直接填写钱包地址
amountnumber是不可为0或负数，最多支持2位小数订单金额，单位为所选的币种
group_nostring否6~30位组编号，可将多笔订单进行分组
order_nostring否6~30位订单号，可用于匹配自有系统的订单号。留空则自动生成15位随机订单号
tailstring否4位数字且最后一位不可为零尾额，仅在type为tail时需要，不提供则自动生成
timeoutnumber否60 ~ 86400订单超时时间，单位为秒，留空则自动生成1800秒（30分钟）超时时间
notify_urlstring否https://开头订单支付成功后后端的通知地址（POST请求）
return_urlstring否https://开头订单支付成功后前端的跳转页面
notestring否展示收款用途或款项名称。将会展示在支付页面及收据中。

通知地址

对于配置了通知地址（Notify URL）的订单，在支付成功后，支付页面会立即将支付成功的订单信息 POST 到该地址。您的服务器可以通过解析接收到的请求来进行订单的相关处理。该请求的请求体中包含了订单相关的信息JSON格式：

// notify body
{
  "id": "order.id", // xxxxxxxxxxxxxxx
  "group_no": "order.group_no",
  "order_no": "order.order_no",
  "chain": "chain.name", // ETH, BSC, ...
  "address": "address.address", // 0x...
  "token": "token.address", // 0x...
  "amount": "full_amount_with_tail",
  "pay_time": "order.pay_time", // ISO
  "transaction": TokenTx,
  "locale": "en" // 前端界面的语言
}
// TokenTx
interface TokenTx {
    blockNumber: string;
    timeStamp: string;
    hash: string;
    nonce: string;
    blockHash: string;
    from: string;
    contractAddress: string;
    to: string;
    value: string;
    tokenName: string;
    tokenSymbol: string;
    tokenDecimal: string;
    transactionIndex: string;
    gas: string;
    gasPrice: string;
    gasUsed: string;
    cumulativeGasUsed: string;
    input: string;
    confirmations: string;
}

注意：由于请求被拦截、目标服务器不可用、网络波动等原因，该通知可能会失败，因此请务针对重要的支付事件进行回调配置。

跳转地址

在对通知地址的请求（如有）处理完毕后，支付页面会将浏览器页面跳转到该跳转地址（Return URL），可以用于返回您的网站页面，完成闭环。

响应

Content-Type: application/json

成功 200 
{
  "code": 200,
  "data": {
    "id": "order_id",
    "type": "tail", // id | tail
    "group_no": "",
    "order_no": "external_order_no",
    "user": "RELATION_RECORD_ID",
    "chain": "RELATION_RECORD_ID",
    "address": "RELATION_RECORD_ID",
    "token": "RELATION_RECORD_ID",
    "amount": 123,
    "tail": "5623", // empty for id type
    "status": 0, // 0: pending, 1: success, 2: overdue
    "pay_time": "", // empty when created
    "timeout": 1800, // seconds, default 1800
    "return_url": "https://domain.com/path",
    "created": "2022-01-01 10:00:00.123Z",
    "updated": "2022-01-01 10:00:00.123Z"
  }
}
失败 400 
{
  "code": 400,
  "message": "error message"
}

创建自定义转账（暂未开放）

暂未开放

©2025 Spell.im 版权所有