集成方案
本页是 Subscription 的接入主流程。Subscription 的适用场景,以及与 Recurring、CodeGrant 的方案选择对比,请见 Subscription 概览;确认使用 Subscription 后,按本页步骤接入即可。
适用支付方式
- 收银台:通过 创建订阅收银台会话 创建订阅计划和收银台会话,当前可展示的支付方式包括
VISA、Mastercard、ApplePay、GooglePay、Klarna、PayPal。 API Only:通过 创建订阅(API Only) 直接创建订阅并提交首期支付,当前支持VISA、Mastercard以及已支持的ApplePay、GooglePay、Klarna、PayPal。
两种模式的取舍见下文 推荐接入模式。
支付流程
流程说明:
- 商户前端应先向买家展示订阅价格、扣款周期、试用期、订阅条款和取消入口,并由买家确认订阅。
- 商户服务端根据接入模式创建订阅:收银台模式先创建订阅收银台会话,再由买家在 PingPong 收银台完成首期支付或授权;
API Only模式由买家先在商户自建页面输入或选择支付方式,商户服务端再带支付要素创建订阅,并按接口返回继续完成 3DS、钱包授权或本地支付跳转。 - 买家完成首期支付或授权后,商户应同时处理订阅层结果和支付层结果,其中订阅状态变化以 订阅通知 为核心。
- 首期生效后,PingPong 会根据订阅配置自动维护后续计费周期、试用期和自动重试。
- 当续费失败且开启自动重试时,订阅会进入
PAST_DUE,后续是否继续提供服务由商户根据业务规则决定。
推荐接入模式
如果您已经决定使用 Subscription,还需要继续选择收银台还是 API Only:
| 模式 | 更适合谁 | 首期支付体验 | 商户需要处理什么 | 推荐程度 |
|---|---|---|---|---|
| 收银台 | 希望更快上线、由 PingPong 承接首期支付流程的团队 | 支持卡、钱包、3DS、内嵌和跳转 | 前端打开收银台,服务端处理通知和订阅状态 | 优先推荐 |
API Only | 已有自建支付页、需要完全控制支付体验或已具备相应合规能力的团队 | 商户侧自定义,可能仍需继续完成 3DS 或钱包授权 | 上送支付要素、处理风控与后续动作、处理通知 | 适合进阶团队 |
优先选择收银台的典型情况:
- 首次上线订阅能力,希望尽量降低对支付流程的接入复杂度。
- 需要同时支持
VISA/Mastercard卡、钱包和多种收银台支付方式。 - 不希望自己处理首期支付页、3DS 页面或钱包跳转细节。
更适合选择 API Only 的典型情况:
- 已经有成熟的自建支付页和服务端支付编排能力。
- 需要完全控制支付交互、表单结构和支付发起方式。
- 已具备相应的卡支付合规和风控对接能力。
接口列表
Subscription 集成通常涉及以下接口和通知:
| 阶段 | 类型 | 文档 | 是否必接 | 用途 |
|---|---|---|---|---|
| 创建与首期支付 | API | 创建买家 | 必接 | 创建订阅前必须先创建买家,获得 customerId |
| API | 创建订阅收银台会话 | 按接入模式 | 创建订阅收银台会话,并返回支付链接、token 等前端继续处理所需信息 | |
| API | 创建订阅(API Only) | 按接入模式 | 通过 API Only 创建订阅,并同步提交首期支付要素 | |
| 通知 | 订阅通知 | 必接 | 接收订阅状态变化、试用转正、续费结果和计划更新结果 | |
| 说明 | 通用异步通知接入说明 | 必读 | 了解通知地址配置、验签、幂等、ACK、重试和白名单等通用接入规则 | |
| 通知 | 支付通知 | 推荐 | 获取首期支付或每期续费对应的支付层结果与支付方式明细(含 invoiceId) | |
| API | 查询订阅详情 | 推荐 | 当通知延迟、补偿或核验状态时,拉取订阅最新快照 | |
| 生命周期管理与对账 | API | 查询订阅支付记录 | 推荐 | 查询每一期支付订单和退款关联信息 |
| API | 票据详情 | 推荐 | 按 invoiceId 查询票据金额、状态和客户信息(对账用) | |
| API | 票据下载 | 推荐 | 获取票据 PDF 下载链接(30 天有效) | |
| API | 凭证详情 | 推荐 | 按 receiptId 查询支付凭证(含退款记录) | |
| API | 凭证下载 | 推荐 | 获取凭证 PDF 下载链接 | |
| API | 预览订阅更新 | 按需 | 在正式更新前预估补扣、退款和生效方式 | |
| API | 更新订阅 | 按需 | 更新金额、周期、商品信息和账单处理策略 | |
| API | 取消订阅 | 按需 | 立即取消或在当前计费周期结束后取消订阅 |
集成准备
接入 Subscription 前,请先完成 准备工作 中的通用准备。
此外,请额外确认以下事项:
- 已为每个用户创建买家档案:通过 创建买家 接口获得
customerId(创建订阅时必填,缺失报customerId: must not be blank)。 - 已确定接入方式:收银台或
API Only。 - 已为每个订阅计划生成稳定且全局唯一的
merchantSubscriptionId,并为每次接口请求生成唯一的requestId。 - 已准备可公网访问的订阅通知地址
notifyUrl。如果您还需要支付层异步结果,请同时准备支付结果通知地址。 - 已明确订阅业务规则:每期扣款金额、币种、周期单位、周期数量、首期收费方式、试用期、自动重试策略、何时停服以及取消规则。
- 已在商户侧准备好本地映射关系,至少保存
merchantSubscriptionId、subscriptionId、用户 ID、商品/套餐、订阅状态、当前周期和通知处理状态。 - 已在用户协议、订阅确认页或下单确认环节清晰展示订阅价格、扣款币种、扣款频率、订阅条款、试用期、续费失败处理方式以及如何取消订阅。
- 已准备面向用户的清晰取消入口,并在商户侧保留用户授权留痕。
- 已准备扣款提醒、试用转正提醒、invoice / receipt 发送和用户服务权益管理方案。这些用户触达和权益管理由商户负责,PingPong 负责订阅执行、通知和支付留痕。
集成步骤
请按以下步骤完成集成:
- 步骤 0:创建买家(前置,获得
customerId) - 步骤 1:创建订阅
- 步骤 2:引导买家完成首期授权与支付
- 步骤 3:获取订阅结果和支付结果
- 步骤 4:管理续费、补扣与计划变更
步骤 0:创建买家(前置)
创建订阅前必须先创建买家档案,获得 customerId:
// POST /v4/customers/create
{
"requestId": "REQ_CUST_001",
"partnerCustomerId": "user_merchant_001",
"firstName": "Emily",
"lastName": "Johnson",
"email": "emily.johnson@example.com",
"language": "en"
}响应返回 customerId(如 CUS-260507100000000001),保存 partnerCustomerId ↔ customerId 映射,后续创建订阅时使用。
步骤 1:创建订阅
商户应先按 推荐接入模式 选择收银台或 API Only 创建订阅,请求中必须传入 customerId。
创建订阅时建议优先关注以下关键字段:
| 字段 | 必填 | 说明 |
|---|---|---|
merchantSubscriptionId | M | 商户定义的订阅计划唯一 ID,后续查询、更新、取消都建议持续使用 |
requestId | M | 本次请求唯一编号 |
description | M | 订阅计划描述,建议与商户商品或套餐名称一致 |
customerId | M | PingPong 买家 ID(由创建买家获得),用于关联买家档案 |
notifyUrl | M | 订阅通知地址,用于接收订阅状态变化和计划更新结果 |
payResultUrl | M | 首期支付完成后跳转回商户的支付结果页地址 |
flatPrice.amount / flatPrice.currency | M | 每个正式计费周期的实际扣款金额和币种 |
period.unit / period.count | M | 单个正式计费周期的单位和单位数量,例如 MONTH + 1 表示每月计费一次 |
tradeCountry | M | 收银台或交易国家,使用 ISO 3166-1 alpha-2 国家二字码;收银台和 API Only 均必填 |
shopperIP | M | 用户发起订阅时的 IP 地址 |
goods | M | 本次订阅对应的商品或服务信息,使用单个对象,不是数组;其中 goods.unitPrice × goods.number 之和须与 flatPrice.amount 一致,否则返回 301012 |
billingAddress | M | 账单地址,其中 state 为必填字段 |
device.orderTerminal | M | 用户发起订阅的终端类型 |
jsGeneratedData | C | API Only 卡支付必须传;获取失败时可传空字符串 |
totalPeriodCount | O | 正式扣款总期数,不包含试用期;不传时不限制总期数 |
startAt | O | 订阅开始时间;不传时通常按当前时间开始 |
endAt | O | 订阅计划结束时间;保留该入参,未指定结束时间和总期数时持续自动续费 |
trial | O | 试用期配置,仅包含 startAt、endAt、periodDays,不包含金额和币种 |
autoRecovery.enabled | O | 是否开启续费失败后的自动重试 |
language | O | 交互语言 |
创建订阅时,各时间字段应保持在同一条主时间轴上:
| 时间字段 / 节点 | 产品规则 |
|---|---|
startAt | 整个订阅计划的生效时间,也是正式周期计算的主锚点 |
trial.startAt | 不传时默认等于 startAt;传入时也应与 startAt 相等 |
trial.endAt | 试用期结束时间;存在试用期时,也是首个正式计费周期开始和首次正式扣款时间 |
| 无试用期的首次正式扣款 | 在 startAt 执行;如果 startAt 晚于创建时间,创建后先完成支付方式绑定或授权,到 startAt 再正式扣款 |
endAt | 到达该时间后不再生成新一期扣款任务;未指定结束时间和总期数时按订阅周期持续自动续费 |
period.count 表示一次计费周期包含多少个单位,totalPeriodCount 表示一共计费多少期。例如 period={"unit":"MONTH","count":1}、totalPeriodCount=12 表示共 12 个按月计费的正式周期;试用期不计入这 12 期。以下示例使用总期数,不同时指定 endAt。
模式差异说明:
- 收银台通过
paymentMethods控制允许向买家展示的支付方式范围。 API Only通过paymentMethod上送本次首期支付的支付方式和支付要素。- 如果您还需要支付层异步通知,两种创建接口均使用
paymentNotifyUrl。
收银台创建会话示例(仅展示 bizContent):
{
"merchantSubscriptionId": "SUB_PLAN_202607150001",
"merchantTransactionId": "MT_SUB_202607150001",
"requestId": "REQ_SUB_SESSION_202607150001",
"description": "Premium monthly membership",
"notifyUrl": "https://merchant.example.com/notify/subscription",
"paymentNotifyUrl": "https://merchant.example.com/notify/payment",
"redirectUrl": "https://merchant.example.com/subscription/result",
"payCancelUrl": "https://merchant.example.com/subscription/cancel",
"payResultUrl": "https://merchant.example.com/subscription/result",
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"language": "en",
"tradeCountry": "US",
"shopperIP": "8.8.8.8",
"customerId": "CUS-260507100000000001",
"period": {
"unit": "MONTH",
"count": 1
},
"totalPeriodCount": 12,
"trial": {
"periodDays": 7
},
"autoRecovery": {
"enabled": true
},
"paymentMethods": [
"VISA",
"Mastercard"
],
"goods": {
"name": "Premium membership",
"description": "Monthly membership service",
"sku": "MEMBERSHIP-001",
"unitPrice": "9.99",
"number": "1",
"imgUrl": "https://merchant.example.com/images/membership.png",
"virtualProduct": "Y",
"itemType": "3"
},
"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"
}
}API Only 创建订阅示例(仅展示 bizContent):
{
"merchantSubscriptionId": "SUB_PLAN_202607150002",
"requestId": "REQ_SUB_DIRECT_202607150001",
"description": "Premium monthly membership",
"notifyUrl": "https://merchant.example.com/notify/subscription",
"paymentNotifyUrl": "https://merchant.example.com/notify/payment",
"redirectUrl": "https://merchant.example.com/subscription/result",
"payResultUrl": "https://merchant.example.com/subscription/result",
"flatPrice": {
"amount": "9.99",
"currency": "USD"
},
"language": "en",
"tradeCountry": "US",
"shopperIP": "8.8.8.8",
"customerId": "CUS-260507100000000001",
"period": {
"unit": "MONTH",
"count": 1
},
"totalPeriodCount": 12,
"autoRecovery": {
"enabled": true
},
"paymentMethod": {
"type": "scheme",
"cardInfo": {
"number": "4111111111111111",
"expireMonth": "12",
"expireYear": "2030",
"holderFirstName": "John",
"holderLastName": "Smith",
"cvv": "123"
}
},
"jsGeneratedData": "",
"goods": {
"name": "Premium membership",
"description": "Monthly membership service",
"sku": "MEMBERSHIP-001",
"unitPrice": "9.99",
"number": "1",
"imgUrl": "https://merchant.example.com/images/membership.png",
"virtualProduct": "Y",
"itemType": "3"
},
"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"
}
}注意
- 创建成功的同步响应不等于订阅已经正式生效。
- 首期支付结果和订阅状态变更必须通过服务端通知或主动查询确认。
- 如果首期支付依赖 3DS 挑战、钱包授权或跳转流程,只有这些后续动作完成后,订阅才可能进入
IN_TRIAL或ACTIVE。 - 对同一用户重复创建同一业务订阅前,建议先在商户侧检查
merchantSubscriptionId是否已存在,避免产生重复订阅。 - 如果创建接口超时、返回网关错误或结果不确定,不要立即换一个新的
merchantSubscriptionId重建。应先使用原商户订阅 ID 查询订阅,确认是否已经创建成功,再决定是否重试。
步骤 2:引导买家完成首期授权与支付
创建订阅后,商户应根据接入模式继续完成首期支付:
- 收银台:将返回的
paymentUrl、innerJsUrl或token用于前端打开订阅收银台,由买家在 PingPong 页面完成首期支付或授权。 API Only:若同步响应返回action、跳转地址或其他后续动作,商户应继续引导买家完成 3DS 挑战或钱包授权绑定。
处理建议:
- 不要仅根据前端跳转完成就开通服务。
redirectUrl只是买家完成支付流程后的跳转地址,不代表订阅一定已经生效。- 如果买家中途退出、挑战失败或支付失败,订阅可能保持
PENDING或首期支付失败,商户不应提前授予订阅权益。
步骤 3:获取订阅结果和支付结果
订阅场景需要同时消费三类结果,分别回答三个不同的问题:
| 结果 | 回答的问题 | 订阅方式 | 建议幂等键 |
|---|---|---|---|
| 订阅结果 | 订阅当前是否生效、能否继续提供服务 | 订阅通知 | subscriptionId + notifyType + updateAt |
| 支付结果 | 首期或某一期扣款是否成功、扣了多少 | 支付通知 | transactionId |
| 退款结果 | Update 或 Cancel 触发的退款是否完成 | 退款通知 | merchantRefundId |
服务开通以订阅结果为准;支付结果用于对账,退款结果用于资金确认。
接入顺序建议:
- 必接 订阅通知,按 通用异步通知接入说明 完成地址配置、验签、幂等和 ACK。
- 推荐同时接收 支付通知;涉及退款时再接收 退款通知。
- 通知延迟、丢失或需补偿时,用 查询订阅详情 拉订阅状态,用 查询订阅支付记录 拉每期支付结果。
各通知的字段含义(notifyType、status、currentPeriod、merchantTransactionId 等)请见对应通知参考页。
步骤 4:管理续费、补扣与计划变更
首期生效后,PingPong 会根据订阅计划自动推进后续续费、试用转正和计划变更。商户侧建议始终分两条线处理:
| 处理层 | 要回答的问题 | 推荐关注字段 | 推荐获取方式 |
|---|---|---|---|
| 订阅层 | 这个订阅现在还能不能继续给服务 | notifyType、status、currentPeriod、cancelReason | 订阅通知 + 查询订阅详情 |
| 支付层 | 这一期有没有实际扣款成功、是否发生补扣或退款 | paymentRecords、merchantTransactionId、transactionId、amount、currency、status | 支付通知 + 查询订阅支付记录 |
1. 处理续费与补扣
每个计费周期到期时,PingPong 会按订阅计划自动发起续费。续费失败并开启 autoRecovery.enabled=true 时,订阅可能进入 PAST_DUE,商户应结合订阅状态、支付记录和自身宽限期策略决定是否继续提供服务。
更多续费失败、自动重试、补扣和查询建议,请查看 续费与自动恢复。
2. 查询订阅计划与支付记录
如果您需要判断用户是否继续享有订阅权益,优先看订阅状态;如果需要确认某一期资金结果,优先看支付记录和通知。
3. 预览并执行计划变更
需要升级/降级套餐、修改金额、调整周期或变更商品信息时,建议先调用 预览订阅更新 预估补扣或退款,再调用 更新订阅 正式提交变更。
通过收银台创建的订阅,若变更产生的补扣需要买家继续支付,Update 响应会返回 action.paymentRedirectUrl 收银台地址,商户需将买家重定向到该地址完成支付,详见 Update 与 Cancel 规则 · 收银台订阅的补扣跳转支付。
计划变更涉及 effectiveMode、billingAction、prorationMode 组合,不同组合会影响生效时间、账单锚点、补扣和退款。详细规则请查看 Update 与 Cancel 规则。
4. Update 与 Cancel 的关系
如果订阅计划存在未完成或已完成的 Update,Cancel 是否允许执行会受到 Update 状态和新周期开始时间影响。即使 cancelAtPeriodEnd=true 表示周期末取消,也不能绕过 Update 门禁。
完整门禁、立即取消/周期末取消、Update 与 Cancel 各自 prorationMode 的关系,请查看 Update 与 Cancel 规则。
5. Invoice 对账
每笔扣款成功后 PingPong 会生成票据(invoice)和支付凭证(receipt):
- invoiceId 获取:支付通知(
paymentNotifyUrl)的报文中携带invoiceId字段; - 票据查询:用 票据详情 按
invoiceId查询金额、状态、客户信息; - 票据下载:用 票据下载 获取 PDF 下载链接(30 天有效);
- 凭证查询:用 凭证详情 按
receiptId查询(receiptId从 凭证创建通知 获取); - 凭证下载:用 凭证下载 获取 PDF 下载链接。
详细对账指引和票据节奏请查看 Invoice 对账。
下一步阅读
完成集成主流程后,各专题的深入规则请返回 Subscription 概览 查看完整阅读指引(订阅状态与通知、续费与自动恢复、Update 与 Cancel 规则、场景与最佳实践)。
接入检查清单
上线前建议确认:
- 已保存
merchantSubscriptionId、subscriptionId、customerId、订阅状态、当前周期、金额币种和最近一次事件信息。 - 已分别处理订阅通知、支付通知和退款通知,并按各自维度做幂等。
- 已准备通知延迟或丢失时的补偿查询逻辑。
- 已明确
PAST_DUE、试用转正失败、周期末取消和立即取消时的用户权益处理规则。 - 已向用户展示订阅周期、续费金额、试用规则、取消入口和必要的扣款提醒。
