创建订阅（API Only）

约 245 字小于 1 分钟

View as Markdown

2026-06-16

POST

📍如何选择站点？请参阅 API 端点地址

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

periodObject必填
订阅周期信息。
- countInteger必填
  单个正式计费周期包含的单位数量，必须大于等于 1。例如，unit 为 MONTH、count 为 1 表示每月计费一次；此字段不是订阅总期数。
- unitString必填
  订阅周期单位类型，有效值包括：
  YEAR：表示订阅周期以年为单位。
  MONTH：表示订阅周期以月为单位。
  WEEK：表示订阅周期以周为单位。
  DAY：表示订阅周期以天为单位。
trialObject可选
试用期信息。
- startAtString(10)可选
  试用期开始时间，10 位秒级时间戳字符串。
- endAtString(10)按条件选
  试用期结束时间，10 位秒级时间戳字符串。和 periodDays 至少传一个。两个字段都填时以 endAt 为准。
- periodDaysInteger按条件选
  试用期持续天数，从试用期开始时间 startAt 开始计算。
autoRecoveryObject可选
自动重试配置。
- enabledBoolean可选
  是否开启自动重试，默认自动开启。
  true 开启重试
  false 关闭重试
flatPriceObject必填
订阅计划每个正式计费周期的扣款金额和币种。
- amountString(12)必填
  每期扣款金额。
- currencyString(3)必填
  每期扣款币种，ISO 4217 三位币种代码。
discountObject可选
订阅计划折扣配置。仅作用于正式计费周期，不作用于试用期。
- typeString(32)必填
  折扣类型。有效值：
  fixedAmount：固定金额折扣。
  percentage：百分比折扣。
- amountOffString(12)按条件选
  固定金额减免。仅当 type 为 fixedAmount 时传入；与 percentOff 互斥。
- percentOffString(12)按条件选
  百分比减免值。仅当 type 为 percentage 时传入；与 amountOff 互斥。
- durationCountString(12)必填
  折扣持续的正式计费周期数，不包含试用期。
paymentMethodObject必填
支付方式和支付要素。
- typeString(32)必填
  支付方式类型。当前支持列表：
  scheme 国际信用卡
  ApplePay
  GooglePay
  Klarna
  PayPal
- cardInfoObject按条件选
  卡支付信息；当使用国际卡时必填。
  - numberString必填
    银行卡号。
  - expireMonthString(2)必填
    卡有效期月份。
  - expireYearString(4)必填
    卡有效期年份。
  - holderFirstNameString必填
    持卡人名。
  - holderLastNameString必填
    持卡人姓。
  - cvvString必填
    卡安全码。
customerObject可选
客户信息。已传 customerId 时无需再传，买家资料以 customerId 关联的买家档案为准。
- firstNameString可选
  用户名字。
- lastNameString可选
  用户姓氏。
- emailString(128)可选
  用户邮箱。
- phoneString(20)可选
  用户手机号。
- phoneCountryCodeString(5)可选
  手机号国家区号。
- identificationTypeString(20)可选
  证件类型。
- identificationIdString(20)可选
  证件号码。
- birthDateString(10)可选
  出生日期。
- accountNumberString可选
  账户号。
- domesticCardNumberString可选
  本地卡号。
- domesticCardIssuingDateString可选
  本地卡签发日期。
- domesticCardExpireMonthString可选
  本地卡有效期月份。
- domesticCardExpireYearString可选
  本地卡有效期年份。
goodsObject必填
商品信息。
- nameString(128)必填
  商品名称。
- descriptionString(255)可选
  商品描述。
- skuString(255)可选
  商品编号，产品SKU。
- unitPriceString(12)必填
  商品单价。注意：单个商品的 unitPrice × number 之和须与 flatPrice.amount 一致，否则返回 301012。
- unitTaxAmountString(12)按条件选
  单个商品税费，订单总金额包含税费时必填。
- taxRateString可选
  税率。
- totalDiscountAmountString按条件选
  单个商品总优惠金额，订单总金额涉及优惠时必填。
- numberString(12)必填
  商品购买数量。
- imgUrlString(255)必填
  商品主图链接。
- virtualProductString(1)可选
  是否是虚拟产品，虚拟商品（Y/N）。
- itemTypeString(1)可选
  商品类型，枚举值：1/2/3，对应含义如下：
  1 DIGITAL：数字商品
  2 PHYSICAL：实物商品
  3 SERVICE：服务
billingAddressObject必填
账单地址。
- streetString(256)必填
  账单地址街道。
- postcodeString(16)必填
  邮编。
- cityString(50)必填
  城市。
- stateString(128)必填
  州/省。
- countryString(64)必填
  国家二字码。
- districtString可选
  区县。
browserInfoObject可选
浏览器信息，当支付方式为卡支付时必传。
- windowSizeString可选
  窗口大小：
  01-250x400
  02-390x400
  03-500x600
  04-600x400
  05-Full screen
- acceptHeaderString可选
  http响应头信息，示例值：text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, image/apng, *;q=0.8
- colorDepthString可选
  窗口颜色，获取浏览器 screen.colorDepth。示例值：32
- screenHeightString可选
  窗口高度。
- screenWidthString可选
  屏幕宽度（单位：像素）。
- jetLagString可选
  UTC时间和持卡人浏览器本地时间之间的时差，以分钟为单位。
- userAgentString可选
  浏览器用户代理信息。
- javaEnabledBoolean可选
  持卡人终端是否能够执行Java。
- javaScriptEnabledBoolean可选
  指示购物者的浏览器是否能够执行JavaScript。如果字段不存在，则假定为默认的 true 值。
deviceObject必填
设备信息，accessModel取值，可以不填。
- orderTerminalString(2)必填
  01-移动端浏览器(app)
  02-PC端浏览器(pc)
  04-SDK(ios)
  05-SDK(Android)
  06-微信小程序
  09-二维码
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
requestIdString(64)必填
商户请求唯一编号。
descriptionString(256)必填
订阅计划的描述，例如 Youtube monthly menbership。
redirectUrlString(255)可选
订阅过程中需要商户处理的重定向地址，一般指3ds挑战页面，钱包授权绑定页面。沙箱实测（2026-10-21）不传也可创建成功；若首期支付可能触发 3DS/授权跳转，建议传入。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。不填时默认取当前时间。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。保留商户指定结束时间的能力；未指定结束时间和总期数时持续自动续费。
notifyUrlString(512)必填
订阅计划通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
payResultUrlString(512)必填
支付结果页跳转地址（首期支付完成后用户重定向回商户的页面）。沙箱实测（2026-10-21）：必填，缺失报 `payResultUrl:must not be blank`（102000）。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
paymentNotifyUrlString(255)可选
支付结果异步通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
remarkString(255)可选
商户扩展字段，响应中会原样返回。
languageString(12)可选
交互语言。
tradeCountryString(2)必填
交易国家，使用 ISO 3166-1 alpha-2 国家二字码。
shopperIPString(64)必填
用户下单IP，支持 IPv4 格式。
merchantRequestBillDescriptorString(22)可选
商家自定义动态账单描述，最长 22 个字符；仅允许英文字母、数字、空白字符及英文符号 , . ( ) - / :，不允许中文或其他特殊符号。不同渠道侧可能会做适当截取。
customerIdString(64)必填
PingPong 买家 ID。需先通过创建买家接口创建买家后获得；不传时报 102000 customerId: must not be blank。
jsGeneratedDataString(256)按条件选
卡支付必须接入风控组件，卡支付需要传，若获取失败，可传空字符串，不阻塞支付流程。通过嵌入pingpong提供的风控组件，获取浏览器相关信息的json字符串，传到这个参数中。使用风控插件对接的商户使用，详见3DS集成指南。

请求报文示例

{
  "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",
    "payResultUrl": "https://merchant.example.com/subscription/result",
    "startAt": "1781116800",
    "notifyUrl": "https://merchant.example.com/notify/subscription",
    "period": {
      "count": 1,
      "unit": "MONTH"
    },
    "totalPeriodCount": 12,
    "trial": {
      "startAt": "1781116800",
      "endAt": "1781721600",
      "periodDays": 7
    },
    "autoRecovery": {
      "enabled": true
    },
    "flatPrice": {
      "amount": "9.99",
      "currency": "USD"
    },
    "discount": {
      "type": "fixedAmount",
      "amountOff": "1.00",
      "durationCount": "3"
    },
    "paymentNotifyUrl": "https://merchant.example.com/notify/payment",
    "remark": "test subscription",
    "language": "en",
    "tradeCountry": "US",
    "shopperIP": "8.8.8.8",
    "merchantRequestBillDescriptor": "TEST SUB",
    "customerId": "CUS-260507100000000001",
    "paymentMethod": {
      "type": "scheme",
      "cardInfo": {
        "number": "4111111111111111",
        "expireMonth": "12",
        "expireYear": "2030",
        "holderFirstName": "John",
        "holderLastName": "Smith",
        "cvv": "123"
      }
    },
    "jsGeneratedData": "JS_GENERATED_DATA",
    "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"
    }
  }
}

Responses Body Parameters

application/json

公共返回参数

bizContent

flatPriceObject必填
当前订阅计划每个正式计费周期的扣款金额和币种。
- amountString(12)必填
  订阅计划每个正式计费周期的实际扣款金额。
- currencyString(3)必填
  订阅计划正式计费周期的扣款币种，使用三位字母的 ISO 4217 币种代码。
discountObject可选
当前生效的订阅折扣配置；未配置折扣时不返回。
- typeString(32)必填
  折扣类型。有效值：
  fixedAmount：固定金额折扣。
  percentage：百分比折扣。
- amountOffString(12)按条件选
  固定金额减免。仅当 type 为 fixedAmount 时传入；与 percentOff 互斥。
- percentOffString(12)按条件选
  百分比减免值。仅当 type 为 percentage 时传入；与 amountOff 互斥。
- durationCountString(12)必填
  折扣持续的正式计费周期数，不包含试用期。
periodObject可选
订阅周期信息。
- countInteger必填
  单个正式计费周期包含的单位数量，必须大于等于 1。例如，unit 为 MONTH、count 为 1 表示每月计费一次；此字段不是订阅总期数。
- unitString必填
  订阅周期单位类型，有效值包括：
  YEAR：表示订阅周期以年为单位。
  MONTH：表示订阅周期以月为单位。
  WEEK：表示订阅周期以周为单位。
  DAY：表示订阅周期以天为单位。
trialObject可选
试用期信息。
- startAtString(10)可选
  试用期开始时间，10 位秒级时间戳字符串。
- endAtString(10)按条件选
  试用期结束时间，10 位秒级时间戳字符串。
- periodDaysInteger按条件选
  试用期持续天数。
autoRecoveryObject可选
自动重试配置。
- enabledBoolean可选
  是否开启自动重试，默认自动开启。
  true 开启重试
  false 关闭重试
threeDUnionParamsObject可选
3DS 处理参数。
- threeDSMethodDataString可选
  3DS Method 数据。
- creqString可选
  3DS Challenge 请求参数。
paymentMethodObject可选
支付方式信息。
- typeString(32)可选
  支付方式类型。
- cardInfoObject可选
  支付方式中的卡信息。
  - firstSixDigitsString可选
    卡号前六位。
  - lastFourDigitsString可选
    卡号后四位。
  - issuringBankString可选
    发卡行。
  - isoCountryString可选
    发卡国家。
  - paymentBrandString可选
    卡品牌。
  - cardTypeString可选
    卡类型。
  - cardLevelString可选
    卡等级。
  - lastNameString可选
    持卡人姓。
  - firstNameString可选
    持卡人名。
  - ipCountryString可选
    IP 所属国家。
  - isoCountryA2String可选
    ISO 3166-1 alpha-2 国家码。
cardInfoObject可选
卡信息。
- firstSixDigitsString可选
  卡号前六位。
- lastFourDigitsString可选
  卡号后四位。
- issuringBankString可选
  发卡行。
- isoCountryString可选
  发卡国家。
- paymentBrandString可选
  卡品牌。
- cardTypeString可选
  卡类型。
- cardLevelString可选
  卡等级。
- lastNameString可选
  持卡人姓。
- firstNameString可选
  持卡人名。
- ipCountryString可选
  IP 所属国家。
- isoCountryA2String可选
  ISO 3166-1 alpha-2 国家码。
authenticationInfoObject可选
支付认证信息。
- threeDSecureString可选
  3DS 校验结果标识。
- cvvResultString可选
  cvv验证结果，Y/N
- avsResultString可选
  AVS 校验结果。
actionObject可选
支付后续动作信息。
- typeString可选
  下一步动作类型。
- qrCodeString可选
  二维码内容。
- qrUrlString可选
  二维码链接。
- paymentRedirectUrlString可选
  支付跳转地址。
- jsSdkUrlString可选
  JS SDK 地址。
issuerInfoObject可选
发卡行返回信息。
- issuerResultCodeString可选
  发卡行结果码。
- issuerResultMsgString可选
  发卡行结果描述。
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
requestIdString(64)必填
商户请求唯一编号。
subscriptionIdString(64)必填
PingPong 订阅单号。
statusString(32)必填
订阅计划状态。有效值包括：
- PENDING 订阅已创建，但尚未进入正式生效阶段。
- IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。
- ACTIVE 订阅当前正常生效中，用户有权使用服务。
- PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。
- CANCELLED 订阅已终止，不再继续自动续费。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。
notifyUrlString(255)可选
订阅通知地址。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
threeDContinueString(32)可选
是否需要继续 3DS 流程。
partnerTransactionIdString(64)可选
首期/本期支付的商户交易单号，格式为 subscriptionId_P期次。
transactionIdString(64)可选
首期/本期支付的 PingPong 交易流水号。
remarkString(255)可选
商户扩展字段，原样回显。
resultCodeString必填
业务处理结果码。
resultMessageString必填
业务处理结果描述。

响应报文示例

{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "flatPrice": {
      "amount": "9.99",
      "currency": "USD"
    },
    "discount": {
      "type": "fixedAmount",
      "amountOff": "1.00",
      "durationCount": "3"
    },
    "merchantSubscriptionId": "SUB_MER_001",
    "requestId": "REQ_SUB_CREATE_001",
    "subscriptionId": "SUB-1234567890abcdef",
    "status": "ACTIVE",
    "resultCode": "000000",
    "resultMessage": "Transaction succeeded",
    "partnerTransactionId": "SUB-1234567890abcdef_P1",
    "transactionId": "26101600000352284454",
    "remark": "test subscription",
    "startAt": "1785152760",
    "endAt": "1817293560",
    "notifyUrl": "https://merchant.example.com/subscription/notify",
    "period": {
      "count": 1,
      "unit": "MONTH"
    },
    "totalPeriodCount": 12,
    "trial": {
      "startAt": "1785152760",
      "endAt": "1785757560",
      "periodDays": 7
    },
    "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"
}