收款

安全地在线上收款。

制作支付表单或使用预构建的结账页面来开始接收线上付款。

使用 Stripe Elements 和 Checkout Sessions 在您的网站上构建一个结账页面，这是一种可管理税费、折扣、运费等内容的集成方式。

仅当您的任一钱包绑定了有效的卡时，演示中才会显示 Google Pay 或 Apple Pay。

设置服务器
服务器端

在开始之前，您需要注册一个 Stripe 账户。

用官方 Stripe 库从您的应用程序访问 API。

将 SDK 设置为至少使用 2025-03-31.basil API 版本。

创建一个 Checkout Session
服务器端

在服务器上添加一个终结点，用于创建 Checkout Session 并将其客户端私钥返回到前端。Checkout Session 表示您的客户在进行一次性付款或订阅时的会话。Checkout Sessions 创建后 24 小时过期。

设置前端
客户端

在您的结账页面包含 Stripe.js 脚本，方法是将其添加到您的 HTML 文件的 head。一定直接从 js.stripe.com 加载 Stripe.js，以保持 PCI 合规。请勿将脚本包含在捆绑包中，也不要自己托管其副本。

Ensure you’re on the latest Stripe.js version by including the following script tag <script src=“https://js.stripe.com/clover/stripe.js”></script>. Learn more about Stripe.js versioning.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

注意

Stripe 提供一个 npm 工具包，可用于将 Stripe.js 加载为模块。请参阅 GitHub 上的项目。需要 7.0.0 或更高版本。

初始化 stripe.js。

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
  'pk_test_TYooMQauvdEDq54NiTphI7jx'
,
);

发起结账
客户端

创建 clientSecret 承诺，解析为客户端密钥，或直接将其设置为密钥。调用 initCheckout，并传入 clientSecret。initCheckout 会返回一个解析为 Checkout 实例的承诺。

结账对象作为您的结账页面的基础，包含来自结账会话的数据和更新会话的方法。

actions.getSession() 返回的对象包含您的定价信息。我们建议在用户界面 (UI) 中读取并显示会话中的 total 和 lineItems。

该集成能让您通过最少的代码修改启用新功能。例如，若您显示总额，则添加手动货币定价，无需修改用户界面。

checkout.js
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.checkoutSessionClientSecret);
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
  const checkoutContainer = document.getElementById('checkout-container');
  checkoutContainer.append(JSON.stringify(session.lineItems, null, 2));
  checkoutContainer.append(document.createElement('br'));
  checkoutContainer.append(`Total: ${session.total.total.amount}`);
}

index.html
<div id="checkout-container"></div>

收集客户电子邮件地址
客户端

创建电子邮件输入以收集客户的电子邮件地址。当客户完成输入来验证并保存电子邮件地址时，调用 updateEmail。

根据您的结账表单的设计，可通过以下方式调用 updateEmail：

在提交付款之前。也可以调用 updateEmail 来提前验证，例如模糊输入。
在转到下一步之前，例如点击保存按钮（如果您的表单包含多个步骤）。

index.html
<input type="text" id="email" />
<div id="email-errors"></div>

checkout.js
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    actions.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
}

收集付款详情
客户端

用 Payment Element 在客户端收集支付信息。Payment Element 是一个预构建的 UI 组件，它简化了多种支付方式的收集支付详情的流程。

首先，创建一个容器 DOM 元素来挂载 Payment Element。然后使用 checkout.createPaymentElement 创建 Payment Element 的实例，并通过调用 element.mount 挂载它，提供 CSS 选择器或容器 DOM 元素。

index.html
<div id="payment-element"></div>

checkout.js
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

请参阅 Stripe.js文档以查看支持的选项。

您可以通过在前端初始化 Checkout 时传递 elementsOptions.appearance 来自定义所有 Element 的外观。

提交付款
客户端

渲染一个支付按钮，该按钮调用 confirm 从 checkout 实例提交付款。

index.html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>

checkout.js
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const button = document.getElementById('pay-button');
  const errors = document.getElementById('confirm-errors');
  button.addEventListener('click', () => {
    // Clear any validation errors
    errors.textContent = '';

    actions.confirm().then((result) => {
      if (result.type === 'error') {
        errors.textContent = result.error.message;
      }
    });
  });
}

测试您的集成应用

导航到您的结账页面。
使用下表中的支付方式填写付款详情。对于银行卡付款：
- 输入一个任意的未来日期作为有效期。
- 输入 3 位数 CVC 码。
- 输入账单地址邮编。
将付款提交至 Stripe。
前往管理平台，在交易页面上查找支付。如果您支付成功，就会在列表中看到它。
点击您的付款，查看更多详情，例如账单信息及已购商品列表。您可以此信息来履行订单。

卡号	场景	如何测试
	该卡付款成功，不需要验证。	使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。
	该卡付款时需要验证。	使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。
	该卡被拒绝，显示拒付代码，例如 `insufficient_funds`。	使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。
	银联卡的长度为 13-19 位。	使用信用卡号以及有效期和 CVC 和邮编填写我们的信用卡表单。

有关测试您的集成的更多信息，请参阅测试部分。

可选创建产品和价格

创建 Checkout Session 之前，您可以预先创建产品和价格。用“产品”表示不同的实物商品或服务等级，用“价格”表示每个产品的定价。

例如，您可以创建一个价格为 20 美元的 T 恤产品。这样即可在不更新相关产品详情的情况下更改和添加价格。使用 Stripe 管理平台或 API 均可创建产品和价格。详细了解产品和价格的运作原理。

API 仅要求有一个 name 即可创建 Product。Checkout 中显示您提供的产品的 name、description 和 images。

然后，创建一个 Price，定义产品的价格。这包括产品的费用及使用的币种。

您创建的每个定价都有一个 ID。创建 Checkout Session 时，请引用定价 ID 和数量。若您需以多种货币销售商品，请将您的定价 (Price) 设置为多币种。Checkout 会自动确定客户的本地货币并在 Price 支持的情况下显示该货币。

可选预填充客户数据
服务器端

如果您已经收集了客户的邮件地址并且想在 Checkout Session 中给他们预先填写，则创建 Checkout Session 时传递 customer_email。

可选保存支付方式详情

了解如何接受付款并保存客户的付款详情以供未来购物时使用。

可选侦听 Checkout Session 的变化

侦听 Checkout Session 的变化

您可以通过用 checkout.on 在 change 事件上添加事件监听器来侦听 Checkout Session 的变化。

checkout.js
checkout = stripe.initCheckout({
  clientSecret: promise,
  elementsOptions: { appearance },
});

checkout.on('change', (session) => {
  // Handle changes to the checkout session
});

可选收集账单地址和收货地址

收集账单地址

默认情况下，Checkout Session 通过 Payment Element 收集付款所需的最少账单信息。

使用 Billing Address Element

您可以使用 Billing Address Element 来收集完整的账单地址。

首先，创建 Checkout Session 时传递 billing_address_collection=required。

创建一个容器 DOM 元素来挂载 Billing Address Element。然后使用 checkout.createBillingAddressElement 创建 Billing Address Element 的实例，并通过调用 element.mount 挂载它，提供 CSS 选择器或容器 DOM 元素。

index.html
<div id="billing-address"></div>

checkout.js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.mount('#billing-address');

Billing Address Element 支持以下选项：

使用自定义表单

您可以构建自己的表单来收集账单地址。

如果您的结账页面在确认之前有独立的地址收集步骤，则在客户提交地址时调用 updateBillingAddress。
否则，当客户点击“支付”按钮时，您可以通过将 billingAddress 传入 confirm 来提交地址。

收集部分账单地址

要收集部分账单地址，例如仅国家/地区和邮编，请传递 billing_address_collection=auto。

收集部分账单地址时，必须手动收集地址。默认情况下，Payment Element 会自动收集付款所需的最少账单信息。为避免重复收集账单详情，请在创建 Payment Element 时传递 fields.billingDetails=never。如果您只打算收集一部分账单详情（例如客户姓名），则只为您打算自己收集的字段传递 never。

收集收货地址

要收集客户的收货地址，请在创建 Checkout Session 时传递 shipping_address_collection 参数。

收集收货地址时，还必须指定允许发货至的国家/地区。用两字母 ISO 国家/地区代码组成的数组配置 allowed_countries 属性。

如何使用 Shipping Address Element

您可以用 Shipping Address Element 收集完整的收货地址。

创建一个容器 DOM 元素来挂载 Shipping Address Element。然后使用 checkout.createShippingAddressElement 创建 Shipping Address Element 的实例，并通过调用 element.mount 挂载它，提供 CSS 选择器或容器 DOM 元素。

index.html
<div id="shipping-address"></div>

checkout.js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address');

Shipping Address Element 支持以下选项：

侦听 Checkout Session 的变化

您可以通过添加事件侦听器来处理与地址相关的更改，从而侦听 Checkout Session 的更改。

使用 Session 对象在结账表单中呈现运费金额。

index.html
<div>
  <h3> Totals </h3>
  <div id="subtotal" ></div>
  <div id="shipping" ></div>
  <div id="total" ></div>
</div>

checkout.js
const checkout = stripe.initCheckout({clientSecret});
const subtotal = document.getElementById('subtotal');
const shipping = document.getElementById('shipping');
const total = document.getElementById('total');

checkout.on('change', (session) => {
  subtotal.textContent = `Subtotal: ${session.total.subtotal.amount}`;
  shipping.textContent = `Shipping: ${session.total.shippingRate.amount}`;
  total.textContent = `Total: ${session.total.total.amount}`;
});

使用自定义表单

您可以构建自己的表单来收集收货地址。

如果您的结账页面在确认之前有独立的地址收集步骤，则在客户提交地址时调用 updateShippingAddress。
否则，当客户点击“支付”按钮时，您可以通过将 shippingAddress 传入 confirm 来提交地址。

可选单独授权和捕获
服务器端

Stripe 支持银行卡两步验证付款，因此您可以先对银行卡进行授权，然后稍后再捕获。当 Stripe 授权付款时，发卡行为客户卡上的资金提供担保并冻结客户卡上的付款金额。然后您会有一定的时间来捕获资金，具体取决于银行卡)。如果您在授权过期之前不捕获付款，则付款会被取消，并且发卡行释放扣留的资金。

如果在确认客户能够支付与向其收款这两项操作之间还需要其他操作，则将授权与捕获分离开来是非常有帮助的。例如，如果您销售的产品库存有限，则需要确认客户用 Checkout 购买的商品仍然有货，然后才能捕获他们的付款并履行订单。通过以下流程实现：

确认 Stripe 已授权客户的支付方式。
查阅库存管理系统，确认那件商品是否有货。
更新您的库存管理系统，指示客户未购买那件商品。
捕获客户的付款。
在确认页面通知客户他们是否购买成功。

要表明您想单独授权和捕获，必须在创建 Checkout Session 时将 payment_intent_data.capture_method 的值设置为 manual。这样可指示 Stripe 仅授权客户银行卡上的金额。

要捕获一笔未捕获的付款，可以用管理平台，也可以用 capture 端点。程序化地捕获付款必须访问 Checkout Session 过程中创建的 PaymentIntent，它可从 Session 对象获取。

可选客户账户管理
无代码

通过向您的客户门户分享链接，让您的客户管理他们自己的账户。客户门户允许客户用他们的电子邮件地址登录，以管理订阅、更新支付方式等。

可选订单履行

了解如何在客户付款时以编程方式获取通知。

收款

安全地在线上收款。

注意

侦听 Checkout Session 的变化

收集账单地址

使用 Billing Address Element

使用自定义表单

收集部分账单地址

收集收货地址

如何使用 Shipping Address Element

侦听 Checkout Session 的变化

使用自定义表单

另见