# 统一订阅创建
商户业务系统通过统一订阅接口发起订阅，适用于商户自定义收银台或直接集成特定支付方式的场景。
# 接口说明
接口
请求API: /api/subscription/unifiedCreate
请求方式: POST
请求类型：application/json 或 application/x-www-form-urlencoded
# 请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户号 | mchNo | 是 | String(30) | M1621873433953 | 商户号 |
| 应用ID | appId | 是 | String(24) | 60cc09bce4b0f1c0b83761c9 | 应用ID |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号 |
| 订阅计划ID | planId | 否 | String | P_123456 | 订阅计划ID, 与planCode二选一 |
| 订阅计划编码 | planCode | 否 | String | PLAN_VIP_MONTHLY | 订阅计划编码, 与planId二选一 |
| 支付方式代码 | wayCode | 是 | String | KAKAO | 具体的支付方式代码, 如 KAKAO, ALIPAY_HK 等 |
| 国家 | country | 否 | String(2) | KR | 国家二字码 |
| 货币代码 | currency | 是 | String(3) | KRW | 三位货币代码 |
| 客户端IP | clientIp | 是 | String(32) | 210.73.10.148 | 客户端IP地址 |
| 商品标题 | subject | 是 | String(64) | 会员订阅 | 商品标题 |
| 商品描述 | body | 是 | String(256) | 月度会员订阅服务 | 商品描述 |
| 用户Id | mchUserId | 是 | String(256) | user1008 | 商户系统用户ID |
| 用户邮箱 | 否 | String(256) | abc@gmail.com | 用户邮箱 | |
| 跳转通知地址 | returnUrl | 否 | String(128) | https://merchant.com/subReturn | 支付结果同步跳转URL |
| <!-- | 扩展参数 | extParam | 否 | String(1024) | {"role":"vip"} |
| 测试模式 | testMode | 否 | Boolean | false | 是否强制指定测试模式 |
| 请求时间 | reqTime | 是 | long | 1622016572190 | 请求接口时间,13位时间戳 |
| 接口版本 | version | 是 | String(3) | 1.0 | 接口版本号，固定：1.0 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
| 签名类型 | signType | 是 | String(32) | MD5 | 签名类型，目前只支持MD5方式 |
# 请求示例数据
{
"mchOrderNo": "sub1624005107281",
"planCode": "VIP_MONTHLY",
"wayCode": "PAYPAL",
"subject": "月度会员",
"body": "高级会员服务",
"currency": "USD",
"mchUserId": "user_001",
"clientIp": "192.168.1.1",
"notifyUrl": "https://merchant.com/notify",
"returnUrl": "https://merchant.com/return",
"reqTime": "1622016572190",
"version": "1.0",
"signType": "MD5",
"mchNo": "M1623984572",
"appId": "60cc09bce4b0f1c0b83761c9",
"sign": "84F606FA25A6EC4783BECC08D4FDC681"
}
# 返回参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态 | code | 是 | int | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | msg | 否 | String(128) | 签名失败 | 具体错误原因 |
| 签名信息 | sign | 否 | String(32) | CCD9083A6DAD9A2DA9F668C3D4517A84 | 对data内数据签名 |
| 返回数据 | data | 否 | Object | {} | 返回订阅数据 |
# data数据格式 (SubscriptionRS)
| 字段名 | 变量名 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| 订阅ID | subscriptionId | String | SUB_20210618001 | 支付系统订阅ID |
| 商户号 | mchNo | String | M1621873433953 | 商户号 |
| 应用ID | appId | String | 60cc09bce4b0f1c0b83761c9 | 应用ID |
| 币种 | currency | String | USD | 币种 |
| 订阅计划ID | planId | String | PLAN_001 | 订阅计划ID |
| 订阅计划编码 | planCode | String | VIP_MONTH | 订阅计划编码 |
| 订阅周期 | cycleIndex | integer | 1 | 订阅周期值 |
| 商户订单号 | mchOrderNo | String | sub1624005107281 | 商户传入的订单号 |
| 商户用户ID | mchUserId | String | user_001 | 商户用户ID |
| 支付订单ID | payOrderId | String | P202106181642329900002 | 支付订单ID用于退款 |
| 状态 | state | Byte | 0 | 0-待生效, 1-等生效 2-活跃, 3-暂停, 4-逾期 5-已取消, 6-完成, 7-无效 |
| 当前周期开始 | currentPeriodStart | Long | 1624005107281 | 当前计费周期开始时间戳 (可选) |
| 下次扣费时间 | currentPeriodEnd | Long | 1626597107281 | 当前周期结束/下次扣费时间戳 (可选) |
| 到期取消 | cancelAtPeriodEnd | Boolean | false | 是否在周期结束时取消 |
| 是否有效 | isActive | Boolean | false | 根据状态和时间判断当前是否有效 |
| 支付数据类型 | payDataType | String | payurl | payurl-跳转链接的方式 |
| 支付数据 | payData | String | http://pay.enjoy.link/pay.html | 发起支付用到的支付参数 |
| 渠道错误码 | errCode | String | DEFAULT_ERROR | 错误码 |
| 渠道错误描述 | errMsg | String | Some error with system | 错误描述 |
# 返回示例数据
{
"code": 0,
"msg": "SUCCESS",
"data": {
"subscriptionId": "SUB_20210618001",
"mchOrderNo": "sub1624005107281",
"state": 0,
"isActive": false,
"payDataType": "payurl",
"payData": "https://cashier-hub.enjoypayment.com/..."
},
"sign": "F4DA202C516D1F33A12F1E547C5004FD"
}