创建订阅收银台会话

约 164 字小于 1 分钟

View as Markdown

2026-06-16

OpenAPI 总览

Request Body Parameters

application/json

公共请求参数

bizContent

durationObject必填
trialObject可选
autoRecoveryObject可选
customerObject可选
goodsArray必填
billingAddressObject必填
browserInfoObject可选
deviceObject必填
merchantSubscriptionIdString(64)必填
商户定义的订阅计划的唯一ID。
requestIdString(64)必填
商户请求唯一编号。
descriptionString(256)必填
订阅计划描述。
startAtString(10)可选
订阅开始时间，10 位秒级时间戳字符串。
endAtString(10)可选
订阅结束时间，10 位秒级时间戳字符串。
notifyUrlString(512)必填
订阅通知地址。
地址建议：请填写基于公网域名的完整 URL，推荐使用标准 Web 端口（HTTPS 默认 443，HTTP 默认 80），并确保该地址可稳定接收 PingPongCheckout 的异步通知。
amountString(12)必填
每期扣款金额；当前实现要求不能为 0。
currencyString(3)必填
每期扣款币种。
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",
    "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",
    "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

durationObject必填
trialObject可选
autoRecoveryObject可选
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)必填
订阅通知地址。
amountString(12)必填
订阅支付金额。
currencyString(3)必填
订阅计划扣款币种。
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": "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"
}