---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/subscription/api/create/index.md
description: 创建订阅 S2S 接口用于商户通过服务端直连方式创建订阅计划，并同步提交首期支付、订阅周期、试用期、用户信息和支付方式等数据。
---
# 创建订阅 S2S

```apidef
endpoint: POST /v4/subscriptions/create
name: 创建订阅 S2S
summary: 服务端创建订阅计划
tags: Subscription, S2S
```

创建订阅 S2S 接口用于商户通过服务端直连方式创建订阅计划，并同步提交首期支付、订阅周期、试用期、用户信息和支付方式等数据。

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| 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 | 订阅计划的描述，例如 Youtube monthly menbership。 |
| └─ redirectUrl | string | M | 订阅过程中需要商户处理的重定向地址，一般指3ds挑战页面，钱包授权绑定页面。 |
| └─ 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 | 每期扣款金额。 |
| └─ currency | string | M | 每期扣款币种，ISO 4217 三位币种代码。 |
| └─ paymentNotificationUrl | string | O | 支付结果异步通知地址。 |
| └─ remark | string | O | 商户扩展字段，响应中会原样返回。 |
| └─ language | string | O | 交互语言。 |
| └─ tradeCountry | string | O | 用于指定pingpong收银台国家，默认取pingpong侧支持的国家。 |
| └─ shopperIP | string | M | 用户下单IP，支持 IPv4 格式。 |
| └─ merchantRequestBillDescriptor | string | O | 商家自定义动态名，不同渠道侧会做适当截取（只支持英文和数字）。 |
| └─ merchantUserId | string | M | 商户侧用户唯一 ID。 |
| └─ paymentMethod | object | M | 支付方式和支付要素。 |
| └─ └─ type | string | M | 支付方式类型。当前支持列表： scheme 国际信用卡; ApplePay; GooglePay; Klarna; PayPal; |
| └─ └─ cardInfo | object | C | 卡支付信息；当使用国际卡时必填。 |
| └─ └─ └─ number | string | M | 银行卡号。 |
| └─ └─ └─ expireMonth | string | M | 卡有效期月份。 |
| └─ └─ └─ expireYear | string | M | 卡有效期年份。 |
| └─ └─ └─ holderFirstName | string | M | 持卡人名。 |
| └─ └─ └─ holderLastName | string | M | 持卡人姓。 |
| └─ └─ └─ cvv | string | M | 卡安全码。 |
| └─ jsGeneratedData | string | C | 卡支付必须接入风控组件，卡支付需要传，若获取失败，可传空字符串，不阻塞支付流程。 通过嵌入pingpong提供的风控组件，获取浏览器相关信息的json字符串，传到这个参数中。使用风控插件对接的商户使用，详见3DS集成指南: /notes/zh/risk/3ds/。 |
| └─ customer | object | M | 客户信息。 |
| └─ └─ 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_202606110001\",\"requestId\":\"REQ_SUB_CREATE_001\",\"description\":\"Monthly membership subscription\",\"redirectUrl\":\"https://merchant.example.com/subscription/return\",\"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\",\"paymentNotificationUrl\":\"https://merchant.example.com/notify/payment\",\"remark\":\"test subscription\",\"language\":\"en\",\"tradeCountry\":\"US\",\"shopperIP\":\"8.8.8.8\",\"merchantRequestBillDescriptor\":\"TEST SUB\",\"merchantUserId\":\"USER_001\",\"paymentMethod\":{\"type\":\"scheme\",\"cardInfo\":{\"number\":\"4111111111111111\",\"expireMonth\":\"12\",\"expireYear\":\"2030\",\"holderFirstName\":\"John\",\"holderLastName\":\"Smith\",\"cvv\":\"123\"}},\"jsGeneratedData\":\"JS_GENERATED_DATA\",\"customer\":{\"firstName\":\"John\",\"lastName\":\"Smith\",\"email\":\"john.smith@example.com\",\"phone\":\"13800138000\",\"phoneCountryCode\":\"86\",\"identificationType\":\"ID_CARD\",\"identificationId\":\"ID123456\",\"birthDate\":\"1990-01-01\",\"accountNumber\":\"123456789012\",\"domesticCardNumber\":\"9704123456789012\",\"domesticCardIssuingDate\":\"2020-01\",\"domesticCardExpireMonth\":\"12\",\"domesticCardExpireYear\":\"2030\"},\"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\",\"district\":\"SOMA\"},\"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 订阅已终止，不再继续自动续费。; |
| └─ 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 关闭重试; |
| └─ threeDContinue | string | 是否需要继续 3DS 流程。 |
| └─ threeDUnionParams | object | 3DS 处理参数。 |
| └─ └─ threeDSMethodData | string | 3DS Method 数据。 |
| └─ └─ creq | string | 3DS Challenge 请求参数。 |
| └─ paymentMethod | object | 支付方式信息。 |
| └─ └─ type | string | 支付方式类型。 |
| └─ └─ cardInfo | object | 支付方式中的卡信息。 |
| └─ └─ └─ firstSixDigits | string | 卡号前六位。 |
| └─ └─ └─ lastFourDigits | string | 卡号后四位。 |
| └─ └─ └─ issuringBank | string | 发卡行。 |
| └─ └─ └─ isoCountry | string | 发卡国家。 |
| └─ └─ └─ paymentBrand | string | 卡品牌。 |
| └─ └─ └─ cardType | string | 卡类型。 |
| └─ └─ └─ cardLevel | string | 卡等级。 |
| └─ └─ └─ lastName | string | 持卡人姓。 |
| └─ └─ └─ firstName | string | 持卡人名。 |
| └─ └─ └─ ipCountry | string | IP 所属国家。 |
| └─ └─ └─ isoCountryA2 | string | ISO 3166-1 alpha-2 国家码。 |
| └─ cardInfo | object | 卡信息。 |
| └─ └─ firstSixDigits | string | 卡号前六位。 |
| └─ └─ lastFourDigits | string | 卡号后四位。 |
| └─ └─ issuringBank | string | 发卡行。 |
| └─ └─ isoCountry | string | 发卡国家。 |
| └─ └─ paymentBrand | string | 卡品牌。 |
| └─ └─ cardType | string | 卡类型。 |
| └─ └─ cardLevel | string | 卡等级。 |
| └─ └─ lastName | string | 持卡人姓。 |
| └─ └─ firstName | string | 持卡人名。 |
| └─ └─ ipCountry | string | IP 所属国家。 |
| └─ └─ isoCountryA2 | string | ISO 3166-1 alpha-2 国家码。 |
| └─ authenticationInfo | object | 支付认证信息。 |
| └─ └─ threeDSecure | string | 3DS 校验结果标识。 |
| └─ └─ cvvResult | string | cvv验证结果，Y/N |
| └─ └─ avsResult | string | AVS 校验结果。 |
| └─ action | object | 支付后续动作信息。 |
| └─ └─ type | string | 下一步动作类型。 |
| └─ └─ qrCode | string | 二维码内容。 |
| └─ └─ qrUrl | string | 二维码链接。 |
| └─ └─ paymentRedirectUrl | string | 支付跳转地址。 |
| └─ └─ jsSdkUrl | string | JS SDK 地址。 |
| └─ issuerInfo | object | 发卡行返回信息。 |
| └─ └─ issuerResultCode | string | 发卡行结果码。 |
| └─ └─ issuerResultMsg | string | 发卡行结果描述。 |

### 响应示例

```json
{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": "{\"merchantSubscriptionId\":\"SUB_MER_001\",\"requestId\":\"REQ_SUB_CREATE_001\",\"subscriptionId\":\"SUB-1234567890abcdef\",\"status\":\"PENDING\",\"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},\"threeDContinue\":\"Y\",\"threeDUnionParams\":{\"threeDSMethodData\":\"THREEDS_METHOD_DATA\",\"creq\":\"CREQ_VALUE\"},\"paymentMethod\":{\"type\":\"CARD\",\"cardInfo\":{\"firstSixDigits\":\"411111\",\"lastFourDigits\":\"1111\",\"issuringBank\":\"CHASE\",\"isoCountry\":\"US\",\"paymentBrand\":\"VISA\",\"cardType\":\"CREDIT\",\"cardLevel\":\"PLATINUM\",\"lastName\":\"Lebron\",\"firstName\":\"James\",\"ipCountry\":\"US\",\"isoCountryA2\":\"US\"}},\"cardInfo\":{\"firstSixDigits\":\"411111\",\"lastFourDigits\":\"1111\",\"issuringBank\":\"CHASE\",\"isoCountry\":\"US\",\"paymentBrand\":\"VISA\",\"cardType\":\"CREDIT\",\"cardLevel\":\"PLATINUM\",\"lastName\":\"Lebron\",\"firstName\":\"James\",\"ipCountry\":\"US\",\"isoCountryA2\":\"US\"},\"authenticationInfo\":{\"threeDSecure\":\"Y\",\"cvvResult\":\"Y\",\"avsResult\":\"U\"},\"action\":{\"type\":\"PAYMENT_REDIRECT_URL\",\"qrCode\":\"QR_CODE_CONTENT\",\"qrUrl\":\"https://merchant.example.com/qr.png\",\"paymentRedirectUrl\":\"https://merchant.example.com/payment/redirect\",\"jsSdkUrl\":\"https://pay-cdn.pingpongx.com/sdk.js\"},\"issuerInfo\":{\"issuerResultCode\":\"00\",\"issuerResultMsg\":\"APPROVED\"}}",
  "code": "000000",
  "description": "SUCCESS"
}
```