如何在Stripe的invoice.payment_succeeded事件中关联创建Checkout Session时保存的唯一ID

阿华AIGC实验室

2026-4-20

我来帮你搞定这个关联问题！其实Stripe提供了几种实用的方式，能让你把Checkout Session阶段的自定义标识传递到后续的invoice相关事件里，下面结合你的代码场景给出具体方案：

方案一：利用Subscription Metadata传递自定义标识（最推荐）

你代码里已经用了setClientReferenceId(transaction.getTransactionId())，但这个字段不会直接出现在invoice.payment_succeeded事件里。不过我们可以在创建Checkout Session时，把你的transaction ID放到Subscription的Metadata里——因为每个Invoice都会关联对应的Subscription，这样后续所有周期的Invoice事件都能拿到这个标识。

修改你创建Session的代码，添加subscription_data.metadata的设置：

SessionCreateParams params = new SessionCreateParams.Builder()
    .setSuccessUrl("https://example.com/success.html?session_id={CHECKOUT_SESSION_ID}")
    .setCancelUrl("https://example.com/canceled.html")
    .setMode(SessionCreateParams.Mode.SUBSCRIPTION)
    .setClientReferenceId(transaction.getTransactionId())
    // 新增：把transaction ID存入Subscription的元数据
    .setSubscriptionData(
        new SessionCreateParams.SubscriptionData.Builder()
            .putMetadata("transaction_id", transaction.getTransactionId())
            .build()
    )
    .addLineItem(new SessionCreateParams.LineItem.Builder()
        .setQuantity(1L)
        .setPrice(priceId)
        .build()
    )
    .build();

处理invoice.payment_succeeded事件时的步骤：

解析事件对象，拿到Invoice实例
从Invoice中获取关联的subscription字段（即Subscription ID）
调用Stripe的API查询该Subscription详情：Subscription.retrieve(subscriptionId)
从Subscription的metadata里取出transaction_id，就能关联到你数据库里的交易记录了

方案二：提前存储Checkout Session与Subscription的映射

在checkout.session.completed事件中，你可以拿到Checkout Session对应的Subscription ID，这时把它和你之前保存的Session ID/transaction ID做映射存储到数据库里。

处理checkout.session.completed事件的示例代码：

// 解析事件得到Checkout Session对象
Session session = (Session) event.getDataObjectDeserializer().getObject().get();
String transactionId = session.getClientReferenceId();
String subscriptionId = session.getSubscription();
// 将transactionId与subscriptionId的映射关系存入数据库

之后处理invoice.payment_succeeded事件时，直接从Invoice里拿到subscriptionId，查数据库就能找到对应的transaction ID，不需要额外调用Stripe API，效率更高。