如何配置Stripe PaymentElement以实现卡片保存功能

a) 移除PaymentElement的额外字段 #

你可以在创建PaymentElement时通过fields配置项精准控制显示的字段，把不需要的字段设为never即可隐藏。比如针对账单地址类的多余字段，修改代码如下：

const paymentElement = elements.create("payment", {
  fields: {
    billingDetails: {
      address: {
        country: "never", // 隐藏国家字段
        postalCode: "never", // 隐藏邮编字段
        // 其他不需要的字段如city、line1等，同理设置为"never"
      },
    },
  },
});

可根据实际需要调整字段的配置值（never/auto/always），实现对显示内容的精确控制。

b) 添加持卡人姓名字段 #

有两种实用的实现方式：

方式1：让PaymentElement自带姓名输入框 #

直接在创建PaymentElement时配置billingDetails.name为always，Element会自动渲染姓名输入框：

const paymentElement = elements.create("payment", {
  fields: {
    billingDetails: {
      name: "always", // 强制显示持卡人姓名输入框
    },
  },
});

方式2：自定义姓名输入框 #

如果需要自定义样式，可在页面添加独立的输入框，再在确认时把姓名传入接口：

<!-- 页面中添加自定义姓名输入 -->
<div id="payment-form">
  <div>
    <label>持卡人姓名</label>
    <input type="text" id="card-holder-name" />
  </div>
  <div id="payment-element"></div>
  <div id="payment-message"></div>
</div>

const confirmSetup = async() => {
  const cardHolderName = document.getElementById('card-holder-name')?.value;
  const result = await stripe.confirmSetup({
    elements,
    redirect: "if_required",
    payment_method_data: {
      billing_details: {
        name: cardHolderName,
      },
    },
  });
}

c) 避免重复添加卡片 #

方案1：利用错误提示处理（简单易实现） #

Stripe在尝试绑定已存在的卡片时，会返回payment_method_already_attached错误，你可以在confirmSetup后捕获该错误并提示用户：

const confirmSetup = async() => {
    const result = await stripe.confirmSetup({
        elements,
        redirect: "if_required"
    });

    if (result.error) {
      if (result.error.code === 'payment_method_already_attached') {
        document.getElementById('payment-message').textContent = '该卡片已绑定到您的账户';
      } else {
        document.getElementById('payment-message').textContent = result.error.message;
      }
    } else {
      // 绑定成功后的逻辑
      document.getElementById('payment-message').textContent = '卡片绑定成功';
    }
}

方案2：提前获取客户已有卡片（需后端配合） #

页面加载时，通过后端调用Stripe的Customers List Payment Methods接口，获取该客户已绑定的卡片信息（如后四位卡号、卡组织），前端展示这些卡片供用户选择，同时避免重复添加。如果用户选择添加新卡，再走后续绑定流程。

修改后的完整代码示例 #

<script setup lang="ts">
let setupIntent = getSetupIntent(stripeCustomerId);
const appearance = {
    theme: 'stripe',
};

const options = {
    clientSecret: setupIntent.clientsecret,
    appearance,
};

elements = stripe.elements(options);
// 配置字段显示/隐藏+添加姓名输入
const paymentElement = elements.create("payment", {
  fields: {
    billingDetails: {
      name: "always",
      address: {
        country: "never",
        postalCode: "never",
      },
    },
  },
});
paymentElement.mount("#payment-element"); 

const confirmSetup = async() => {
    const result = await stripe.confirmSetup({
        elements,
        redirect: "if_required"
    });

    if (result.error) {
      if (result.error.code === 'payment_method_already_attached') {
        document.getElementById('payment-message').textContent = '该卡片已绑定到您的账户';
      } else {
        document.getElementById('payment-message').textContent = result.error.message;
      }
    } else {
      // 绑定成功后的逻辑
      document.getElementById('payment-message').textContent = '卡片绑定成功';
    }
}
</script>

<html>
<div>
    <form id="payment-form">
        <div id="payment-element"></div>
        <div id="payment-message"></div>
    </form>
    <button onclick="confirmSetup()">提交</button>
</div>
</html>

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