商户买币接口文档 v1.0
业务接口
POST /api/buy-coin/transaction
描述:商户买币接口
传入参数列表
参数名称
必填项
参数类型
参数描述
buyCoinMode
Enum
USDD数量模式(UsddAmount)或支付金额模式(PaymentPrice)。默认为 UsddAmount 模式。 关于两种模式的区别,请看买币模式说明。
usddAmount
Decimal
【USDD数量模式必传】币的数量。
totalPrice
Decimal
【支付金额模式必传】总支付金额。
externalOrderNumber
String
外部订单号
callbackUrl
String
买币成功后回调地址。
supportLanguage
Enum
展示语言:en, zh_CN, zh_TW, vi, id。
currencyCode
Enum
所需支付币种:CNY, HKD, TWD, VND, AUD, USDT。
payerRealName
String
实际支付人姓名
买币模式说明
  • UsddAmount - 数量模式
    默认模式
    当选择此模式时,需要传入 usddAmount 字段,此时会通过所购币种的数量,筛选最优广告并生成订单。
  • PaymentPrice - 支付金额模式
    当选择此模式时,需要传入 totalPrice 字段,此时会通过支付币种与总金额数量,筛选最优广告并生成订单。
所需支付币种: USDT
  • 当支付币种为USDT时,买币模式只能是Amount - 数量模式.
  • usddAmount要求大于或等于50.
传出参数列表
参数名称
参数类型
参数描述
redirectUrl
String
所需跳转的支付 URI。
advertisementCode
String
此次交易所匹配的广告编码。
currentTimestamp
Long
当前 UTC 时间戳。
eth
String
币安智能链(BSC)的收款地址
trx
String
Tron链的收款地址

当此次买币操作完成后,系统将自动回调 callbackUrl 的接口,方式为 POST,并传入此 JSON 数据:

    {
        "success": true,
        "statusCode": "SUCCESS",
        "message": "",
        "signature": "鉴权签名", // 需要通过鉴权算法进行校验
        "timestamp": 1679533328342, // UTC 毫秒级时间戳
        "data": {
            "externalOrderNumber": "ORDER_CODE", // 外部订单号
            "transactionCode": "ATSA6E40D5FE7UZHE", // 订单编码
            "transactionAmount": 200.00, // 交易USDD数量
            "currencyCode": "CNY", // 支付币种
            "paymentPrice": 1000.00, // 支付金额
            "transactionCreateTime": "2023-03-01 00:00:00", // UTC 交易创建时间
            "paymentFinishedTime": "2023-03-01 02:00:00" // UTC 支付完成时间
        }
    }
    

当此次买币操作失败后,系统将自动回调 callbackUrl 的接口,方式为 POST,并传入此 JSON 数据:

    {
        "success": false,
        "statusCode": "TRADE_CANCELED",
        "message": "取消交易",
        "signature": "鉴权签名", // 需要通过鉴权算法进行校验
        "timestamp": 1679533328342, // UTC 毫秒级时间戳
        "data": {
            "externalOrderNumber": "ORDER_CODE", // 外部订单号
            "transactionCode": "ATSA6E40D5FE7UZHE", // 订单编码
            "transactionAmount": 200.00, // 交易USDD数量
            "currencyCode": "CNY", // 支付币种
            "paymentPrice": 1000.00, // 支付金额
            "transactionCreateTime": "2023-03-01 00:00:00", // UTC 交易创建时间
        }
    }
    

接口需要响应:

    "success" 或 {"success":true}
    

若响应其他内容,则默认响应失败,会自动进入重试逻辑;若所有重试均失败,则此次回调会标记为“回调失败”。

重试时间间隔如下表:

    00:01:00
    00:02:00
    00:03:00
    00:08:00
    00:38:00
    01:08:00
    02:08:00
    03:08:00
    04:08:00
    05:08:00
    06:08:00
    07:08:00
    08:08:00
    09:08:00
    10:08:00
    11:08:00