如何通过Stripe一次性支付为Firebase添加自定义声明？

核心问题在于一次性支付和订阅场景触发的Stripe Webhook事件不同，订阅场景的事件会自动关联用户元数据，但一次性支付需要你主动传递用户标识并监听正确的事件来处理。以下是具体解决步骤：

1. 支付流程中传递Firebase UID到Stripe Metadata #

不管用Stripe Checkout还是直接创建PaymentIntent，都要在创建资源时把用户的Firebase UID塞进metadata里。比如Checkout Session的示例：

// 后端创建Stripe Checkout Session
const stripe = require('stripe')('你的Stripe密钥');

exports.createCheckoutSession = async (req, res) => {
  const { firebaseUid } = req.body; // 从前端获取当前用户的Firebase UID

  const session = await stripe.checkout.sessions.create({
    payment_method_types: ['card'],
    line_items: [
      {
        price: '你的一次性商品价格ID',
        quantity: 1,
      },
    ],
    mode: 'payment',
    success_url: 'https://你的域名/success',
    cancel_url: 'https://你的域名/cancel',
    metadata: {
      firebase_uid: firebaseUid // 关键：传递Firebase用户ID
    },
  });

  res.json({ id: session.id });
};

2. 在Firebase Cloud Functions中监听正确的Stripe Webhook事件 #

一次性支付成功后，Stripe会触发checkout.session.completed或者payment_intent.succeeded事件，你需要在Cloud Functions里监听这个事件，解析metadata并设置自定义声明：

const functions = require('firebase-functions');
const admin = require('firebase-admin');
const stripe = require('stripe')('你的Stripe密钥');

admin.initializeApp();

// 监听Stripe Webhook事件
exports.handleStripePayment = functions.https.onRequest(async (req, res) => {
  const sig = req.headers['stripe-signature'];
  const webhookSecret = '你的Stripe Webhook密钥';

  let event;
  try {
    event = stripe.webhooks.constructEvent(req.rawBody, sig, webhookSecret);
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // 处理一次性支付完成事件
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    const firebaseUid = session.metadata.firebase_uid;

    if (firebaseUid) {
      // 设置Firebase自定义声明
      await admin.auth().setCustomUserClaims(firebaseUid, {
        paid: true, // 替换成你需要的自定义声明
        purchaseDate: new Date().toISOString()
      });
      functions.logger.log(`成功为用户 ${firebaseUid} 设置自定义声明`);
    }
  }

  res.json({ received: true });
});

3. 排查常见问题 #

• Webhook事件监听错误：别用订阅相关的customer.subscription.updated，一定要用一次性支付对应的事件（checkout.session.completed或payment_intent.succeeded）
• Metadata未传递：检查创建Checkout Session/PaymentIntent时是否正确传入了firebase_uid，可以在Stripe后台的支付记录里查看metadata是否存在
• 权限问题：确保Cloud Functions的服务账号拥有Firebase Auth Admin权限（在Google Cloud IAM里配置）
• Webhook签名验证：必须正确配置Stripe Webhook的签名密钥，否则会解析失败导致后续流程无法执行

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