卡管理模块

支持的卡bin-v2

POST /merchant/core/mcb/card/v2/cardTypes

请求

参数	类型	是否必传	备注

响应

参数	类型	是否必传	描述
cardTypeId	Long	是	卡片类型ID
organization	String	是	卡组织。 Visa； MasterCard； Discover
country	String	是	发卡地区
bankCardBin	String	是	卡BIN
type	String	是	卡类型。 Virtual：虚拟卡 Physical：实体卡
typeStr	String	是	卡类型描述
cardName	String	是	卡名称
cardDesc	String	是	卡片描述
cardPrice	Bigdecimal	是	卡片价格
cardPriceCurrency	String	是	卡片价格币种
support	List	是	支持的机构。仅供参考
supportHolderRegin	List	是	持卡人信息支持的国家/地区编码
supportHolderAreaCode	List	是	持卡人信息支持的手机区号
needCardHolder	Boolean	是	开卡时是否需要持卡人
needDepositForActiveCard	Boolean	是	开卡时是否需要进行充值
depositAmountMinQuotaForActiveCard	BigDecimal	是	开卡时充值最低额度
depositAmountMaxQuotaForActiveCard	BigDecimal	是	开卡时充值最大额度
fiatCurrency	String	是	卡本位币种
maxCount	Interger	是	最大购卡数量。暂时无用
status	String	是	状态。 online:上架; offline:下架
rechargeCurrency	String	是	支持充值的币种
rechargeMinQuota	BigDecimal	是	充值最小额度
rechargeMaxQuota	BigDecimal	是	充值最大额度
rechargeFeeRate	BigDecimal	是	充值手续费率 1=1%
rechargeFixedFee	BigDecimal	是	充值固定手续费
rechargeDigital	Integer	是	充值金额精度
enableActiveCard	Boolean	是	是否开启开卡功能
enableDeposit	Boolean	是	是否开启充值功能
enableFreeze	Boolean	是	是否开启冻结功能
enableUnFreeze	Boolean	是	是否开启解冻功能

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    [
        {
            "cardTypeId": 111002,
            "organization": "Visa",
            "country": "US",
            "bankCardBin": "4866",
            "type": "Virtual",
            "typeStr": "虚拟卡",
            "cardName": "4866**",
            "cardDesc": "Adobe,Aliexpress,Amazon.（暂不支持PayPal, Grab, ONLYFANS, Patreon, Etsy商户消费，否则会立刻销卡并冻结；需要Apple服务可选择5319卡片；）",
            "cardPrice": "10",
            "cardPriceCurrency": "USD",
            "support":
            [
                "Adobe",
                "Aliexpress"
            ],
            "supportHolderRegin":
            [
                "US"
            ],
            "supportHolderAreaCode":
            [
                "+60",
                "+1"
            ],
            "needCardHolder": false,
            "needDepositForActiveCard": true,
            "depositAmountMinQuotaForActiveCard": 10,
            "depositAmountMaxQuotaForActiveCard": 100000,
            "fiatCurrency": "USD",
            "maxCount": 100,
            "status": "online",
            "rechargeCurrency": "USD",
            "rechargeMinQuota": 20,
            "rechargeMaxQuota": 100000,
            "rechargeFeeRate": 1,
            "rechargeFixedFee": 0,
            "rechargeDigital": 2,
            "enableActiveCard": true,
            "enableDeposit": true,
            "enableFreeze": true,
            "enableUnFreeze": true
        }
    ]
}

开卡

当开卡成功后（status=success）才会返回cardNo。在此之前可以等待开卡webhook或者主动调用 卡交易查询 接口查询开卡进度

POST /merchant/core/mcb/card/openCard

请求

参数	类型	是否必传	备注
merchantOrderNo	String	是	商户订单号。[20...]位
holderId	Long	否	持卡人id
cardTypeId	Long	是	卡片类型id
amount	BigDecimal	否	开卡时充值金额。不传默认最低额度（如果卡BIN需要首冲）值范围：/merchant/core/mcb/card/cardTypes接口depositAmountMinQuotaForActiveCard <= amount <= depositAmountMaxQuotaForActiveCard

响应

参数	类型	是否必传	备注
orderNo	String	是	平台订单号。
merchantOrderNo	String	是	商户订单号
cardNo	String	否	银行卡id
currency	String	是	币种
amount	BigDecimal	是	金额
fee	BigDecimal	是	手续费
receivedAmount	BigDecimal	是	到账金额
receivedCurrency	String	是	到账币种
type	String	是	类型。 create：开卡；
status	String	是	状态。 wait_process：待处理； processing：处理中； success：成功； fail：失败
remark	String	否	交易备注
transactionTime	Long	是	交易时间。毫秒时间戳

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    [
        {
            "orderNo": "1852379830190366720",
            "merchantOrderNo": "T1852379826671345664",
            "cardNo": null,
            "currency": "USD",
            "amount": "15",
            "fee": "0",
            "receivedAmount": "0",
            "receivedCurrency": "USD",
            "type": "create",
            "status": "processing",
            "remark": null,
            "transactionTime": 1730476741729
        }
    ]
}

卡信息

POST /merchant/core/mcb/card/info

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
onlySimpleInfo	Boolean	否	是否只返回卡片的基本信息。不包含余额。默认true

响应

参数	类型	是否必传	备注
holderId	Long	否	持卡人id
cardNo	String	是	银行卡id
cardNumber	String	是	银行卡号
cvv	String	是	cvv。商户公钥加密返回，使用商户私钥解密
validPeriod	String	是	有效期。商户公钥加密返回，使用商户私钥解密
status	String	是	状态。 Normal：正常； Freeze：冻结； Freezing：冻结审核中； UnFreezing：解冻审核中； canceling：注销中； cancel：已注销；
statusStr	String	是	状态描述
bindTime	Long	是	开卡时间。毫秒时间戳
remark	String	否	备注
balanceInfo	Object	否	卡余额信息
balanceInfo.cardNo	String	是	银行卡id
balanceInfo.amount	BigDecimal	是	卡余额
balanceInfo.usedAmount	BigDecimal	否	已用金额。有些卡bin不支持
balanceInfo.currency	String	是	币种

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "holderId": 10090,
        "cardNo": "FC202408181555232422322004",
        "cardNumber": "202404000000000083",
        "cvv": "bQoXms9ScNxy37b1JgyP1tJuFiAcGl6d+7jqn7LTZRzQMXjn00zaa/xKJp/8sotkcBjl/L/6LSImxhnF+yg6V3aDft+v1ikkYBdY9Wco042o/uPyUNtr0xW786ENyB8Z84teK3vWtLeU/TbixEygxrxl/ilE+COmJOItWCGE6bs=",
        "validPeriod": "gQldrvKSV3cWXuCbrUgtVF5EsCgxEAZQuivEuddeoo5M+5bF0AiJJbw8PWvvZZerRmcOmv/0dRv8uyeaSbUmCyQrDn6cploG60lCxGfnzSopv5pEO4UrK071tNzIa++mZ4IZ4tvtlMYlwo+y3d9JhIareLM21E1mH7aPn+WOk50=",
        "status": "cancel",
        "statusStr": "Canceled",
        "bindTime": 1723997214000,
        "remark": null,
        "balanceInfo":
        {
            "cardNo": "FC202408181555232422322004",
            "amount": "10",
            "usedAmount": "1",
            "currency": "USD"
        }
    }
}

卡余额

POST /merchant/core/mcb/card/balanceInfo

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡id

响应

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
amount	BigDecimal	是	卡余额
usedAmount	BigDecimal	否	已用金额。有些卡bin不支持
currency	String	是	币种

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "cardNo": "FC202408181555232422322004",
        "amount": "10",
        "usedAmount": "1",
        "currency": "USD"
    }
}

冻结

POST /merchant/core/mcb/card/freeze

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
merchantOrderNo	String	否	商户订单号。

响应

参数	类型	是否必传	备注
status	String	是	状态。 processing：处理中； success：成功； fail：失败；
statusStr	String	是	状态描述

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "status": "success",
        "statusStr": "成功"
    }
}

冻结-v2

POST /merchant/core/mcb/card/v2/freeze

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
merchantOrderNo	String	是	商户订单号。[20...40]字符
clientRemark	String	否	备注。[0...50]字符

响应

参数	类型	是否必传	备注
orderNo	String	是	平台订单号
merchantOrderNo	String	是	商户订单号
cardNo	String	是	银行卡id
currency	String	是	币种
amount	BigDecimal	是	金额
fee	BigDecimal	是	手续费
receivedAmount	BigDecimal	否	到账金额。status=success返回
receivedCurrency	String	否	到账币种。status=success返回
type	String	是	类型。Freeze: 冻结;
status	String	是	状态。 wait_process: 待处理; processing: 处理中; success: 成功; fail: 失败
remark	String	否	交易备注
transactionTime	Long	是	交易时间。毫秒时间戳

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "orderNo": "1852379830190366720",
        "merchantOrderNo": "T1852379826671345664",
        "cardNo": "38928421021320391244",
        "currency": "USD",
        "amount": "0",
        "fee": "0",
        "receivedAmount": "0",
        "receivedCurrency": "USD",
        "type": "Freeze",
        "status": "processing",
        "remark": "Freeze",
        "transactionTime": 1730476742000
    }
}

解冻

POST /merchant/core/mcb/card/unfreeze

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡id

响应

参数	类型	是否必传	备注
status	String	是	状态。 processing：处理中； success：成功； fail：失败；
statusStr	String	是	状态描述

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "status": "success",
        "statusStr": "成功"
    }
}

解冻-v2

POST /merchant/core/mcb/card/v2/unfreeze

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡ID
merchantOrderNo	String	是	商户订单号。[20...40]字符
clientRemark	String	否	备注。[0...50]字符

响应

参数	类型	是否必传	备注
orderNo	String	是	平台订单号
merchantOrderNo	String	是	商户订单号
cardNo	String	是	银行卡id
currency	String	是	币种
amount	BigDecimal	是	金额
fee	BigDecimal	是	手续费
receivedAmount	BigDecimal	否	到账金额。status=success返回
receivedCurrency	String	否	到账币种。status=success返回
type	String	是	类型。UnFreeze: 解冻;
status	String	是	状态。 wait_process: 待处理; processing: 处理中; success: 成功; fail: 失败
remark	String	否	交易备注
transactionTime	Long	是	交易时间。毫秒时间戳

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "orderNo": "1852379830190366720",
        "merchantOrderNo": "T1852379826671345664",
        "cardNo": "38928421021320391244",
        "currency": "USD",
        "amount": "0",
        "fee": "0",
        "receivedAmount": "0",
        "receivedCurrency": "USD",
        "type": "UnFreeze",
        "status": "processing",
        "remark": "UnFreeze",
        "transactionTime": 1730476742000
    }
}

充值

POST /merchant/core/mcb/card/deposit

请求

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
merchantOrderNo	String	是	商户订单号。[20...35]位
amount	BigDecimal	是	充值金额

响应

参数	类型	是否必传	备注
orderNo	String	是	平台订单号
merchantOrderNo	String	是	商户订单号
cardNo	String	是	银行卡id
currency	String	是	币种
amount	BigDecimal	是	充值金额
fee	BigDecimal	是	手续费
receivedAmount	BigDecimal	否	到账金额。status=success返回
receivedCurrency	String	否	到账币种。status=success返回
type	String	是	类型。deposit: 充值;
status	String	是	状态。 wait_process: 待处理; processing: 处理中; success: 成功; fail: 失败
remark	String	否	交易备注
transactionTime	Long	是	交易时间。毫秒时间戳

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "orderNo": "1852379830190366720",
        "merchantOrderNo": "T1852379826671345664",
        "cardNo": "38928421021320391244",
        "currency": "USD",
        "amount": "15",
        "fee": "0",
        "receivedAmount": "0",
        "receivedCurrency": "USD",
        "type": "deposit",
        "status": "processing",
        "remark": "Card Deposit",
        "transactionTime": 1730476742000
    }
}

卡交易记录查询

POST /merchant/core/mcb/card/transaction

请求

参数	类型	是否必传	备注
pageNum	Integer	是	当前页。默认1
pageSize	Integer	是	每页数量。默认10，最大100
type	String	是	类型。 create：开卡； deposit：充值； cancel：销卡； Freeze：冻结； UnFreeze：解冻
merchantOrderNo	String	否	商户订单号
orderNo	String	否	平台订单号
cardNo	String	否	银行卡id
startTime	Long	否	开始交易时间。毫秒时间戳
endTime	Long	否	结束交易时间。毫秒时间戳

响应

参数	类型	是否必传	备注
orderNo	String	是	平台订单号
merchantOrderNo	String	否	商户订单号
cardNo	String	否	银行卡id
currency	String	是	币种
amount	BigDecimal	是	金额
fee	BigDecimal	是	手续费
receivedAmount	BigDecimal	否	到账金额
receivedCurrency	String	否	到账币种
type	String	是	类型。 create：开卡； deposit：充值； cancel：销卡； Freeze：冻结； UnFreeze：解冻
status	String	是	状态。 wait_process：待处理； processing：处理中； success：成功； fail：失败
remark	String	否	交易备注
transactionTime	Long	是	交易时间。毫秒时间戳

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "total": 1,
        "records":
        [
            {
                "orderNo": "1852379830190366720",
                "merchantOrderNo": "T1852379826671345664",
                "cardNo": null,
                "currency": "USD",
                "amount": "15",
                "fee": "0",
                "receivedAmount": "0",
                "receivedCurrency": "USD",
                "type": "create",
                "status": "processing",
                "remark": null,
                "transactionTime": 1730476742000
            }
        ]
    }
}

卡授权交易记录查询

POST /merchant/core/mcb/card/authTransaction

请求

参数	类型	是否必传	备注
pageNum	Integer	是	当前页。默认1
pageSize	Integer	是	每页数量。默认10，最大100
type	String	否	类型。 auth: 预授权; correct_auth: 预授权冲正; correct_refund: 退款冲正; refund: 退款; verification: 验证; Void: 撤销;
tradeNo	String	否	交易流水号
cardNo	String	否	银行卡id
startTime	Long	否	开始交易时间。毫秒时间戳
endTime	Long	否	结束交易时间。毫秒时间戳

响应

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
tradeNo	String	是	交易流水号
originTradeNo	String	否	原交易流水号
currency	String	否	交易币种
amount	BigDecimal	否	交易金额
authorizedAmount	BigDecimal	是	授权金额
authorizedCurrency	String	是	授权币种
fee	BigDecimal	是	授权手续费
feeCurrency	String	否	授权手续费币种
crossBoardFee	BigDecimal	是	跨境交易手续费
crossBoardFeeCurrency	String	否	跨境交易手续费币种
settleAmount	BigDecimal	否	结算金额。收到结算信息后推送
settleCurrency	String	否	结算币种。收到结算信息后推送
settleDate	Long	否	结算日期。毫秒时间戳
merchantName	String	是	商户名称
type	String	是	类型。 auth: 授权; correct_auth: 授权冲正; correct_refund: 退款冲正; refund: 退款; verification: 验证; Void: 撤销;
typeStr	String	是	交易类型描述
status	String	是	状态。 authorized：已授权； revoked：已撤销 failed：失败； succeed：成功；
statusStr	String	是	状态描述
description	String	是	交易描述
transactionTime	Long	是	交易时间。毫秒时间戳

响应示例

{
    "success": true,
    "code": 200,
    "msg": "Success",
    "data":
    {
        "total": 1563,
        "records":
        [
            {
                "cardNo": "1242352328671924231",
                "tradeNo": "trans1232435363435463432",
                "originTradeNo": null,
                "currency": "CNY",
                "amount": "16.96",
                "authorizedAmount": "2.45",
                "authorizedCurrency": "USD",
                "fee": "0.5",
                "feeCurrency": "USD",
                "crossBoardFee": "0",
                "crossBoardFeeCurrency": null,
                "settleAmount": 0,
                "settleCurrency": null,
                "settleDate": null,
                "merchantName": "ALP*Mr Rice 1223",
                "type": "auth",
                "typeStr": "授权",
                "status": "authorized",
                "statusStr": "已授权",
                "transactionTime": 1729422898000,
                "description": "Auth"
            }
        ]
    }
}

卡3ds记录查询

POST /merchant/core/mcb/card/third3dsTransaction

请求

参数	类型	是否必传	备注
pageNum	Integer	是	当前页。默认1
pageSize	Integer	是	每页数量。默认10，最大100
type	String	否	类型。 third_3ds_otp：3ds验证码； auth_url：交易授权响应url；
tradeNo	String	否	交易流水号
cardNo	String	否	银行卡id
startTime	Long	否	开始交易时间。毫秒时间戳
endTime	Long	否	结束交易时间。毫秒时间戳

响应

参数	类型	是否必传	备注
cardNo	String	是	银行卡id
tradeNo	String	是	交易流水号
originTradeNo	String	否	原交易流水号
currency	String	是	交易币种
amount	BigDecimal	是	交易金额
merchantName	String	是	商户名称（交易场景）
values	String	是	值。商户公钥加密返回，使用商户私钥解密
type	String	是	类型。 third_3ds_otp：3ds验证码； auth_url：交易授权响应url；
description	String	否	描述
transactionTime	Long	是	交易时间。毫秒时间戳
expirationTime	Long	否	过期时间。毫秒时间

响应示例

3ds验证码

{
    "cardNo": "1242352328671924231",
    "tradeNo": "trans1232435363435463432",
    "originTradeNo": null,
    "currency": "CNY",
    "amount": "16.96",
    "merchantName": "ULTRA MOBILE",
    "values": "ajfon34nNOIN24nafaiw4onnfn0iw32ngfn0IF0Q34NFQFOFAW", //明文示例：208346
    "type": "third_3ds_otp",
    "description": null,
    "transactionTime": 1729422898000
}

交易授权响应url

{
    "cardNo": "1242352328671924231",
    "tradeNo": "trans1232435363435463432",
    "originTradeNo": null,
    "currency": "CNY",
    "amount": "16.96",
    "merchantName": "ULTRA MOBILE",
    "values": "ajfon34nNOIN24nafaiw4onnfn0iw32ngfn0IF0Q34NFQFOFAW", //明文示例:https://www.google.com
    "type": "auth_url",
    "description": null,
    "transactionTime": 1729422898000,
    "expirationTime": 1729422899000
}