如何通过 Braintree API 设置 Billing Cycles 数量？

2026-10-24支付小周

结论

正确的参数名是 numberOfBillingCycles，不是 billingCycles。周期数应传入整数：

'numberOfBillingCycles' => 7

这表示该 subscription 最多执行 7 个 billing cycles。每个 billing cycle 的时长仍由 Plan 的 billing frequency 决定。例如，按月计费的 Plan 执行 7 个周期，通常就是连续计费 7 个月。

修改后的代码

旧版 Braintree PHP SDK 可以这样写：

$result = Braintree_Subscription::create([
    'paymentMethodToken' => $payment_method_token,
    'planId' => 'r45g',
    'price' => $_SESSION['enroll-draft-amount'],
    'numberOfBillingCycles' => 7,
]);

if ($result->success) {
    $subscription = $result->subscription;
} else {
    foreach ($result->errors->deepAll() as $error) {
        echo $error->code . ': ' . $error->message . PHP_EOL;
    }
}

使用较新的命名空间 SDK 时，通常通过 Braintree\Gateway 创建：

$result = $gateway->subscription()->create([
    'paymentMethodToken' => $payment_method_token,
    'planId' => 'r45g',
    'price' => $_SESSION['enroll-draft-amount'],
    'numberOfBillingCycles' => 7,
]);

if (!$result->success) {
    foreach ($result->errors->deepAll() as $error) {
        echo $error->code . ': ' . $error->message . PHP_EOL;
    }
}

原因

billingCycles 不是 subscription 创建请求中用来控制周期数量的字段，所以不会得到预期结果。Braintree 使用的字段名是：

numberOfBillingCycles

其中的 number 不能省略。

numberOfBillingCycles 控制的是计费次数，不是每个周期的时长。周期时长取决于 planId 对应的 Plan，不能通过这个字段改为按周、按月或按年计费。

注意事项

周期数应传入整数 7，不要使用字符串 '7'。
price 可以覆盖 Plan 的订阅价格，但应先校验并规范化会话中的金额，避免直接使用未经验证的输入。
如果设置了 trial，trial 是否计入 billing cycles，以及首次扣款的时间，应以当前使用的 Braintree SDK 和网关规则为准。
务必检查 $result->success 和 $result->errors。请求失败时，错误信息通常会指出字段冲突、取值范围或 Plan 配置问题。
不同版本的 Braintree PHP SDK 可能使用不同的调用入口，但请求字段仍是 numberOfBillingCycles。如果当前 SDK 无法识别该字段，需要核对所安装版本对应的 Subscription API 文档。