如何在Stripe支付流程中为订单项添加自定义备注字段？

针对你需要给Stripe订单项添加自定义备注并同步到发票的需求，有以下几种可行方案：

1. 利用订单项的Metadata字段存储备注（推荐） #

Stripe的SessionLineItemOptions支持Metadata字典，可用来存储结构化的自定义信息。后续通过配置Stripe后台，能让这些元数据直接显示在发票上。

后端C#代码示例 #

// 定义购物车条目模型，包含商品价格ID、数量和归属信息
public class CartItem
{
    public string PriceId { get; set; }
    public int Quantity { get; set; }
    public string Recipient { get; set; }
}

// 创建Stripe结账会话时，给每个订单项添加元数据
var checkoutOptions = new SessionCreateOptions
{
    PaymentMethodTypes = new List<string> { "card" },
    Mode = "payment",
    SuccessUrl = "https://your-domain.com/success",
    CancelUrl = "https://your-domain.com/cancel",
    LineItems = new List<SessionLineItemOptions>()
};

// 假设从前端接收的购物车数据
var userCartItems = new List<CartItem>
{
    new CartItem { PriceId = "price_xxxx", Quantity = 1, Recipient = "Alice" },
    new CartItem { PriceId = "price_xxxx", Quantity = 1, Recipient = "Bob" },
    new CartItem { PriceId = "price_xxxx", Quantity = 1, Recipient = "Charlie" }
};

foreach (var item in userCartItems)
{
    checkoutOptions.LineItems.Add(new SessionLineItemOptions
    {
        Price = item.PriceId,
        Quantity = item.Quantity,
        Metadata = new Dictionary<string, string>
        {
            { "归属人", item.Recipient }
        }
    });
}

var sessionService = new SessionService();
var session = sessionService.Create(checkoutOptions);

配置发票显示元数据 #

登录Stripe后台，进入设置 > 发票 > 发票内容，勾选「显示行项目元数据」，这样备注信息就会自动出现在顾客收到的发票对应订单项下方。

2. 修改订单项的Description字段嵌入备注 #

如果希望备注直接显示在结账页面和发票的订单项描述中，可以直接拼接自定义信息到Description字段，无需依赖元数据设置。

代码示例 #

foreach (var item in userCartItems)
{
    checkoutOptions.LineItems.Add(new SessionLineItemOptions
    {
        Price = item.PriceId,
        Quantity = item.Quantity,
        Description = $"香蕉 - 归属人: {item.Recipient}"
    });
}

这种方式的优点是直观，顾客在结账时就能看到备注；缺点是会覆盖商品默认的描述，需要自行合并原有描述和自定义备注。

3. 通过Webhook同步备注到发票（灵活扩展） #

如果需要更复杂的逻辑（比如付款后再调整发票内容），可以监听Stripe的checkout.session.completed webhook事件，在付款完成后更新发票的订单项信息。

Webhook处理代码示例 #

// 解析Stripe webhook事件
var stripeEvent = EventUtility.ParseEvent(requestBody);

if (stripeEvent.Type == Events.CheckoutSessionCompleted)
{
    var session = stripeEvent.Data.Object as Session;
    var invoiceService = new InvoiceService();
    var invoice = invoiceService.Get(session.InvoiceId);

    // 遍历发票订单项，从会话订单项中获取元数据并更新发票
    foreach (var invoiceLineItem in invoice.LineItems.Data)
    {
        var sessionLineItem = session.LineItems.Data.First(li => li.Id == invoiceLineItem.Id);
        if (sessionLineItem.Metadata.TryGetValue("归属人", out var recipient))
        {
            var updateLineOptions = new InvoiceLineItemUpdateOptions
            {
                Description = $"{invoiceLineItem.Description} - 归属人: {recipient}"
            };
            invoiceService.UpdateLineItem(invoice.Id, invoiceLineItem.Id, updateLineOptions);
        }
    }

    // 重新生成并发送发票
    invoiceService.FinalizeInvoice(invoice.Id);
}

前端React部分的配合 #

在购物车页面给每个商品条目添加输入框，收集用户输入的归属信息，提交订单时将这些数据一并传给后端：

function Cart({ cartItems, updateCartItemRecipient }) {
    return (
        <div className="cart">
            {cartItems.map((item, idx) => (
                <div key={idx} className="cart-item">
                    <span>{item.name} × {item.quantity}</span>
                    <input
                        type="text"
                        placeholder="输入归属人"
                        value={item.recipient || ""}
                        onChange={(e) => updateCartItemRecipient(idx, e.target.value)}
                    />
                </div>
            ))}
            <button onClick={submitOrder}>提交订单</button>
        </div>
    );
}

注意事项 #

• 同一个商品如果要分配给多个用户，建议拆分为多个数量为1的订单项，这样每个备注可以对应单独的条目，更清晰。
• Stripe元数据的每个字段最多支持500字符，避免过长的备注内容。

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