PayPal Payouts API沙盒测试与真实环境状态流转技术问询

我正在集成PayPal Payouts API，需测试并理解完整的付款流程。目前已在沙盒环境完成以下流程测试：

• 收款方无账户：状态流转为pending -> unclaimed -> successful
• 收款方有账户：状态流转为pending -> successful

针对无法在沙盒中测试的场景，以下是技术问题的具体解答：

1. 沙盒中测试onhold状态的付款流程 #

PayPal沙盒没有直接触发onhold的可视化开关，但可通过两种方式模拟：

• 使用官方预配置的沙盒商家账户：部分预设账户发起付款时，会自动触发资金保留机制，生成onhold状态的交易记录。
• 在API请求中添加标识：创建Payout时，在请求体的note字段中加入类似"high-risk transaction"的内容，沙盒系统会识别并将付款置为onhold状态。

2. 沙盒中测试blocked状态的付款流程 #

模拟blocked状态可通过两种方式实现：

• 配置受限沙盒收款方账户：在沙盒账户管理后台创建收款方账户时，将账户状态设置为"受限"，向该账户发起付款时，交易会直接被标记为blocked。
• 触发风控拦截规则：发起Payout时使用异常参数，比如超过沙盒风控阈值的大额金额、短时间内重复发起相同付款请求，沙盒风控系统会自动拦截并标记交易为blocked。

3. 状态流转路径及资金流向 #

onhold状态的触发路径 #

• 直接从pending流转：多数场景下，PayPal在付款初始审核阶段触发资金保留，直接将pending转为onhold。
• 从unclaimed流转：若收款方超过7天未认领付款，PayPal可能将未认领资金转为onhold，即pending -> unclaimed -> onhold。

blocked状态的触发路径 #

仅能从pending状态直接流转，因为blocked是交易被风控或系统直接拦截的结果，不会经过其他中间状态。

资金流向说明 #

• 进入pending/onhold状态时：付款方资金已被扣除，暂存于PayPal中转账户。
• 进入blocked状态时：若付款方式为余额，资金不会实际扣除；若为信用卡，资金会立即原路退回付款方账户。

4. onhold/blocked状态被拒绝后的流转 #

• onhold状态被拒绝：会流转至returned状态，资金退回付款方账户。
• blocked状态被拒绝：
  • 若资金未完成扣除，直接转为failed状态。
  • 若资金已扣除，会转为reversed状态，资金原路退回付款方。
• 注：refunded状态仅适用于已成功完成的付款后续发起退款操作的场景，与onhold/blocked的拒绝流程无关。

内容的提问来源于stack exchange，提问作者Kristijan