创建订阅收银台会话

约 164 字小于 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必填
订阅计划每个正式计费周期的扣款金额和币种，金额不可为 0。
- amountString(12)必填
  每期扣款金额；当前实现要求不能为 0。
- currencyString(3)必填
  每期扣款币种。
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)必填
订阅计划描述。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。
notifyUrlString(512)必填
订阅通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
redirectUrlString(255)必填
支付或订阅处理完成后的跳转地址。
payCancelUrlString(255)必填
用户取消支付后的跳转地址。
paymentNotifyUrlString(255)可选
本次支付结果通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
remarkString(255)可选
商户扩展字段。
languageString(12)可选
交互语言。
tradeCountryString(2)必填
用于指定 PingPong 收银台国家。
shopperIPString(128)必填
用户下单IP，支持 IPv4 格式。
merchantSourceString(64)按条件选
建站平台标识，建站平台接入时上送。
merchantRequestBillDescriptorString(22)可选
商家自定义动态账单描述，最长 22 个字符；仅允许英文字母、数字、空白字符及英文符号 , . ( ) - / :，不允许中文或其他特殊符号。不同渠道侧可能会做适当截取。
merchantUserIdString(256)必填
商户侧用户唯一 ID。
paymentMethodsArray可选
收银台允许展示的支付方式列表，用于控制本次订阅收银台可向用户展示的支付方式范围。当前支持：
- CARD 国际信用卡
- ApplePay
- GooglePay
- Klarna
- PayPal

请求报文示例

{
  "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",
    "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"
    },
    "redirectUrl": "https://merchant.example.com/subscription/return",
    "payCancelUrl": "https://merchant.example.com/subscription/cancel",
    "paymentNotifyUrl": "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"
    }
  }
}

Responses Body Parameters

application/json

公共返回参数

bizContent

periodObject必填
订阅周期信息。
- countInteger必填
  单个正式计费周期包含的单位数量，必须大于等于 1。例如，unit 为 MONTH、count 为 1 表示每月计费一次；此字段不是订阅总期数。
- unitString必填
  订阅周期单位类型，有效值包括：
  YEAR：表示订阅周期以年为单位。
  MONTH：表示订阅周期以月为单位。
  WEEK：表示订阅周期以周为单位。
  DAY：表示订阅周期以天为单位。
trialObject可选
试用期信息。
- startAtString(10)可选
  试用期开始时间，10 位秒级时间戳字符串。
- endAtString(10)按条件选
  试用期结束时间，10 位秒级时间戳字符串。
- periodDaysInteger按条件选
  试用期持续天数。
autoRecoveryObject可选
自动重试配置。
- enabledBoolean可选
  是否开启自动重试，默认自动开启。
  true 开启重试
  false 关闭重试
flatPriceObject必填
订阅计划每个正式计费周期的扣款金额和币种。
- amountString(12)必填
  订阅支付金额。
- currencyString(3)必填
  订阅计划扣款币种。
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
requestIdString(64)必填
商户请求唯一编号。
subscriptionIdString(64)必填
PingPong 订阅单号。
statusString(32)必填
订阅计划状态。有效值包括：
- PENDING 订阅已创建，但尚未进入正式生效阶段。
- IN_TRIAL 订阅处于试用期内，当前服务可用，但尚未完成首次正式收费。
- ACTIVE 订阅当前正常生效中，用户有权使用服务。
- PAST_DUE 订阅已到应扣款时间，但本次扣款失败，进入欠费/补扣阶段。
- CANCELLED 订阅已终止，不再继续自动续费。
redirectUrlString(255)可选
收银台完成支付跳转地址。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。
notifyUrlString(255)必填
订阅通知地址。
totalPeriodCountInteger可选
订阅计划包含的正式扣款周期总数，必须大于等于 1，不包含试用期。不传时不限制正式扣款期数。
tokenString必填
Subscription Checkout Session Token。
innerJsUrlString必填
JS SDK 加载地址。
paymentUrlString必填
支付收银台地址。

响应报文示例

{
  "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": "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
    },
    "status": "PENDING",
    "flatPrice": {
      "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"
}