payin商户操作手册

最新文章

Stripe 测试时钟：分步推进模拟，不把通过当作真实收款保证

建立可丢弃的账单模拟，遵守冻结时间推进上限，等待就绪，排查观察缺失，并在清理前保留证据，明确真实支付边界。

发布日期及来源核查日期：

Stripe Billing 沙盒中采用第一版客户对象的测试时钟生命周期：时间推进、异步就绪、观察边界与清理。不讨论真实试用策略、账单锚点配方、待处理升级、第二版账户对象、通用限流优化或发票导出。

模拟时间经过，不要为了加速而改写收费规则

一则公开开发者提问反映了实际困难：订阅周期只能按日、周、月或年配置，今天创建的订阅计划如何立即验证？提问者尝试修改试用参数，却得到了难以理解的发票结果。[5] 这说明需要把时间模拟与商业配置分开，而不是为了让测试尽快结束就改变实际收费规则。社区问题只能证明有人遇到这种需求，不能代替当前接口说明。

Stripe 测试时钟从指定的冻结时间开始，创建后只能向前推进，不能倒退。[1] 本文讨论模拟环境的建立、推进边界、等待条件、观察结果和清理，不重复试用结束策略、账单锚点或待付款升级的配置方案。以下流程属于基于官方文档的编辑建议，不是已经执行的 Stripe 测试，也不表示 PayIn 提供这些功能。

先建立隔离且可以丢弃的场景

Stripe 建议新集成使用普通沙盒，而不是测试模式沙盒，因为普通沙盒可以隔离正式环境的设置和数据；测试模式沙盒则会与正式环境共享部分设置，在控制台修改它们可能影响正式环境。[4] 必须确认应用真正使用的密钥：在控制台切换到沙盒，并不会自动改变代码中的接口密钥。[4]

  1. 先写明要验证的断言：在哪个模拟时间边界，应看到哪项订阅或发票状态，以及应用应完成什么处理。记录账户环境、接口版本、收费周期和预期结果。
  2. 通过 POST /v1/test_helpers/test_clocks 创建时钟，传入初始 frozen_time 时间戳和便于识别的名称，保存返回的标识符。[1]
  3. 本文采用第一版客户对象路径：创建一个可丢弃的客户，把 test_clock 设为时钟标识符，再为该客户创建订阅。订阅通过客户继承时钟关联，不需要在创建订阅时再次传入时钟标识符。[1]
  4. 根据场景使用官方测试支付方式；如果测试目标就是未提供支付方式，则有意不添加。[1] 建议为不相关的测试分别建立对象，明确谁负责最终删除。

目前每个模拟最多容纳三个客户；每个客户最多三个订阅，包括计划订阅；每个模拟最多十个未关联客户的报价。[1] 因此它适合小范围生命周期验证，不应被当作大规模用户群体测试。

不要沿用旧社区回答，把“不能使用已有客户”当作永久规则。当前文档允许为符合条件的已有客户创建时钟，但要求对象数量不超限、初始时间不能在过去，而且账户不能配置自动化流程；客户一旦加入时钟便不能移出。[1] 编辑建议优先创建可丢弃的新客户，不要仅为复用测试数据而删除账户自动化配置。

按允许的跨度推进，再等待处理完成

推进目标必须晚于当前 frozen_time；一次推进不能超过该时钟中最短订阅周期的两个周期。[2] 例如，月度订阅一次最多推进两个月；操作指南进一步说明，没有订阅或订阅计划时，可以推进到初始冻结时间之后两年以内。[1] 不要把空时钟的例外理解为能够反复跳跃两年、无限扩展范围。

假设同一时钟同时关联月度订阅和年度订阅，就应按照月度周期规划推进步骤，而不是直接跳到年度续订日。这只是对最短周期规则的说明，不是本文执行过的测试结果。[2] 建议把长期场景拆成多个检查点，每到一个检查点都保存实际观察，避免只检查最终状态而遗漏中间变化。

  1. 读取时钟和当前测试配置，选定下一个合法目标时间。
  2. 向 POST /v1/test_helpers/test_clocks/{id}/advance 提交目标 frozen_time。请求成功返回的状态是 advancing，不等于所有推进工作已经完成。[2]
  3. 等待 test_helpers.test_clock.ready 事件，或者按标识符读取时钟并检查 status；Stripe 也会发出 test_helpers.test_clock.advancing 事件。[1]
  4. 确认 ready 后，再检查订阅、发票以及应用自身的处理结果，最后决定是否继续推进。该状态的官方含义只是关联对象已经推进到冻结时间，并不代表你自己的外部任务队列已经处理完毕。[3]

建议明确三个分支：仍为 advancing 时，采用有总等待上限的轮询；本地等待超时时，保留标识符并调查，不立即宣布成功或失败；出现 internal_failure 时，停止继续推进该时钟，因为官方说明后续推进请求也会失败。[3] 保存诊断证据后，再重建可丢弃的场景。这里没有宣称任何通用轮询间隔或完成时限。

观察不到结果时，先检查查询范围

未加筛选条件的列表可能造成误判。Stripe 说明，列表接口默认可能不返回测试时钟生成的对象，需要提供适当的查询条件，具体参数因资源而异。[1] 因此，建议先按已知标识符读取对象，或者使用对应的客户、订阅或时钟筛选条件，不要因为全量列表没有发票，就断定发票从未生成。这是模拟对象的可见性检查，不是发票批量导出教程。

在同一个冻结时间内多次更新订阅，也可能触发限流，因为请求都会计入那个模拟时间。Stripe 建议在继续请求之前，先把模拟时间推进几分钟。[1] 如果这几分钟会越过你正在验证的边界，应保留失败现场并重新设计测试，而不是悄悄改变时间，再把不同条件下的结果写成原断言通过。

模拟成功不等于真实收款成功

银行扣款尤其容易造成误解：时钟推进过程目前不支持收取这类付款，包括 us_bank_account；Stripe 会在推进之后处理收款。官方失败案例中，推进后订阅可能仍为 active，因为推进过程中没有尝试收款。[1] 必须继续观察后续发票和订阅事件，不能把时钟就绪或订阅有效当作银行扣款成功。

更根本的边界是，沙盒只创建模拟对象，不转移真实资金，也不由银行或卡组织处理真实付款。[4] 一次通过的模拟可以支持“在所测试的配置下，观察到某种状态和处理结果”，却不能证明未来真实授权、结算或客户银行处理必然成功。正式上线准备、账户资格和支付方式支持应另行确认；也不应为了让测试报告更有说服力，就拿真实客户付款随意试验。

建议把测试报告分成两部分：一部分列出确实观察到的模拟状态、事件和应用处理；另一部分列出尚未覆盖的真实支付链路及负责人。没有覆盖的内容应明确写出，不能用一句“整个生命周期已验证”把范围边界掩盖掉。这是报告方法建议，不是平台提供的自动认证。

先保存证据，再进行破坏性清理

建议保存时钟与对象标识符、起始和目标时间戳、实际状态、相关事件及断言结果，再执行删除。结果可以标为已观察、失败、等待超时或不受模拟支持，便于后来复查。这些只是推荐分类，并非本文已经取得的账户测试结果。

Stripe 文档说明模拟会在创建三十天后自动删除；时钟对象中的 deletes_after 表示计划自动删除的时间戳。[1][3] 使用 DELETE /v1/test_helpers/test_clocks/{id} 手动删除，会删除关联的测试客户并取消其订阅。[1] 不要让其他测试依赖即将被清理的共享对象，也不要把模拟时间推进与证据保留期限混为一谈。

来源与日期

检索与核对日期：2026年9月23日。所取得的来源正文未注明发布日期或更新日期；检索日期不是发布日期。官方文档用于支持技术行为，公开问题仅用于说明实际需求。来源不能证明全球各地均可使用相关功能，账户、产品和支付方式的适用范围须另行确认。本文仅为文档研究，未进行经过身份验证的接口测试或真实付款测试。

更多指南