--- url: >- https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/api/sessionCreate/index.md description: 创建订阅 Session 接口用于商户以收银台模式创建订阅计划，并返回 token、JS SDK 地址和支付链接供前端继续完成支付。 --- # 创建订阅 Session ```apidef endpoint: POST /v4/subscriptions/sessions/create name: 创建订阅 Session summary: 收银台模式创建订阅计划 tags: Subscription, Hosted ``` 创建订阅 Session 接口用于商户以收银台模式创建订阅计划，并返回 token、JS SDK 地址和支付链接供前端继续完成支付。 ## 请求参数 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | accId | string | M | 店铺唯一标识 | | clientId | string | M | PingPong 商户号 | | signType | string | M | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 | | sign | string | M | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 | | version | string | M | 版本号，当前固定为1.0，后续随接口变动可能有调整 | | bizContent | string | M | 请求参数的集合，最大长度不限，除公共请求参数外所有请求参数都必须放在这个参数中传递，格式：JSON字符串。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 | | └─ merchantSubscriptionId | string | M | 商户定义的订阅计划的唯一ID。 | | └─ requestId | string | M | 商户请求唯一编号。 | | └─ description | string | M | 订阅计划描述。 | | └─ startAt | string | O | 订阅开始时间，10 位秒级时间戳字符串。 | | └─ endAt | string | O | 订阅结束时间，10 位秒级时间戳字符串。 | | └─ notifyUrl | string | M | 订阅通知地址。 | | └─ duration | object | M | 订阅周期信息。 | | └─ └─ periodCount | integer | M | 订阅周期数量，必须大于等于 1。例如，如果 periodUnit 的值为 MONTH ， periodCount 的值为 1 ，则表示订阅周期为一个月。支持 1 - 无限。 | | └─ └─ periodUnit | string | M | 订阅周期单位类型，有效值包括： YEAR ：表示订阅周期以年为单位。; MONTH ：表示订阅周期以月为单位。; WEEK ：表示订阅周期以周为单位。; DAY ：表示订阅周期以天为单位。; | | └─ trial | object | O | 试用期信息。 | | └─ └─ startAt | string | O | 试用期开始时间，10 位秒级时间戳字符串。 | | └─ └─ endAt | string | C | 试用期结束时间，10 位秒级时间戳字符串。和 periodDays 至少传一个。两个字段都填时以 endAt 为准。 | | └─ └─ periodDays | integer | C | 试用期持续天数，从试用期开始时间 startAt 开始计算。 | | └─ └─ amount | string | C | 试用期扣款金额。指定试用期时必填。免费试用期填 0 。 | | └─ └─ currency | string | C | 订阅计划试用期的扣款币种，将用于试用期扣款。指定试用期时必填。ISO 4217 格式为三位英文字母，具体支持币种见附录交易币种: /notes/zh/appendix/transactionCurrency/。 | | └─ autoRecovery | object | O | 自动重试配置。 | | └─ └─ enabled | boolean | O | 是否开启自动重试，默认自动开启。 true 开启重试; false 关闭重试; | | └─ amount | string | M | 每期扣款金额；当前实现要求不能为 0 。 | | └─ currency | string | M | 每期扣款币种。 | | └─ redirectUrl | string | M | 支付或订阅处理完成后的跳转地址。 | | └─ payCancelUrl | string | M | 用户取消支付后的跳转地址。 | | └─ notificationUrl | string | O | 本次支付结果通知地址。 | | └─ remark | string | O | 商户扩展字段。 | | └─ language | string | O | 交互语言。 | | └─ tradeCountry | string | M | 用于指定 PingPong 收银台国家。 | | └─ shopperIP | string | M | 用户下单IP，支持 IPv4 格式。 | | └─ merchantSource | string | C | 建站平台标识，建站平台接入时上送。 | | └─ merchantRequestBillDescriptor | string | O | 商家自定义动态名，不同渠道侧会做适当截取（只支持英文和数字）。 | | └─ merchantUserId | string | M | 商户侧用户唯一 ID。 | | └─ paymentMethods | array | O | 收银台允许展示的支付方式列表，用于控制本次订阅收银台可向用户展示的支付方式范围。当前支持： CARD 国际信用卡; ApplePay; GooglePay; Klarna; PayPal; | | └─ customer | object | O | 客户信息。 | | └─ └─ firstName | string | O | 用户名字。 | | └─ └─ lastName | string | O | 用户姓氏。 | | └─ └─ email | string | O | 用户邮箱。 | | └─ └─ phone | string | O | 用户手机号。 | | └─ └─ phoneCountryCode | string | O | 手机号国家区号。 | | └─ └─ identificationType | string | O | 证件类型。 | | └─ └─ identificationId | string | O | 证件号码。 | | └─ └─ birthDate | string | O | 出生日期。 | | └─ └─ accountNumber | string | O | 账户号。 | | └─ └─ domesticCardNumber | string | O | 本地卡号。 | | └─ └─ domesticCardIssuingDate | string | O | 本地卡签发日期。 | | └─ └─ domesticCardExpireMonth | string | O | 本地卡有效期月份。 | | └─ └─ domesticCardExpireYear | string | O | 本地卡有效期年份。 | | └─ goods | array | M | 商品信息。 | | └─ └─ name | string | M | 商品名称。 | | └─ └─ description | string | O | 商品描述。 | | └─ └─ sku | string | O | 商品编号，产品SKU。 | | └─ └─ unitPrice | string | M | 商品单价。 | | └─ └─ unitTaxAmount | string | C | 单个商品税费，订单总金额包含税费时必填。 | | └─ └─ taxRate | string | O | 税率。 | | └─ └─ totalDiscountAmount | string | C | 单个商品总优惠金额，订单总金额涉及优惠时必填。 | | └─ └─ number | string | M | 商品购买数量。 | | └─ └─ imgUrl | string | M | 商品主图链接。 | | └─ └─ virtualProduct | string | O | 是否是虚拟产品，虚拟商品（ Y / N ）。 | | └─ └─ itemType | string | O | 商品类型，枚举值： 1 / 2 / 3 ，对应含义如下： 1 DIGITAL：数字商品; 2 PHYSICAL：实物商品; 3 SERVICE：服务; | | └─ billingAddress | object | M | 账单地址。 | | └─ └─ street | string | M | 账单地址街道。 | | └─ └─ postcode | string | M | 邮编。 | | └─ └─ city | string | M | 城市。 | | └─ └─ state | string | M | 州/省。 | | └─ └─ country | string | M | 国家二字码。 | | └─ └─ district | string | O | 区县。 | | └─ browserInfo | object | O | 浏览器信息，当支付方式为卡支付时必传。 | | └─ └─ windowSize | string | O | 窗口大小： 01 -250x400; 02 -390x400; 03 -500x600; 04 -600x400; 05 -Full screen; | | └─ └─ acceptHeader | string | O | http响应头信息，示例值：text/html, application/xhtml+xml, application/xml; q=0.9, image/webp, image/apng, *; q=0.8 | | └─ └─ colorDepth | string | O | 窗口颜色，获取浏览器 screen.colorDepth。示例值： 32 | | └─ └─ screenHeight | string | O | 窗口高度。 | | └─ └─ screenWidth | string | O | 屏幕宽度（单位：像素）。 | | └─ └─ jetLag | string | O | UTC时间和持卡人浏览器本地时间之间的时差，以分钟为单位。 | | └─ └─ userAgent | string | O | 浏览器用户代理信息。 | | └─ └─ javaEnabled | boolean | O | 持卡人终端是否能够执行Java。 | | └─ └─ javaScriptEnabled | boolean | O | 指示购物者的浏览器是否能够执行JavaScript。如果字段不存在，则假定为默认的 true 值。 | | └─ device | object | M | 设备信息，accessModel取值，可以不填。 | | └─ └─ orderTerminal | string | M | 01 -移动端浏览器(app); 02 -PC端浏览器(pc); 04 -SDK(ios); 05 -SDK(Android); 06 -微信小程序; 09 -二维码; | ### 请求示例 ```json { "clientId": "2024061100000000001", "accId": "20240611000000000010001", "signType": "SHA256", "sign": "SIGN_VALUE", "version": "1.0", "bizContent": "{\"merchantSubscriptionId\":\"SUB_M_202606110002\",\"requestId\":\"REQ_SUB_SESSION_001\",\"description\":\"Monthly membership subscription\",\"startAt\":\"1781116800\",\"endAt\":\"1812652800\",\"notifyUrl\":\"https://merchant.example.com/notify/subscription\",\"duration\":{\"periodCount\":1,\"periodUnit\":\"MONTH\"},\"trial\":{\"startAt\":\"1781116800\",\"endAt\":\"1781721600\",\"periodDays\":7,\"amount\":\"0.00\",\"currency\":\"USD\"},\"autoRecovery\":{\"enabled\":true},\"amount\":\"9.99\",\"currency\":\"USD\",\"redirectUrl\":\"https://merchant.example.com/subscription/return\",\"payCancelUrl\":\"https://merchant.example.com/subscription/cancel\",\"notificationUrl\":\"https://merchant.example.com/notify/payment\",\"remark\":\"test subscription session\",\"language\":\"en\",\"tradeCountry\":\"US\",\"shopperIP\":\"8.8.8.8\",\"merchantSource\":\"SHOPIFY\",\"merchantRequestBillDescriptor\":\"TEST SUB\",\"merchantUserId\":\"USER_001\",\"paymentMethods\":[\"CARD\"],\"customer\":{\"firstName\":\"John\",\"lastName\":\"Smith\",\"email\":\"john.smith@example.com\",\"phone\":\"13800138000\",\"phoneCountryCode\":\"86\"},\"goods\":[{\"name\":\"Membership\",\"description\":\"Monthly membership\",\"sku\":\"SKU_SUB_001\",\"unitPrice\":\"9.99\",\"number\":\"1\",\"imgUrl\":\"https://merchant.example.com/goods/sub.png\",\"virtualProduct\":\"Y\",\"itemType\":\"1\"}],\"billingAddress\":{\"street\":\"1 Market St\",\"postcode\":\"94105\",\"city\":\"San Francisco\",\"state\":\"CA\",\"country\":\"US\"},\"browserInfo\":{\"windowSize\":\"05\",\"acceptHeader\":\"text/html,application/xhtml+xml\",\"colorDepth\":\"32\",\"screenHeight\":\"1080\",\"screenWidth\":\"1920\",\"jetLag\":\"-480\",\"userAgent\":\"Mozilla/5.0\",\"javaEnabled\":false,\"javaScriptEnabled\":true},\"device\":{\"orderTerminal\":\"02\"}}" } ``` ## 响应参数 | 参数名 | 类型 | 说明 | |--------|------|------| | accId | string | 店铺唯一标识 | | clientId | string | PingPong 商户号 | | signType | string | 支持 MD5 、 SHA256 ，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/一栏 | | sign | string | 签名，具体⻅本文签名规约: /notes/zh/onlinePayment/developer/sign/，所有参数均参与签名 | | code | string | 结果状态码，见附录状态码表: /notes/zh/appendix/successCodeList/ | | description | string | 结果描述 | | bizContent | string | 业务响应参数。该字段内容为 JSON 字符串，反序列化后的结构见 contentSchema。 | | └─ merchantSubscriptionId | string | 商户定义的订阅计划的唯一ID。 | | └─ requestId | string | 商户请求唯一编号。 | | └─ subscriptionId | string | PingPong 订阅单号。 | | └─ status | string | 订阅计划状态。有效值包括： PENDING 订阅已创建，但尚未进入正式生效阶段。; IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。; ACTIVE 订阅当前正常生效中，用户有权使用服务。; PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。; CANCELLED 订阅已终止，不再继续自动续费。; | | └─ redirectUrl | string | 收银台完成支付跳转地址。 | | └─ startAt | string | 订阅开始时间，10 位秒级时间戳字符串。 | | └─ endAt | string | 订阅结束时间，10 位秒级时间戳字符串。 | | └─ notifyUrl | string | 订阅通知地址。 | | └─ duration | object | 订阅周期信息。 | | └─ └─ periodCount | integer | 订阅周期数量，必须大于等于 1。例如，如果 periodUnit 的值为 MONTH ， periodCount 的值为 1 ，则表示订阅周期为一个月。支持 1 - 无限。 | | └─ └─ periodUnit | string | 订阅周期单位类型，有效值包括： YEAR ：表示订阅周期以年为单位。; MONTH ：表示订阅周期以月为单位。; WEEK ：表示订阅周期以周为单位。; DAY ：表示订阅周期以天为单位。; | | └─ trial | object | 试用期信息。 | | └─ └─ startAt | string | 试用期开始时间，10 位秒级时间戳字符串。 | | └─ └─ endAt | string | 试用期结束时间，10 位秒级时间戳字符串。 | | └─ └─ periodDays | integer | 试用期持续天数。 | | └─ └─ amount | string | 试用期扣款金额。 | | └─ └─ currency | string | 试用期扣款币种。 | | └─ autoRecovery | object | 自动重试配置。 | | └─ └─ enabled | boolean | 是否开启自动重试，默认自动开启。 true 开启重试; false 关闭重试; | | └─ amount | string | 订阅支付金额。 | | └─ currency | string | 订阅计划扣款币种。 | | └─ token | string | Subscription Checkout Session Token。 | | └─ innerJsUrl | string | JS SDK 加载地址。 | | └─ paymentUrl | string | 支付收银台地址。 | ### 响应示例 ```json { "clientId": "2025050971820281024", "accId": "2025050971820281024001", "signType": "MD5", "sign": "SIGN_VALUE", "version": "1.0", "bizContent": "{\"merchantSubscriptionId\":\"SUB_MER_SESSION_001\",\"requestId\":\"REQ_SUB_SESSION_001\",\"subscriptionId\":\"SUB-abcdef1234567890\",\"redirectUrl\":\"https://merchant.example.com/checkout/result\",\"startAt\":\"1785152760\",\"endAt\":\"1816688760\",\"notifyUrl\":\"https://merchant.example.com/subscription/notify\",\"duration\":{\"periodCount\":1,\"periodUnit\":\"MONTH\"},\"trial\":{\"startAt\":\"1785152760\",\"endAt\":\"1785757560\",\"periodDays\":7,\"amount\":\"0.00\",\"currency\":\"USD\"},\"autoRecovery\":{\"enabled\":true},\"status\":\"PENDING\",\"amount\":\"9.99\",\"currency\":\"USD\",\"token\":\"EU:session_token_example\",\"innerJsUrl\":\"https://pay-cdn.pingpongx.com/pp-checkout.js?token=EU:session_token_example\",\"paymentUrl\":\"https://dev-safepay.pingpongx.com?token=EU:session_token_example\"}", "code": "000000", "description": "SUCCESS" } ```