Stripe PHP发票开发：如何传入自定义特定参数（如课程金额）

嘿，看你是在给学校器乐课做Stripe发票生成功能对吧？金额随机构费率和分组变化的需求确实很常见，我来帮你捋捋怎么把这些自定义参数（比如课程金额、孩子信息这些）正确传入Stripe的发票流程里～

首先，你的代码框架已经有了核心思路：先获取/创建客户，再处理发票。接下来需要把课程相关的自定义参数（比如单课费用、课量、孩子姓名、乐器类型）融入到Stripe的发票项和发票中，具体可以这么做：

1. 先处理金额计算（关键！） #

Stripe的金额参数要求用最小货币单位（比如美元是分，人民币是分），所以首先要把你的$cost（单课费用）和$lessonCount（课量）转换成符合要求的格式，比如：

// 假设$cost是人民币“元”，转换为“分”需要乘以100
$totalAmount = $cost * $lessonCount * 100;

如果你的$cost已经是最小单位了，直接相乘就行，不用额外乘倍数。

2. 用Metadata存储自定义参数 #

Stripe的大多数对象（客户、发票项、发票）都支持metadata字段，用来存储自定义的业务信息，比如孩子姓名、乐器类型、分组这些，既方便你在Stripe后台查看，也能后续做数据核对。

3. 完整的示例代码 #

我补全你的函数，把自定义参数都整合进去：

function createStripeLessonInvoice($parentName, $email, $childName, $instrument, $grouping, $cost, $lessonCount) {
    \Stripe\Stripe::setApiKey('sk_test_[MYKEY]');

    try {
        // 获取或创建客户，同时把孩子信息存入客户元数据
        $customer = getOrCreateStripeCustomer($email, $parentName, null, $childName);

        // 计算总金额（根据你的货币调整最小单位倍数）
        $totalAmount = $cost * $lessonCount * 100; 
        $currency = 'cny'; // 换成你实际用的货币，比如usd

        // 创建发票项：关联客户，设置金额、描述，同时存入课程自定义参数
        $invoiceItem = \Stripe\InvoiceItem::create([
            'customer' => $customer->id,
            'amount' => $totalAmount,
            'currency' => $currency,
            'description' => "{$lessonCount}节{$instrument}课程（{$grouping}分组）",
            'metadata' => [
                'child_name' => $childName,
                'instrument_type' => $instrument,
                'grouping_type' => $grouping,
                'single_lesson_cost' => $cost,
                'total_lessons' => $lessonCount
            ]
        ]);

        // 创建发票，设置收款方式和到期时间，也可以加全局元数据
        $invoice = \Stripe\Invoice::create([
            'customer' => $customer->id,
            'collection_method' => 'send_invoice', // 自动发送发票给客户邮箱
            'days_until_due' => 7, // 发票7天后到期
            'metadata' => [
                'course_category' => 'school_instrumental_lesson'
            ]
        ]);

        // 手动触发发票发送（如果上面设置了send_invoice，也会自动发送，这里做双重保障）
        $invoice->sendInvoice();

        return $invoice;
    } catch (\Stripe\Exception\ApiErrorException $e) {
        // 捕获Stripe API错误，记录日志或者返回错误信息
        error_log('Stripe发票创建失败：' . $e->getMessage());
        return false;
    }
}

// 补全你的getOrCreateStripeCustomer函数，加入自定义元数据
function getOrCreateStripeCustomer($email, $name, $phone = null, $childName = null) {
    $existingCustomers = \Stripe\Customer::all(['email' => $email]);
    if (!empty($existingCustomers->data)) {
        // 如果客户已存在，更新元数据（比如更新孩子信息）
        $customer = $existingCustomers->data[0];
        $customer->metadata->child_name = $childName;
        $customer->save();
        return $customer;
    } else {
        // 创建新客户，同时存入家长和孩子信息
        return \Stripe\Customer::create([
            'email' => $email,
            'name' => $parentName,
            'phone' => $phone,
            'metadata' => [
                'child_name' => $childName
            ]
        ]);
    }
}

几个重要的小提示 #

• 发票描述要清晰：把课程信息写在description里，客户收到的发票邮件里会直接显示，避免混淆。
• 错误处理不能少：Stripe API调用可能因为网络、参数错误等失败，一定要捕获异常，避免程序崩溃。
• 多课程场景：如果一个家长有多个孩子的课程，可以循环创建多个InvoiceItem，然后再生成一张包含所有项的发票。

备注：内容来源于stack exchange，提问作者Chris McCartney