Skip to content

Merchant Withdraw Bankcard API

Revision & Version

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

Endpoint

Request Parameters

Parameter Type Required Description
client Client Yes Client information
withdrawCurrency Currency Yes Currency type for the withdrawal (e.g. MTC/CNY/HKD)
fiatCurrency CurrencyCode Yes Fiat currency code (e.g. CNY/HKD)
withdrawAmount BigDecimal Yes Amount to withdraw
bankCard BankCard Yes Bank card details for receiving funds
requiresReview Boolean Yes Indicates whether this withdrawal requires manual review
merchantOrderNo String (max 100) Yes Unique merchant order number
webhookUrl String (max 200) Yes Webhook URL for notifications (See More)

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

BankCard Fields

Parameter Type Description
cardNumber String Bank card number of the client
bankName String Name of the client's bank
bankBranchName String Branch name of the client's bank

Language Enum Values

Value Frontend Language
en en-US
zh_CN Simplified Chinese
zh_TW Traditional Chinese

About Currency Mode

MTC - MTC Amount Mode

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

In this mode, the transaction is based on the specified MTC amount. The system will calculate the optimal advertisement based on the withdrawal 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 withdraw USD 5,000 in CNY, set withdrawAmount to 5000 and fiatCurrency to CNY.

If the system matches an ad with an exchange rate of 7.1 CNY/MTC, the client will receive 35,500 CNY. Meanwhile, the merchant wallet will be debited 5000 MTC (final amount may vary depending on 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 to calculate the client’s payment amount.

In this mode, the transaction is settled based on the given total fiat amount. The system will automatically calculate the corresponding MTC amount based on the fiat amount the client wishes to receive.

Example: If the client needs to receive 32,551.20 CNY, set withdrawAmount to 32,551.20 and fiatCurrency to CNY.

If the system matches an ad with an exchange rate of 7.1 CNY/MTC, the client will receive exactly 32,551.20 CNY. The corresponding MTC amount for this transaction will be 4584.68 MTC.

Response Parameters

APIMerchantWithdrawResponse Fields

Parameter Type Description
requestCode String Request tracking order
createdAt Long Creation timestamp in millisecond

Request Example

curl -X POST https://{YOUR_ENDPOINT}/api/v2/merchant/withdraw/bank-card \
  -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
    },
    "withdrawCurrency": "CNY",
    "fiatCurrency": "CNY",
    "withdrawAmount": 34500.00,
    "bankCard": {
      "cardNumber": "0000000000000000",
      "bankName": "BANK_NAME",
      "bankBranchName": "BANK_BRANCH_NAME"
    },
    "requiresReview": true,
    "merchantOrderNo": "{MERCHANT_ORDER_ID}",
    "webhookUrl": "{MERCHANT_WEBHOOK_URL}"
  }'

Response Example

{
  "data": {
    "requestCode": "d40f0d9a83a248c38d5621dce10810aa",
    "createdAt": 1742143702916
  },
  "isSuccess": true,
  "statusCode": "SUCCESS",
  "message": "",
  "version": "2.0"
}