创建 - Subscription create

请求地址

https://{{gateway_domain}}/pg/v2/payment/subscription/create

请求参数

HTTP Method

POST

HTTP Header

字段	数据类型	长度限制	是否必填项	说明
Content-Type	String	N/A	是	字段值只支持 application/json
Accept	String	N/A	是	字段值只支持 application/json
Authorization	String		是	Authorization: {type} {credentials}，详情参考签名规范部分

HTTP Body

字段	数据类型	长度限制	是否必填项	说明
merchantSubscriptionNo	String	50	是	商户自行生成的订阅号，建议商户保证唯一性
description	String	80	是	订单的标题，有些场景如果消费者看到订单信息，可能会展示此字段内容
payer	JSON Object		是	付款人信息，参考payer参数说明
billingModel	JSON Object		是	用户订阅的模式，参照对照表-订阅模式
scheduleUnit	String	20	是	每期订阅的周期单位，参照对照表-周期单位
scheduleLength	String	20	是	每期订阅的周期步长，表示每一期订阅有几个周期单位
marketingStrategy	JSON Object		是	营销策略数据
tradeEnv	JSON Object			用户交易环境信息
merchantAttach	String	255	否	如使用此字段，同步/异步通知、订单查询接口将原样返回该字段值
notifyUrl	String	255	是	订单在支付成功时，支付平台会通过后台调用此url通知商户
returnUrl	String	255	是	订单支付完毕时，如果上游支持同步跳转，支付平台会将用户的页面跳转到此url上

• billingModel 参数结构说明
  • billingModel 为动态参数，包含了固定字段 type，以及根据 type 的不同包含不同的字段

字段	数据类型	长度限制	是否必填项	说明
type	String	20	是
amount	String	18	是	每期订阅的金额大小，整数 1-15 位，保留2位小数，比如："100.05"
currency	String	3	是	国际统一币种简称，表示amount金额的币种，参照对照表-币种

• marketingStrategy 参数结构说明
  • marketingStrategy 为动态参数，包含了固定字段 type，以及根据 type 的不同包含不同的字段

字段	数据类型	长度限制	是否必填项	说明
type	String	20	是

• payer 参数说明
  • email和phone 二选一

字段	数据类型	长度限制	是否必填项	说明
userId	String	64	否	付款人Id
name	String	80	否	付款人名称
email	String	80	否	付款人Email，与 phone 二选一，至少填其一
phone	String	20	否	付款人手机号，与 email 二选一，至少填其一

• tradeEnv 参数说明

字段	数据类型	长度限制	是否必填项	说明
deviceId	String	50		付款人设备ID
ip	String	32		付款人设备IP

响应结果

HTTP Header

字段	数据类型	是否必填项	说明
Content-Type	String	是	字段值只支持 application/json
Authorization	String	是	Authorization: {type} {credentials}，详情参考签名规范部分

HTTP Body

字段	数据类型	是否必填项	说明
code	String	是
errorMessage	String	否	错误信息
data	JSON Object	否

data 字段说明

字段	数据类型	是否必填项	说明
subscriptionNo	String	是	支付平台的订阅号
merchantSubscriptionNo	String	是	商户生成的订阅号
action	JSON Object	是	可变返回字段

action 字段说明

• payUrl为支付平台生成的支付链接，用户点击后跳转到支付平台进行支付

{
    "action": {
        "payUrl": "https://xxx.yy"
    }
}

:::

示例

请求

curl https://{{gateway_domain}}/pg/v2/payment/subscription/create \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H 'Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=9e494e8a91bcdd08f18ad5b2cfdbfd5654f5c00c89f8216eebd7c1637b6ce01b,timestamp=1714128828114,nonce=C7CA27DC6D55DA935DFC8450C721CC99' \
  -d '{
  "merchantSubscriptionNo": "MSN-1161",
  "description": "subscription test",
  "payer": {
    "userId": "test_id",
    "name": "testName",
    "email": "[email protected]",
    "phone": "00000000"
  },
  "billingModel": {
    "type": "FIXED_SCHEDULE_AND_FIXED_AMOUNT",
    "amount": "10.00",
    "currency": "RUB"
  },
  "scheduleUnit": "MONTH",
  "scheduleLength": "1",
  "marketingStrategy": {
    "type": "DEFAULT"
  },
  "tradeEnv": {
    "ip": "127.0.0.1",
    "deviceId": "02efc74d-3988-4f0d-8cc8-0cb78bded719"
  },
  "merchantAttach": "merchant attach",
  "notifyUrl": "https://example.com/notifyurl",
  "returnUrl": "https://example.com/returnurl"
}'

响应

HTTP/1.1 200 OK
Content-Type: application/json
Server: nginx/1.18.0
Date: Mon, 06 Mar 2024 12:00:00 GMT
Authorization: V2_SHA256 appId=1111b620f93b48c5904210ff47bb1111,sign=ac6ae72f8c46f5c2092c3dab9bb0e08b6cdb6d5e7ff8ad190499a8955d57f297,timestamp=1714128245401,nonce=28FA11BF8FD1309767551B4FD8A57BD5

{
    "code": "OK",
    "errorMessage": null,
    "data": {
        "subscriptionNo": "20240423220624300800001097000004",
        "merchantSubscriptionNo": "MSN-1161",
        "action": {
            "payUrl": "https://xxx.yy"
        }
    }
}

说明

若后续扣款失败，分以下几种情况：

• 用户在银行侧主动取消授权，则不再重试，直接关闭订阅
• 用户未取消授权，但用户余额不足，会尝试重试三次，每天重试一次，三次若扣款不成功，则不再重试