Skip to content

Merchant Deposit API

Revision & Version

  • Version: 1.0
  • Last Updated: 2025-03-14

Endpoint

Request Parameters

Parameter Type Required Description
client Client Yes Client information
depositCurrency Currency Yes Currency type for the deposit (e.g. MTC/CNY/HKD)
fiatCurrency CurrencyCode Yes Fiat currency code (e.g. CNY/HKD)
depositAmount BigDecimal Yes Amount to Deposit
merchantOrderNo String (max 100) Yes Unique merchant order number
webhookUrl String (max 200) Yes Webhook URL for notifications (See More)
language Language No Preferred language (default: en)
paymentMethod PaymentMethod? No Payment method (optional)

Client Fields

Parameter Type Description
realName String Client's real name
registeredAt Long Registration milliseconds timestamp (optional)

Currency Enum Values

Value Description
MTC MTC currency
CNY Chinese Yuan
HKD Hong Kong Dollar

Language Enum Values

Value Frontend Language
en English
zh_CN Simplified Chinese
zh_TW Traditional Chinese

PaymentMethod Fields

Parameter Type Description
method Long This field is a bitwise enumeration:
BankCard → 1
WeChatPay → 2
Alipay → 4
Blockchain → 8 (Coming soon)
Account → 16 (Coming soon)
Each value represents a payment method and can be combined using bitwise operations.

About Currency Mode

MTC - MTC Amount Mode

Note: Use this mode if you prefer not to reference the MTPay system’s default exchange rate.

In this mode, the transaction is based on the specified MTC amount. The system will calculate the optimal advertisement based on the deposit amount in MTC and generate an order. In this context, MTC is treated as equivalent to a USD stable coin.

Example: If the client wants to deposit USD 5,000 using RMB, set depositAmount to 5000 and fiatCurrency to CNY.

If the system matches an advertisement with an exchange rate of 7.2 CNY/MTC, the client will need to pay 36,000 CNY. At the same time, the merchant’s wallet will receive 5000 MTC as the transaction amount (the final credited amount may vary depending on the fee configuration).

CNY or HKD - Payment Price Mode

Note: Use this mode if you prefer to apply the exchange rate specified by your merchant system and directly calculate the client's payment amount.

In this mode, the transaction is settled based on the total fiat amount the client will pay. The system will automatically calculate the corresponding MTC amount based on the specified fiat amount.

Example: If the client needs to pay 32,551.20 CNY, set depositAmount to 32,551.20 and fiatCurrency to CNY.

If the system matches an advertisement with an exchange rate of 7.2 CNY/MTC, the client will pay exactly 32,551.20 CNY, and the corresponding MTC amount for the transaction will be 4521.00 MTC.

Response Parameters

APIMerchantDepositResponse Fields

Parameter Type Description
checkoutUrl String URL for completing the deposit
requestCode String Request tracking order
isAvailable Boolean Availability of the deposit
expiresAt Long Expiration timestamp in millisecond
createdAt Long Creation timestamp in millisecond

Request Example

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
    }
  }'

Response Example

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