购买 MTC (商户入金) API 文档

修订版本: v1.0.1.0

修订时间: 2023-01-08

接入点

POST /api/buy-coin/transaction

参数

参数	必填	类型	描述
buyCoinMode	✅	Enum	代表买币模式。 买币模式介绍
mtcAmount		Number	当基于**MTC金额**的买币模式时，必填。代表本次交易中购买的 MTC 数量。
totalPrice		Number	当基于**支付价格**的买币模式时，必填。代表交易所需要支付的法定货币数量。
externalOrderNumber	✅	String	商户系统订单号，用于交易完成回调通知。 关于回调
callbackUrl	✅	String	商户系统回调地址，用于交易完成时回调通知。 关于回调
supportLanguage	✅	Enum	付款结账页面的默认语言。 支持语言
currencyCode	✅	String	用户需要支付的法币类型。 货币代码
payerRealName	✅	String	付款人的真实姓名。

买币模式

MtcAmount - MTC 数量模式

在此模式下，交易将根据 MTC 数量进行。此时，您需要传入mtcAmount字段，系统将根据购买的 MTC 数量计算最佳广告并生成订单。

例如： 客户想通过人民币存入 5,000 USD。此时可以使用此模式，传入的 mtcAmount 为 5000.00，货币类型设置为 CNY。 如果系统匹配的广告单价为 7.2 CNY/MTC，客户需要支付 36,000 CNY，商家的钱包也将收到 5,000 MTC 的交易金额（根据手续费配置可能有所变化）。

PaymentPrice - 支付金额模式

在此模式下，交易将根据传入付款的总金额进行计算。此时，您需要传入 totalPrice 字段，系统将根据客户需要支付的法定货币金额自动计算相应的 MTC 数量并结算账户。

例如： 客户希望存入 32,551.20 CNY。此时可以使用此模式，传入的 totalPrice 为 32551.20 人民币，货币类型设置为 CNY。 如果系统匹配的单价为 7.2 CNY/MTC，客户实际上需要支付 32,551.20 CNY，而此次交易的 MTC 数量为 4,521.00。

支持的语言

可用的枚举值:

• en: English
• zh_CN: 中文（简体）
• zh_TW: 中文（繁體）

货币代码

可用的枚举值:

• CNY: Chinese Yuan
• HKD: Hong Kong Dollar
• TWD: New Taiwan Dollar

响应

参数	类型	描述
redirectUrl	String	付款结账链接。客户可以通过此链接在电脑或手机上完成支付。
advertisementCode	String	匹配的广告代码。并非唯一的交易代码。
currentTimestamp	Number	当前响应的 UTC 时间戳，精确到毫秒。

成功回调

参数

当客户成功完成支付操作并且系统确认货币已成功放币时，表示交易已结束。此时，系统将向商家在创建订单时设置的 callbackUrl 发起回调通知，通知商家系统 externalOrderNumber 的交易已成功完成。

回调请求将以 POST 方式完成，请求以 JSON 编码（Content-Type 为 application/json）。

参数	类型	描述
signature	String	身份验证签名，与身份验证请求的算法一致。为了确保请求的安全性并防止伪造请求，如果签名不一致，请中断后续处理过程。
timestamp	Number	身份验证时间戳，UTC 毫秒级时间戳。为了防止重放攻击，请确保处理部分时间段的请求。
data	Object
data.externalOrderNumber	String	商家系统订单号。
data.transactionCode	String	此交易代码。
data.transactionAmount	Number	此交易中的 MTC 数量。
data.currencyCode	String	此交易的法定货币。
data.paymentPrice	Number	此交易的支付金额。
data.transactionCreateTime	String	交易创建时间。
data.paymentFinishedTime	String	交易完成时间。

回调请求的请求体示例：

{
  "signature": "SIGNATURE_HERE",
  "timestamp": 0,
  "data": {
    "externalOrderNumber": "ORDER_CODE",
    "transactionCode": "ATSA6E40D5FE7UZHE",
    "transactionAmount": 200.00,
    "currencyCode": "CNY",
    "paymentPrice": 1000.00,
    "transactionCreateTime": "2021-07-01T00:00:00",
    "paymentFinishedTime": "2021-07-01T00:05:00"
  }
}

响应

如果商家的回调请求成功处理，应返回以下其中一种响应：

• 字符串类型

success

• JSON 类型

{
  "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