Skip to content

Buy MTC (Client's Deposit) API documents

Revision: v1.0.1.0

Revision time: 2023-01-08

Endpoint

POST /api/buy-coin/transaction

Parameters

Parameter Required Type Descriptions
buyCoinMode ✅ Enum The line items representing buy coin mode.
Buy coin mode introduction
mtcAmount Number When the Buy Coin Mode based on MTC Amount, its required. The items representing the amount of MTC purchased in this transaction.
totalPrice Number When the Buy Coin Mode based on Payment Price, its required. The items representing the amount of fiat currency that the exchange needs to pay.
externalOrderNumber ✅ String The order number of the merchant system, used for callback notification when the transaction is completed.
About callback
callbackUrl ✅ String The callback address of the merchant system, used to call back notifications when the transaction is completed.
About callback
supportLanguage ✅ Enum The default language for payment checkout pages.
Support language
currencyCode ✅ String The type of legal currency that the user needs to pay.
Currency code
payerRealName ✅ String The payer’s real name.

Buy coin mode

MtcAmount - Mtc Amount Mode

In this mode, transactions will be conducted based on the MTC quantity. At this time, you need to pass in the mtcAmount field, and the system will compute the optimal advertisement and generate an order based on the purchased MTC quantity.

For example: The client wants to deposit 5,000 USD via CNY. At this time, this mode can be used, the incoming mtcAmount is 5,000, and the currency type is set to CNY. If the advertising unit price matched by the system is 7.2 CNY/MTC, the client actually needs to pay 36,000 CNY, and the merchant's wallet will also receive a transaction amount of 5,000 USD (which may vary depending on the handling fee configuration).

PaymentPrice - Payment Price Mode

In this mode, transactions will be calculated based on the total amount of the incoming payment. At this time, you need to pass in the totalPrice field, and the system will automatically calculate the corresponding MTC amount and settle the account based on the amount of legal currency that the client needs to pay.

For example: The client wishes to deposit 32,551.20 CNY. This mode can be used at this time, the incoming totalPrice is 32,551.20 CNY, and the currency type is set to CNY. If the unit price matched by the system is 7.2 CNY/MTC, the client actually needs to pay 32,551.20 CNY, and the MTC amount for this transaction is 4,521.00 MTC.

Support language

Possible enum values:

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

Currency code

Possible enum values:

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

Response

Parameter Type Descriptions
redirectUrl String The payment checkout link. Clients can complete payment on the PC or Mobile through this link.
advertisementCode String Matching AD codes. Not the only transaction code.
currentTimestamp Number UTC timestamp of the current response, with millisecond precision.

Success callback

Parameters

When the client successfully completes the payment action and the system has confirmed that the currency has been released successfully, it means that the transaction has ended. At this time, the system will initiate a callback notification to the callbackUrl set when the merchant creates the order, informing the merchant system that the transaction of externalOrderNumber has been successfully completed.

The callback request will be completed in POST mode, and the request is JSON encoding (Content-Type is application/json).

Parameter Type Descriptions
signature String Authentication signature, consistent with the algorithm of the authentication request. In order to ensure the security of the request and prevent forged requests, if the signature is inconsistent, please interrupt the subsequent processing process.
timestamp Number Authentication timestamp, UTC millisecond level timestamp. To prevent replay attacks, make sure to handle requests for part of the time period.
data Object
data.externalOrderNumber String Merchant system order number.
data.transactionCode String This transaction code.
data.transactionAmount Number The amount of MTC in this transaction.
data.currencyCode String The legal currency of this transaction.
data.paymentPrice Number The payment amount for this transaction.
data.transactionCreateTime String Transaction creation time.
data.paymentFinishedTime String transaction completion time.

Callback request body example:

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

Response

If the merchant's callback request is successfully processed, one of the following responses should be returned:

  • String Type 
    success
  • JSON Type 
    {
  "success": true
}

If anything else is returned, it will be considered a processing failure and the automatic retry logic will be triggered. If all retries fail, the callback will be marked as "Callback Failed".

Retry interval

  • 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