商户存款 API¶

修订与版本¶

版本：1.0
最后更新：2025-03-14

接口¶

URL：/api/v2/merchant/deposit
请求方式：POST
认证方式：必需（参见全局认证指南）

请求参数¶

参数	类型	必填	描述
client	Client	是	客户信息
depositCurrency	Currency	是	存款的货币类型（例如 MTC/CNY/HKD）
fiatCurrency	`CurrencyCode`	是	法定货币代码（例如 CNY/HKD）
depositAmount	`BigDecimal`	是	存款金额
merchantOrderNo	`String` (最大 100 字符)	是	唯一的商户订单号
webhookUrl	`String` (最大 200 字符)	是	通知的 Webhook URL (查看更多)
language	`Language`	否	首选语言（默认为 `en`）
paymentMethod	`PaymentMethod?`	否	支付方式（可选）

`Client` 字段¶

参数	类型	描述
realName	`String`	客户的真实姓名
registeredAt	`Long`	注册时间的毫秒时间戳（可选）

`Currency` 枚举值¶

值	描述
MTC	MTC 货币
CNY	人民币
HKD	港元

`Language` 枚举值¶

值	前端语言
en	英文
zh_CN	简体中文
zh_TW	繁体中文

`PaymentMethod` 字段¶

参数	类型	描述
method	`Long`	该字段是一个位枚举：银行卡 → 1 微信支付 → 2 支付宝 → 4 区块链 → 8（即将推出）账户 → 16（即将推出）每个值表示一种支付方式，可以通过位运算组合多个值。

`关于货币模式`¶

`MTC` - MTC 金额模式¶

注意：如果您不希望引用 MTPay 系统的默认汇率，请使用此模式。

在此模式下，交易基于指定的 MTC 金额。系统将根据存款金额（以 MTC 为单位）计算最优广告，并生成订单。在此情况下，MTC 被视为等同于美元稳定币。

示例：如果客户希望使用人民币存入 5,000 美元，则将 depositAmount 设置为 5000，fiatCurrency 设置为 CNY。

如果系统匹配到一个汇率为 7.2 CNY/MTC 的广告，客户需要支付 36,000 CNY。同时，商户的钱包将接收到 5000 MTC 作为交易金额（最终到账金额可能根据费用配置有所不同）。

`CNY` 或 `HKD` - 支付价格模式¶

注意：如果您希望应用商户系统指定的汇率并直接计算客户的支付金额，请使用此模式。

在此模式下，交易基于客户将支付的法定货币总金额进行结算。系统将根据指定的法定货币金额自动计算相应的 MTC 金额。

示例：如果客户需要支付 32,551.20 CNY，则将 depositAmount 设置为 32,551.20，fiatCurrency 设置为 CNY。

如果系统匹配到一个汇率为 7.2 CNY/MTC 的广告，客户将支付 32,551.20 CNY，且交易对应的 MTC 金额为 4521.00 MTC。

响应参数¶

`APIMerchantDepositResponse` 字段¶

参数	类型	描述
checkoutUrl	`String`	完成存款的 URL
requestCode	`String`	请求编号
isAvailable	`Boolean`	存款是否可用
expiresAt	`Long`	到期时间戳（毫秒）
createdAt	`Long`	创建时间戳（毫秒）

请求示例¶

curl -X POST https://{YOUR_ENDPOINT}/api/v2/merchant/deposit \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "access_key: {YOUR_ACCESS_KEY}" \
  -H "signature: {GENERATED_BY_Hmac256}" \
  -H "timestamp: {TIMESTAMP_IN_MILLISECONDS}" \
  -d '{
    "client": {
      "realName": "USER_REAL_NAME",
      "registeredAt": 1700140636000
    },
    "depositCurrency": "CNY",
    "fiatCurrency": "CNY",
    "depositAmount": 5500.20,
    "merchantOrderNo": "{MERCHANT_ORDER_ID}",
    "webhookUrl": "{MERCHANT_WEBHOOK_URL}",
    "language": "zh_CN",
    "paymentMethod": {
      "method": 7
    }
  }'

响应示例¶

{
  "data": {
    "checkoutUrl": "https://{HOST}/api/buy-coin/bbf70d22e14049dcaa973e63a1f57e4e?lang=zh-CN",
    "requestCode": "bbf70d22e14049dcaa973e63a1f57e4e",
    "isAvailable": true,
    "expiresAt": 1742148645751,
    "createdAt": 1742141445751
  },
  "isSuccess": true,
  "statusCode": "SUCCESS",
  "message": "",
  "version": "2.0"
}

商户存款 API¶

修订与版本¶

接口¶

请求参数¶

Client 字段¶

Currency 枚举值¶

Language 枚举值¶

PaymentMethod 字段¶

关于货币模式¶

MTC - MTC 金额模式¶

CNY 或 HKD - 支付价格模式¶