購買 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: 中文 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