创建订阅（API Only）

约 187 字小于 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 三位币种代码。
paymentMethodObject必填
支付方式和支付要素。
- typeString(32)必填
  支付方式类型。当前支持列表：
  scheme 国际信用卡
  ApplePay
  GooglePay
  Klarna
  PayPal
- cardInfoObject按条件选
  卡支付信息；当使用国际卡时必填。
  - numberString必填
    银行卡号。
  - expireMonthString(2)必填
    卡有效期月份。
  - expireYearString(4)必填
    卡有效期年份。
  - holderFirstNameString必填
    持卡人名。
  - holderLastNameString必填
    持卡人姓。
  - cvvString必填
    卡安全码。
customerObject必填
客户信息。
- firstNameString可选
  用户名字。
- lastNameString可选
  用户姓氏。
- emailString(128)可选
  用户邮箱。
- phoneString(20)可选
  用户手机号。
- phoneCountryCodeString(5)可选
  手机号国家区号。
- identificationTypeString(20)可选
  证件类型。
- identificationIdString(20)可选
  证件号码。
- birthDateString(10)可选
  出生日期。
- accountNumberString可选
  账户号。
- domesticCardNumberString可选
  本地卡号。
- domesticCardIssuingDateString可选
  本地卡签发日期。
- domesticCardExpireMonthString可选
  本地卡有效期月份。
- domesticCardExpireYearString可选
  本地卡有效期年份。
goodsObject必填
商品信息。
- nameString(500)必填
  商品名称。
- descriptionString(500)可选
  商品描述。
- skuString(500)可选
  商品编号，产品SKU。
- unitPriceString(12)必填
  商品单价。
- 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挑战页面，钱包授权绑定页面。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。不填时默认取当前时间。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。保留商户指定结束时间的能力；未指定结束时间和总期数时持续自动续费。
notifyUrlString(512)必填
订阅计划通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
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 个字符；仅允许英文字母、数字、空白字符及英文符号 , . ( ) - / :，不允许中文或其他特殊符号。不同渠道侧可能会做适当截取。
merchantUserIdString(256)必填
商户侧用户唯一 ID。
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",
    "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"
    },
    "paymentNotifyUrl": "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"
    }
  }
}

Responses Body Parameters

application/json

公共返回参数

bizContent

flatPriceObject必填
当前订阅计划每个正式计费周期的扣款金额和币种。
- amountString(12)必填
  订阅计划每个正式计费周期的实际扣款金额。
- currencyString(3)必填
  订阅计划正式计费周期的扣款币种，使用三位字母的 ISO 4217 币种代码。
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 流程。

响应报文示例

{
  "clientId": "2025050971820281024",
  "accId": "2025050971820281024001",
  "signType": "MD5",
  "sign": "SIGN_VALUE",
  "version": "1.0",
  "bizContent": {
    "flatPrice": {
      "amount": "9.99",
      "currency": "USD"
    },
    "merchantSubscriptionId": "SUB_MER_001",
    "requestId": "REQ_SUB_CREATE_001",
    "subscriptionId": "SUB-1234567890abcdef",
    "status": "PENDING",
    "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"
}