跳转至

商户银行卡提现 API

修订与版本

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

接口

请求参数

参数 类型 是否必填 描述
client Client 是 客户信息
withdrawCurrency Currency 是 提现货币类型（如 MTC/CNY/HKD）
fiatCurrency CurrencyCode 是 法币货币代码（如 CNY/HKD）
withdrawAmount BigDecimal 是 提现金额
bankCard BankCard 是 客户用于接收资金的银行卡信息
requiresReview Boolean 是 此笔提现是否需要人工审核
merchantOrderNo String (最大 100 字符) 是 商户唯一订单号
webhookUrl String (最大 200 字符) 是 通知用的 Webhook 地址（了解更多）

Client 字段说明

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

Currency 枚举值

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

BankCard 字段说明

参数 类型 描述
cardNumber String 客户银行卡号
bankName String 客户银行名称
bankBranchName String 客户银行分支机构名称

Language 枚举值

值 前端语言
en 英文 (en-US)
zh_CN 简体中文
zh_TW 繁體中文

关于货币模式

MTC - MTC金额模式

说明：如果您不希望参考MTPay系统的默认汇率，请使用此模式。

在此模式下，交易基于指定的MTC金额进行。系统将根据MTC的提现金额计算最优广告，并生成订单。在此上下文中，MTC被视为等同于美元稳定币。

示例：
如果客户希望以人民币提现5,000美元，则设置 withdrawAmount 为 5000，fiatCurrency 为 CNY。

若系统匹配到的广告汇率为 7.1 CNY/MTC，客户将收到 35,500 CNY。同时，商户钱包将扣除 5000 MTC（实际扣款金额可能因手续费配置而有所不同）。

CNY 或 HKD - 支付价格模式

说明：如果您希望使用商户系统指定的汇率，直接计算客户应收款金额，请使用此模式。

在此模式下，交易基于客户希望收到的法币总金额结算。系统将根据指定的法币金额自动计算相应的MTC数量。

示例：
如果客户需收到 32,551.20 CNY，则设置 withdrawAmount 为 32,551.20，fiatCurrency 为 CNY。

若系统匹配到的广告汇率为 7.1 CNY/MTC，客户将正好收到 32,551.20 CNY。该笔交易对应的MTC金额为 4584.68 MTC。

响应参数

APIMerchantWithdrawResponse 字段

参数 类型 描述
requestCode String 请求追踪订单号
createdAt Long 创建时间戳（毫秒）

请求示例

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

响应示例

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