调至内容部分
创建账户
或
登录
Stripe 文档徽标
/
创建账户
登录
概览升级您的集成
线上付款
概览查找您的用例Managed Payments
支付方式
支付接口
支付场景
线下支付
Beyond payments

Konbini 支付

用 Payment Intents 和 Payment Methods APIs 实现 Konbini 收款，这是日本在便利店常用的一种支付方式。

日本的用户可以接收在日本的客户用 Payment Intents 和 Payment Methods APIs 进行的 Konbini 付款。客户通过在日本便利店提供一个付款码、确认码并支付现金，完成付款。Stripe 会在付款完成时给您通知。

设置 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'

创建 PaymentIntent
服务器端

Stripe 用一个 PaymentIntent 对象来表示您从客户收款的意图，跟踪从 Konbini PaymentIntent 创建直至完成整个过程中的状态变化。

在您的服务器上创建一个带有金额和 jpy 货币的 PaymentIntent（Konbini 不支持其他货币）。如果您已经有使用 Payment Intents API 的集成，则将 konbini 添加到您的 PaymentIntent 的 payment method types。

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=jpy \
  -d "payment_method_types[]"=konbini \
  -d "payment_method_options[konbini][product_description]"="Tシャツ" \
  -d "payment_method_options[konbini][expires_after_days]"=3

检索客户端私钥

PaymentIntent 中包含的是一个客户端私钥，用于在客户端安全地完成支付流程。有不同的方法可以将客户端私钥传递到客户端。

使用浏览器的 fetch 功能，从您的服务器上的端点获取客户端私钥。如果您的客户端是单页应用，特别是用现代的前端框架（例如 React）搭建的情况，则该方法最为合适。创建服务于客户端私钥的服务器端点：

main.rb
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

然后在客户端用 JavaScript 获取客户端私钥：

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

其他支付方式选项

支付方式选项可以在 payment method options（konbini 参数下）中指定。

字段值必填默认值
expires_after_days待处理的 Konbini 付款到期前的自然天数。有效值为 1 到 60 天。参见有效期。否3
expires_at待处理的 Konbini 付款到期的一个 Unix 时间戳。有效期必须至少在当前时间 30 分钟以后，且在将设置应用到 PaymentIntent 之后的 60 天以内。参见有效期。否复位
product_description产品描述符最多为 22 个字符，在便利店向客户出示。非 Shift JIS (JIS X 0208:1997) 字符会造成返回错误。虽不要求，但我们建议设置该选项。否则，我们就会退回到我们自己选择的通用占位符，例如，お買い上げ商品・サービス。否占位符

有效期

待处理的 Konbini 付款在特定日期的午夜 (23:59:59 JST) 准时过期。例如，如果 expires_after_days 设置为 2，然后未在周一确认 PaymentIntent，则待处理的 Konbini 付款将在日本时间 (UTC+9) 周三的 23:59:59 过期。

expires_at 设置为 Unix 时间戳，精确到秒。如果该值小于当前时间 30 分钟，或 PaymentIntent 确认操作距离到期时间不足 30 分钟，则会返回一个错误。

expires_after_days 和 expires_at 彼此互斥。如两个都设置，会返回一个错误。两个也都是可选的，如果两个都不设置，则到期时间默认为创建 PaymentIntent 3 天后的日本时间 23:59 (UTC+9)。

错误处理

PaymentIntents 上的请求（例如创建、更新和确认）可能会失败。您可以通过检查 API 响应的 error 值来确定原因，在许多情况下，要么重新提交请求，要么更正错误。特别是，如果您为 confirmation_number 支付方式选项提供一个值的话，您可能希望处理我们返回的特定错误代码。查看确认码，了解更多详情。

中断问题、计划性维护或您的使用模式都可能导致支付方式暂时不可用。更多信息，请见处理临时问题。

收集支付方式详情
客户端

在您的客户端创建一个支付表单，从客户那里收集要求的账单详情：

字段值
name客户的全名，会在便利店的 UI 和收据中截短为 20 个字符。非 Shift JIS (JIS X 0208:1997) 字符将被删除或替换。
email客户的完整邮件地址。

此表单示例中还收集了电话号码，用作客户提供的确认码。

checkout.html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <div class="form-row">
    <label for="phone">
      Phone Number
    </label>
    <input id="phone" name="phone" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with Konbini</button>
</form>

向 Stripe 提交付款
客户端

客户通过 Konbini 点击支付时，用 Stripe.js 向 Stripe 提交付款。Stripe.js 是我们构建支付流程的基础 JavaScript 库。

在您的结账页面包含 Stripe.js 脚本，方法是将它添加到您的 HTML 文件的 head 部分。

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

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

client.js
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

用您在第 2 步创建的 PaymentIntent 对象的 stripe.confirmKonbiniPayment 和 client secret 提交客户的账单详情。

一经确认，Stripe 将自动打开一个模态，向客户显示 Konbini 付款说明。

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

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

  const result = await stripe.confirmKonbiniPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
      payment_method_options: {
        konbini: {
          confirmation_number: document.getElementById('phone').value.replace(/\D/g,''),
        },
      },
    }
  );
  // Stripe.js will open a modal to display the Konbini payment instructions to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

注意

stripe.confirmKonbiniPayment 可能需要几秒才能完成。该时间内，禁止表单重复提交，并显示一个类似于微调器的等待指示器。如果收到错误，则向客户显示，重新启用表单，然后隐藏掉等待指示器。

其他支付方式选项

确认 Konbini PaymentIntent 时，您可以在 payment method options（konbini 参数下）中指定其他支付方式选项。

字段值必填默认值
confirmation_number10 至 11 位数字字符串。此字符串也会显示在支付说明中，不能只包含零。如果您没有为 confirmation_number 提供值，Stripe 会为您随机生成一个值。有关更多信息，请参见确认码。否复位

确认码

您的客户在付款时可能需要参考 confirmation_number。如果您选择您来设置或允许客户设置，那通常建议将此值设置成客户的手机号码。在服务器端创建 PaymentIntent 的过程中，也可以设置 confirmation_number，但更常见的情况是在确认 PaymentIntent 时由客户在客户端设置。从创建 PaymentIntent 直至确认，设定的值可能会一直更新。

如果指定的某个 confirmation_number 在进行中的便利店交易中过于普遍，则在确认 PaymentIntent 时可能会被拒绝。这种情况下返回的错误代码是 payment_intent_konbini_rejected_confirmation_number，只有在确认 PaymentIntent 时才会出现。

在创建 PaymentIntent 时以及更新和确认过程中，Stripe 会主动阻止仅包含零的确认码。请确保在您这一端没有设置这样的值或没有允许客户设置这样的值。

错误处理

在客户端确认 PaymentIntent 时也可能会失败。应检查 error 的返回值来确定原因，并尽量向客户显示错误或修改错误后再次尝试。

处理付款后事件
服务器端

Konbini 属于延迟通知型支付方式，因此资金不会立即到账。客户在结账后可能不会立即在便利店支付待收的 Konbini 付款。

待处理的 Konbini 付款完成后，Stripe 会为其发送一个 payment_intent.succeeded 事件。使用管理平台或构建一个 Webhook 处理程序来接收这些事件并运行动作。这些动作包括：向客户发送订单确认邮件、在数据库中记录订单，或启动配送流程。

在可以稳妥地确定待处理的 Konbini 付款未完成时（通常在过期一小时以后），Stripe 会发送一个 payment_intent.payment_failed 事件。

活动描述后续步骤
payment_intent.requires_action创建了待处理的 Konbini 支付。（可选）将客户转至支付说明页面。等待客户对 Konbini 支付进行付款。
payment_intent.succeeded客户在到期时间之前支付待处理的 Konbini 付款。履行客户购买的商品或服务。
payment_intent.payment_failed客户未在到期时间之前对待处理的 Konbini 支付进行付款。通过电子邮件或推送通知联系客户，请求另一支付方式。

注意

测试时，Konbini PaymentIntent 的状态可能会根据发送的参数自动变化，例如 email。可以在管理平台确认发生的更新。参见测试集成中的更多信息。

接收事件并启动公司操作

手动

用 Stripe 管理平台查看您的所有 Stripe 付款，发送邮件收据，处理提现或重试失败的付款。

自定义代码

构建一个 Webhook 处理程序，侦听事件并构建自定义同步付款流程。用 Stripe CLI 在本地测试并调试您的 Webhook 集成。

测试集成

测试时，调用 stripe.confirmKonbiniPayment 来测试不同场景时将 payment_method.billing_details.email 设置到下列值。您可以用专用确认码或邮件样式来测试。如果两者都用，则专用确认码的行为适用。

邮件地址确认码描述

{any_prefix}@{any_domain}

11111111110

模拟一笔三分钟后成功的 Konbini 付款，然后收到 payment_intent.succeeded Webhook。

例如：hanako@test.com

{any_prefix}succeed_immediately@{any_domain}

22222222220

模拟一笔立即成功的 Konbini 付款，然后收到 payment_intent.succeeded Webhook。

例如：succeed_immediately@test.com

{any_prefix}expire_immediately@{any_domain}

33333333330

模拟一笔立即过期 Konbini 付款，然后收到 payment_intent.payment_failed Webhook。

next_action.konbini_display_details 中的 expires_at 字段设置为当前时间，不要管 payment method options 中的 expires_after_days 或 expires_at 参数设置的是什么时间。

例如：expire_immediately@test.com

{any_prefix}expire_with_delay@{any_domain}

44444444440

模拟一笔永远不会成功的 Konbini 付款，然后收到 payment_intent.payment_failed Webhook。

next_action.konbini_display_details 中的 expires_at 字段设置为未来 3 分钟，不要管 payment method options 中的 expires_after_days 或 expires_at 参数设置的是什么时间。

例如：expire_with_delay@test.com

{any_prefix}fill_never@{any_domain}

55555555550

模拟一笔永远不会成功的 Konbini 付款；按照 payment method options 中提供的各个参数的 next_action.konbini_display_details 中的 expires_at 字段的时间过期，然后收到 payment_intent.payment_failed Webhook。

例如：fill_never@test.com

要测试确认码的错误处理情况，可以使用 payment_method_options[confirmation_number] 的以下值：

  • 01234567890 生成 payment_intent_konbini_rejected_confirmation_number 错误代码。
  • 00000000000 生成一般验证错误代码。您应该通过预验证来避免在集成中出现这一错误。

过期和取消

在由 next_action.konbini_display_details 中的 expires_at 值指定的时间过后，客户不能再在便利店的自助服务终端上_发起_待处理的 Konbini 付款的付款流程。但是，如果在截止时间之前给了他们有效的付款单，则或许能够在 expires_at 之后在收银机上_完成_付款。

这种情况下，会有一个缓冲期，避免在提前付款失败。PaymentIntent 的状态会变成 requires_payment_method。这时，可以用另一支付方式取消或确认 PaymentIntent。

您也可以在确认后以及 next_action.konbini_display_details.expires_at 指定的时间到达前，取消待处理的 Konbini 付款。更新 PaymentIntent 或用另一种支付方式确认它也将隐式地取消现有的 Konbini 付款。

如果客户目前正在便利店进行 Konbini 支付，取消请求将失败。如果客户放弃付款尝试，并且付款单已过期，则可以重新尝试取消。

请注意，支付方式暂时性的可用性问题也会影响（既有显示又有隐式影响）取消请求。

注意

取消待处理的支付时，原始支付说明会失效。大多数情况下，建议您联系您的客户，通知他们取消支付。

成功地重新确认了 requires_action 状态的 PaymentIntent 后，我们会创建新的说明和新的 hosted_voucher_url。您要保证客户意识到这些问题。

处理临时性的可用性问题

以下错误代码表明支付方式的可用性出现了临时性的问题：

代码描述处理
payment_method_rate_limit_exceeded该支付方式的连续请求太多，其限制比我们的 API 范围的速率限制更严格。用退避方式重新尝试一般是可以解决这种问题的。但是，在持续大量使用支付方式的情况下（例如，您的网站持续促销期间），一些特定数量的请求可能会持续发生这些错误。这种情况下，让您的客户考虑选择不同的支付方式可能也是一种缓解措施。
payment_method_not_available支付方式遇到了未知的临时性问题，这些问题可能会持续一段时间（例如，在中断或计划性的维护期间）。最好邀请您的用户使用不同的支付方式完成购买，或者以后再尝试。

注意

如果您预计会发生常规性或因即将到来的事件造成的大量使用，请提前与我们联系。

退款

可以通过管理平台或 API 退还 Konbini 付款。

要直接完成转到客户银行账户的退款，您的客户必须提供用来接收资金的银行账户的详细信息。Stripe 会通过支付方式上的账单详情中的邮件地址联系客户，并请求他们提供这些信息。收到银行详情后，我们会自动处理退款。

退款的状态变化如下：

活动退款状态
退款已创建requires_action
客户提交银行账户详情，Stripe 开始处理退款pending
退款预计会到达客户的银行succeeded
客户的银行将资金退回到 Striperequires_action
创建 45 天以后，退款状态变为 requires_action。failed
退款从 requires_action 状态取消canceled

如果客户的银行不能成功完成转账，资金会退到 Stripe，然后退款状态变为 requires_action。在账户持有人的姓名与收款行记录的姓名不匹配，或提供的银行账号有输入错误时，就会发生这种情况。这些情况下，Stripe 会邮件通知客户发生的故障，并让他们重新提交银行账户详情。

如果您的客户不能在 45 天内提供他们的银行账户详细信息，退款的状态将变为 failed，我们发送 refund.failed 事件。这意味着 Stripe 不能处理这笔退款，您必须在 Stripe 外部将资金退给客户。

退款上的 instructions_email 字段是退款发至的邮件地址。当退款等待客户回复时，还可以在退款的 next_action.display_details.email_sent 字段中找到发给客户的电子邮件的详细信息。

每一笔退款（包括每笔部分退款）都可能产生费用。请联系您在 Stripe 的对接人，了解有关这种费用的更多信息。

测试退款

给客户发送的邮件中有银行账户详情收集链接，您可以用其中的以下测试用银行账户在测试模式下测试退款行为。不接受这些测试银行账户之外的银行账户。

路径账户类型
11000000001234退款成功。

1100000

1111113

1111116

1111113

3333335

4444440

退款失败。

测试退款有效时间

您可以发起一个 API 调用来模拟一笔测试退款的有效时间。

Command Line
curl https://api.stripe.com/v1/test_helpers/refunds/{{REFUND_ID}}/expire \
  -X POST \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
此页面的内容有帮助吗？
是否
需要帮助？联系支持。
加入我们的早期使用计划。
查看我们的更改日志。
有问题？联系销售。
LLM? Read llms.txt.
Powered by Markdoc