POST/api/v2/checkout

创建订单

供商户服务端（Backend）发起创建一笔全新的数字货币支付或挂单账单。成功创建后将返回 cregis_id（系统流水号，务必存储）和 checkout_url（带时效的收银台链接）。

频率限制： 1000 次/分钟

请求

请求体

required

application/json

noncestringrequired
6位随机字符串
pidinteger<int64>required
Cregis中该收单项目的唯一编号
signstringrequired
对该接口请求进行的数字签名以防止非法请求，请参考签名规则章节。
timestampinteger<int64>required
13位unix时间戳格式
order_amountstringrequired
付款总额（如order_currency是法币，则以法币金额计算／如order_currency是加密货币，则以加密货币金额计算）
order_currencystringrequired
请参阅订单货币列表
- 如订单币种为加密货币，例子为USDT、ETH等。
- 如订单币种为法币：则填入ISO 4217 3 位字元货币代码。例子为HKD、USD等。
order_idstringrequired
商家内部的订单编号【不超过128位字符】
payer_idstringrequired
付款人编号
valid_timeintegerrequired
单位：分钟（可填写：10 到 1440 的整数）

订单的有效时间。如超过有效时间，将不可以再支付。
success_urlstringrequired
付款成功后，点击“返回商店”按钮，付款人将被重定向到此 URL。请确保 URL 中包含“http://”或“https://”
cancel_urlstringrequired
如果付款人不付款或点击“取消”按钮，则定向至此 url。请确保 url 中包含“http://”或“https://”。
order_detailsstring<json>
订单商品明细包括价格、数量和商品描述。这显示在 Cregis 结帐页面的订单详情部分
JSON 内部字段application/json
- shopping_costnumber
  运费
- tax_costnumber
  消费税
- itemsarray
  税项
  数组元素
  item_idstring
  商品唯一ID
  item_namestring
  商品名称
  item_pricenumber
  商品价格
  price_currencystring
  请参阅订单货币列表
  item_quantityinteger<int64>
  商品数量
sub_merchantstring<json>
商户可使用此字段来记录内部子商户的编号
JSON 内部字段application/json
- sub_merchant_idstring
  子商户唯一编号
- sub_merchant_namestring
  商户名称
payer_emailstring
付款人邮箱，若accept_partial_payment或accept_over_payment为false则必填
tokensstring
此字段中可限制您允许客户支付的代币。如此字段留空，则表示接受支持所有代币作为支付代币。请参阅支付货币列表

填写参数可参考付款及结算参数页面内支付货币及支付网络的单位：例如：USDT-BEP20、USDT-TRC20等
payer_namestring
付款人姓名，不超过 32 位字符
stablecoin_realtime_ratestring
default: "false" · enum: "true", "false"
默认值：false
- false代表 USDT/USDC 兑 USD 使用固定1:1的汇率
- true代表 USDT/USDC兑USD 使用从CoinMarketCap上获取的实时汇率
underpaid_tolerancenumber<float>
default: 0
部分支付限额。该订单可接受的支付金额容差下限，单位为 order_currency，默认值为 0。

此容差下限用于计算订单可接受的最少支付金额。状态判断规则：
- paidorder_amount - underpaid_tolerance <= 实际支付金额 <= order_amount + overpaid_tolerance
- partial_paid实际支付金额 < order_amount - underpaid_tolerance
- overpaidorder_amount + overpaid_tolerance < 实际支付金额
示例：如果 order_currency 为 HKD，且 underpaid_tolerance 为 3.50：
- paid订单少付金额小于或等于 3.50 HKD
- partial_paid订单少付金额超过 3.50 HKD
overpaid_tolerancenumber<float>
default: 0
超额支付限额。该订单可接受的支付金额容差上限，单位为 order_currency，默认值为 0。

此容差上限用于计算订单可接受的最多支付金额。状态判断规则：
- paidorder_amount - underpaid_tolerance <= 实际支付金额 <= order_amount + overpaid_tolerance
- partial_paid实际支付金额 < order_amount - underpaid_tolerance
- overpaidorder_amount + overpaid_tolerance < 实际支付金额
示例：如果 order_currency 为 HKD，且 overpaid_tolerance 为 3.50：
- paid订单多付金额小于或等于 3.50 HKD
- overpaid订单多付金额超过 3.50 HKD
accept_partial_paymentstring
default: "true" · enum: "true", "false"
默认值：“true”
- false如订单不接受部分支付及实际支付金额少于order_amount时，付款人需对订单进行补款或进行退款
- true如订单接受部分支付，即允许付款人不需对订单进行补款或退款
accept_over_paymentstring
default: "true" · enum: "true", "false"
默认值：“true”
- false如订单不接受超额支付及实际支付金额大于order_amount时，付款人需对订单进行差价退款
- true如订单接受超额支付，即允许付款人不需对订单进行差价退款
callback_urlstring
Cregis 会向此回调地址发送订单状态更新的通知，回调详情参考订单支付通知
languagestring
default: "en" · enum: "en", "tc", "sc"
默认值：en

用于指定收银台或邮件的默认语言，可选值为：
- en英文
- tc繁体中文
- sc简体中文
remarkstring
商户可对这笔支付订单做出备注【不超过256位字符】

响应

200成功

application/json

codestring
返回码
msgstring
返回信息
dataobject
- cregis_idstring
  Cregis唯一识标
- checkout_urlstring
  收银台链接
- merchant_namestring
  收银台展示的商户名称
- merchant_logo_urlstring
  收银台展示的商户logo
- order_amountstring
  订单金额
- order_currencystring
  订单货币代码
- created_timeinteger<int64>
  订单创建时间以13位unix时间戳格式
  
  e.g. 1720508269092 , i.e. 2024-07-09 14:57:49 092
- expire_timeinteger<int64>
  订单失效时间以13位unix时间戳格式
  
  e.g. 1720508269092 , i.e. 2024-07-09 14:57:49 092
- payment_infoarray<object>
  订单相关讯息
  数组元素 · object
  payment_addressstring
  充值地址
  token_symbolstring
  支付币种符号。表示加密货币资产本身的代码，例如 USDT、BTC、ETH；不包含区块链网络信息。
  blockchainstring
  货币网络
  token_namestring
  链上币种展示名称。用于区分同一资产在不同网络或协议标准下的版本，例如 USDT-TRC20、USDT-ERC20。
  logo_urlstring
  货币logo地址
  token_decimalsinteger
  货币精度
  receive_amountstring
  汇率转换后的订单金额
  receive_currencystring
  汇率转换后订单货币代码
  exchange_ratestring
  货币汇率
  asset_logostring
  资产标识logo

在线测试

该接口由服务端签名，无需在此填写密钥。

请求体 (JSON)

请求示例

application/json

{
  "nonce": "m8jisx",
  "pid": 1382528827416576,
  "sign": "cebd2bfd56766f1143dc40d078b64dac",
  "timestamp": 1687848653294,
  "order_amount": "5.00",
  "order_currency": "HKD",
  "order_id": "merchant_order_YYYYMMDDhhmmssms",
  "payer_id": "user_001",
  "payer_email": "[email protected]",
  "payer_name": "张三",
  "valid_time": 30,
  "callback_url": "https://your-domain.com/webhook/order",
  "success_url": "https://your-domain.com/payment/success",
  "cancel_url": "https://your-domain.com/payment/cancel",
  "language": "sc",
  "remark": "季度会员续费"
}

响应示例

200 · application/json

{
  "code": "00000",
  "msg": "ok",
  "data": {
    "cregis_id": "po1420761885130752",
    "checkout_url": "https://pay.cregis.io?cid=b2fb433c953a43bd9bdfc3f611567887",
    "merchant_name": "My Shop",
    "merchant_logo_url": "https://your-domain.com/logo.png",
    "order_amount": "5.00",
    "order_currency": "HKD",
    "created_time": 1687848653294,
    "expire_time": 1687850453294,
    "payment_info": [
      {
        "payment_address": "TMainWalletAddressXXXXXXXXXXXXXXXXXX",
        "token_symbol": "USDT",
        "blockchain": "TRON",
        "token_name": "USDT-TRC20",
        "logo_url": "https://static.cregis.io/pic/coin/USDT-TRX.png",
        "token_decimals": 6,
        "receive_amount": "5.123456",
        "receive_currency": "USDT",
        "exchange_rate": "0.9775",
        "asset_logo": "https://cdn.cregis.com/tokens/usdt.png"
      }
    ]
  }
}