调至内容部分
创建账户
或
登录
Stripe 文档徽标
/
创建账户
登录

当客户用某种支付方式进行付款时，保存该支付方式

了解如何在确认 PaymentIntent 或 Checkout Session 时保存客户的支付方式。

注意

Checkout Sessions API 还支持在客户用它进行付款时保存支付方式。要了解更多，请查看我们的 Checkout Sessions API 指南。

用 Payment Intents API 保存购物时输入的付款详情。有几个用例：

  • 对客户的网上订单扣款并存储支付信息，用于以后的购物。
  • 发起一系列经常性付款中的第一笔付款。
  • 收取押金并存储详情，便于以后收取完整金额。

有卡交易

有卡交易（例如通过 Stripe Terminal 支付）使用不同的流程来保存支付方式。有关详情，请查看 Terminal 文档。

合规

在保存客户的支付详情时，您需要负责遵守所有适用的法律、法规和卡组织规则。如果您想要保存客户的支付方式以供将来使用，则通常会适用于这些要求，例如在结账流程中向他们显示客户的支付方式以供将来购物使用，或者在他们不主动使用您的网站或应用程序时向他们扣款。在您的网站或应用程序中添加条款，说明您计划如何保存支付方式的详细信息，并允许客户选择加入。

保存支付方式后，您只能将它用于条款中包含的特定使用量。要在客户离线时对某种支付方式扣款并将其保存为可供未来购物时选择的选项，请务必收集客户对这一特定用途的明确同意。例如，包含“保存我的支付方式以供未来使用”复选框以收集用户同意书。

要想在他们离线时收款，请确保您的条款中包含以下内容：

  • 客户同意您代其对指定的交易发起一次或一系列付款。
  • 预期的付款时间和频率（例如，收款是计划的分期付款、订阅付款还是计划外充值）。
  • 如何确定付款金额。
  • 如果支付方式是用于支付订阅服务，那即同意您的取消政策。

请务必让客户书面同意这些条款并做好记录。

设置 Stripe
服务器端

首先，注册一个 Stripe 账户。

用我们的官方库从您的应用程序访问 Stripe API：

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

创建一个 Customer
服务器端

要为将来的付款设置银行卡，就必须将它绑定到 Customer。当客户在您的公司创建账户时，创建 Customer 对象。Customer 对象允许重复使用支付方式并跟踪多笔付款。

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jennyrosen@example.com"

成功创建后会返回 Customer 对象。您可以检查客户 id 的对象，并将它的值存储在您的数据库中以供以后检索。

您可以在管理平台的客户页面中找到这些客户。

启用支付方式

查看您的支付方式设置，启用您想支持的支付方式。您至少需要启用一个支付方式才能创建 PaymentIntent。

默认情况下，Stripe 支持信用卡和其他常见的支付方式，可以帮助您获得更多客户，但建议您开启与您的业务和客户相关的其他支付方式。查看支付方式支持，了解支持的产品和支付方式，并查看我们的定价页面了解费用。

创建付款
服务器端

注意

如果您想在不先创建 PaymentIntent 的情况下呈现 Payment Element，请参阅收集支付详情后再创建 Intent。

Checkout Session 对象用来表示您从客户收款的意图，跟踪扣款尝试及整个过程中的状态变化情况。

创建 Checkout Session

在您的服务器上创建一个 Checkout Session。Stripe 使用您的支付方式设置显示您启用的支付方式。要查看您如何向客户显示支付方式，请在管理平台中输入交易 ID 或设置订单金额和货币。要覆盖支付方式，用 payment_method_types 属性手动列出您想要启用的支付方式。

Command Line
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}}
 \
  -d "line_items[0][quantity]"=2 \
  -d mode=payment \
  -d ui_mode=custom \
  -d "saved_payment_method_options[payment_method_save]"=enabled

注意

始终在服务器端决定扣款金额，这是一个可信的环境，客户端不行。这样可以防止恶意客户选择他们自己的价格。

收集付款详情
客户端

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

Payment Element 中包含一个 iframe，它通过一个 HTTPS 连接安全地将支付信息发送到 Stripe。避免将 Payment Element 放在另一个 iframe 中，因为有些支付方式需要重定向到另一个页面进行付款确认。

如果您确实选择使用 iframe 并想要接受 Apple Pay 或 Google Pay，则 iframe 必须要将 allow#attr-allowpaymentrequest) 属性设置为等于 "payment *"。

结账页面上的地址也必须以 https:// 开头，不能是 http://，否则您的集成不能工作。您可以在不使用 HTTPS 的情况下测试您的集成，准备好进行真实收款时将它启用。

设置 Stripe.js

Payment Element 自动可以获取，这是 Stripe.js 的功能。在您的结账页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 head 部分。为保持 PCI 合规，始终从 js.stripe.com 加载 Stripe.js。不要把脚本打包或自行保留副本。

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

用下面的 JavaScript 在您的结账页面创建一个 Stripe 实例：

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'
);

将 Payment Element 添加到您的支付页面

Payment Element 需要存在于您的支付页面的某个地方。用您的支付表单中的唯一 ID 创建一个空的 DOM 节点（容器）：

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

加载了之前的表单后，创建一个 Payment Element 实例，并将它放入容器的 DOM 节点。创建 Elements 实例时，将上一步的 client secret 传入 options：

认真处理客户端私钥，因为它会完成收款。不要记录它，而是把它嵌入到 URL，或显示给除客户以外的所有人。

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Payment Element 呈现一个动态表单，您的客户可在这里选择一个支付方式。对于每个支付方式，表单会自动请求客户填写必要的支付详情。

自定义外观

您可以自定义 Payment Element，使其匹配您网站的设计风格，方法是在创建 Elements 提供程序时向 options 传递外观对象。

收集地址

默认情况下，Payment Element 仅收集必要的账单地址信息。收集客户完整的账单地址（例如，计算数字商品和服务的税额）或收货地址时，使用 Address Element。

申请 Apple Pay 商家令牌

如果您已将集成配置为接受 Apple Pay 付款，则我们建议将 Apple Pay 接口配置为返回商家令牌，以支持商家发起的交易 (MIT)。在 Payment Element 中请求相关商家令牌类型。

向 Stripe 提交付款
客户端

使用 stripe.confirmPayment，用来自 Payment Element 的详情完成付款。为该函数提供一个 return_url，告诉 Stripe 在用户完成付款后将他们重定向到哪里。您的用户可能会先被重定向到一个中间站点，如银行授权页面，然后才被重定向到 return_url。付款成功时，银行卡付款将立即重定向到 return_url。

如果您不想在完成付款后对银行卡付款重定向，可以将重定向设置到 if_required。这样就会只重定向使用基于重定向的支付方式结账的客户。

checkout.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

注意

stripe.confirmPayment 可能需要几秒才能完成。该时间内，禁止表单重复提交，并显示一个类似于微调器的等待指示器。如果收到错误，则向客户显示，重新启用表单，然后隐藏掉等待指示器。如果客户必须执行额外的步骤来完成付款，如身份验证，Stripe.js 将引导其完成该流程。

如果付款成功，那么卡会被保存到 Customer 对象。这将反映在 PaymentMethod 的 customer 字段。这时，将这个 Customer 对象的 ID 关联到您自己对这个客户使用的内部名称（如果有）。到此，可以用储存的 PaymentMethod 对象对您的客户进行未来的收款了，不需要提示他们再次输入银行卡详情。

确保 return_url 对应于您网站上显示付款状态的一个页面。Stripe 将客户重定向到 return_url 时，我们会提供以下 URL 查询参数。

参数描述
payment_intentPaymentIntent 的唯一标识符。
payment_intent_client_secretPaymentIntent 对象的 client secret。

注意

如果您有可以用来跟踪客户浏览器会话的工具，则您可能需要将 stripe.com 域名添加到推荐人列表。重定向会导致一些工具创建新的会话，从而阻止您跟踪完整的会话。

用以下某个查询参数检索 PaymentIntent。检查 PaymentIntent 的状态，以决定向客户显示的内容。您还可以在提供 return_url 时附加自己的查询参数，它们会在重定向过程中持续存在。

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

以后对保存的支付方式扣款
服务器端

警告

bancontact、ideal 和 sofort 是默认的一次性支付方式。设置为将来使用时，它们会生成一个 sepa_debit 可重复使用的支付方式类型，因此您可以用 sepa_debit 来查询保存的支付方式。

合规

保存客户的支付详情时，您有责任遵守所有适用的法律、法规和卡组织规则。向您的最终客户呈现之前用过的支付方式以供未来购物使用时，确保您所列出的支付方式已从客户那里收集保存支付方式详情以供将来具体使用的同意书。对于绑定到客户的支付方式，要区分哪些可以哪些不可以作为保存的支付方式供未来购物使用，请使用 allow_redisplay 参数。

准备在会话外对客户扣款时，使用 Customer 和 PaymentMethod ID 创建一个 PaymentIntent。要找到扣款的支付方式，列出与您的客户关联的支付方式。该例中列出了银行卡，但您可以列出任意受支持的 type。

Command Line
curl -G https://api.stripe.com/v1/payment_methods \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d type=card

当您有 Customer 和 PaymentMethod ID 时，创建一个包含付款金额和货币的 PaymentIntent。设置几个其他参数来进行会话外付款：

  • 将 off_session 设置为 true，以指示客户其在尝试付款时并不在您的结账流程中，并且无法完成合作伙伴（如发卡行、银行或其他支付机构）提出的身份验证请求。如果在您的结账流程中，合作伙伴要求进行验证，Stripe 将使用之前的会话内交易中的客户信息请求豁免。如果不满足豁免条件，PaymentIntent 可能会抛出一个错误。
  • 将 PaymentIntent 的 confirm 属性的值设置为 true，这样就会在创建 PaymentIntent 时立即进行确认。
  • 将 payment_method 设置为 PaymentMethod 的 ID，并将 customer 设置为 Customer 的 ID。
Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d amount=1099 \
  -d currency=usd \
  # In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
  -d "automatic_payment_methods[enabled]"=true \
  -d customer="{{CUSTOMER_ID}}" \
  -d payment_method="{{PAYMENT_METHOD_ID}}" \
  -d return_url="https://example.com/order/123/complete" \
  -d off_session=true \
  -d confirm=true

测试集成

用测试付款详情和测试重定向页面验证您的集成。点击下方选项卡，查看每个支付方式的详情。

支付方式场景如何测试
信用卡银行卡设置成功，不要求验证。填写我们的信用卡表单，卡号是 4242 4242 4242 4242，有效期、CVC（银行卡安全码）以及邮编可任意填写。
信用卡该卡在初始设置时需要身份验证，在后续付款时会直接成功。填写我们的信用卡表单，卡号是 4000 0025 0000 3155，有效期、CVC（银行卡安全码）以及邮编可任意填写。
信用卡该卡在初始设置时需要身份验证，在后续付款时也需要身份验证。填写我们的信用卡表单，卡号是 4000 0027 6000 3184，有效期、CVC（银行卡安全码）以及邮编可任意填写。
信用卡设置过程中卡被拒绝了。填写我们的信用卡表单，卡号是 4000 0000 0000 9995，有效期、CVC（银行卡安全码）以及邮编可任意填写。

测试对保存的 SEPA 借记 PaymentMethod 的收款

用 iDEAL、Bancontact 或 Sofort 确认 PaymentIntent ，生成 SEPA 直接借记 PaymentMethod。SEPA 直接借记是一种延迟通知型支付方式，它几天后会变为 succeeded 或 requires_payment_method 状态，在此之前会变为一个中间 processing 状态。

将 payment_method.billing_details.email 设置为以下某个值，以测试 PaymentIntent 的状态变化。您可以在电子邮件地址的开头加上下划线来包含您的自定义文本。例如，test_1_generatedSepaDebitIntentsFail@example.com 会导致 SEPA 直接借记 PaymentMethod 在与 PaymentIntent 一起使用始终会失败。

邮件地址描述
generatedSepaDebitIntentsSucceed@example.comPaymentIntent 状态从 processing 变为 succeeded。
generatedSepaDebitIntentsSucceedDelayed@example.comPaymentIntent 状态在至少三分钟后从 processing 变为 succeeded。
generatedSepaDebitIntentsFail@example.comPaymentIntent 状态从 processing 变为 requires_payment_method。
generatedSepaDebitIntentsFailDelayed@example.comPaymentIntent 状态在至少三分钟后从 processing 变为 requires_payment_method。
generatedSepaDebitIntentsSucceedDisputed@example.comPaymentIntent 状态从 processing 变为 succeeded，但会立即创建争议。

另见

此页面的内容有帮助吗？
是否
需要帮助？联系支持。
加入我们的早期使用计划。
查看我们的更改日志。
有问题？联系销售。
LLM? Read llms.txt.
Powered by Markdoc