用户开卡
POST/openapi/v2/cards/issueCard| 项 | 内容 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /openapi/v2/cards/issueCard |
| 请求类型 | application/json |
请求参数:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestNo | string | 是 | 调用方业务幂等号,1 到 64 位可见 ASCII 字符,不能包含空格。 |
email | string | 是 | 用户邮箱。 |
memberId | string | 否 | 已废弃的兼容字段;如传入,仅用于与邮箱交叉校验。 |
cardTypeId | string | 是 | 卡类型 ID,最大 64 位。 |
embossedName | string | 否 | 卡面姓名;是否必填及长度由卡产品配置决定。 |
cardSuffix | string | 否 | 指定卡号尾号;是否支持由卡产品配置决定。 |
mobile | string | 否 | 预留手机号;格式要求由卡产品配置决定。 |
deviceFingerprintId | string | 条件 | 设备指纹,最大 128 位;万事达全球美元卡至少提供设备指纹或完整的公网 IP+国家/地区码。 |
deviceIpAddress | string | 条件 | 真实设备公网 IP,最大 64 位;万事达全球美元卡如传入,须同时提供 deviceCountryCode。 |
deviceCountryCode | string | 条件 | 设备 IP 所在国家/地区的两位字母代码,例如 HK,不是用户国籍;万事达全球美元卡如传入,须同时提供 deviceIpAddress。 |
设备信息要求
以 cardTypeId 对应的卡产品为准:
| 卡产品 | 设备信息要求 |
|---|---|
| 万事达香港美元卡 | 非必填。 |
| 万事达全球美元卡 | 至少提供非空 deviceFingerprintId,或同时提供非空 deviceIpAddress 和 deviceCountryCode。 |
万事达全球美元卡允许同时提供两种设备信息。但即使已提供设备指纹,公网 IP 和国家/地区码也不能只传其中一个。设备信息由调用方提供,接口不会自动从请求来源补充。
请求示例
以下为万事达全球美元卡的两种设备信息提交方式。
设备指纹
json
{
"requestNo": "ISSUE_20261010_001",
"email": "user@example.com",
"cardTypeId": "VIRTUAL_USD",
"deviceFingerprintId": "DEVICE_FINGERPRINT_001"
}公网 IP 和国家/地区码
json
{
"requestNo": "ISSUE_20261010_002",
"email": "user@example.com",
"cardTypeId": "VIRTUAL_USD",
"deviceIpAddress": "203.0.113.10",
"deviceCountryCode": "HK"
}cardTypeId 和设备信息均为示例占位值,需替换为实际卡产品 ID 和真实设备信息;示例 IP 不可用于实际开卡。国家/地区码应与实际设备 IP 所在地区一致。
响应 data:
| 字段 | 类型 | 说明 |
|---|---|---|
cardOrderNo | string | 平台开卡订单号。 |
requestNo | string | 调用方业务幂等号。 |
email | string | 用户邮箱。 |
memberId | string | 平台成员 ID。 |
cardTypeId | string | 卡类型 ID。 |
currency | string | 卡产品币种,通常为 ISO 4217 三位代码;由产品配置决定。 |
type | string | 卡类型,当前已知值为 PHYSICAL、VIRTUAL,产品配置可能扩展。 |
feeAmount | string | 开卡手续费金额,非科学计数法字符串。 |
feeAssetCode | string | 开卡手续费资产。 |
accepted | boolean | 是否已受理。 |
status | string | 平台开卡状态,取值 PROCESSING、SUCCESS、FAILED。 |
failCode | string | 失败码。 |
failMessage | string | 失败说明。 |
last4 | string | 卡号后四位。 |
expiryMonth | string | 过期月份。 |
expiryYear | string | 过期年份。 |
createTime | string | 订单创建时间。 |
completedTime | string | 订单终态时间。 |
