VibeFox Stripe for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

Stripe 账户：您需要 Stripe 账户的私密 API 密钥，以及 Stripe Dashboard 中的一个 Webhook 端点（参见配置）。仅使用私密密钥和 Webhook 签名密钥。无需可发布密钥（pk_...），因为 Stripe Checkout 是由 Stripe 托管的页面。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_stripe_gateway-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_stripe_gateway.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_stripe_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，直接将本安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Stripe Gateway，点击 Install（绿色 + 按钮）。您的后台用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。

4. 粘贴您的 Stripe 私密密钥，在 Stripe Dashboard 中设置 Webhook，并粘贴其签名密钥（参见配置）。

5. 开启 Enable/Disable 并点击 Save。使用测试卡 4242 4242 4242 4242 在测试模式下完成一笔付款测试，然后关闭 Test Mode。

OpenCart 4

1. 在后台依次进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_stripe_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法使用。

2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Stripe Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 请按照 OpenCart 3 步骤 3 至 5 输入许可证密钥、Stripe 密钥和 Webhook。两个版本的设置页面及其字段完全相同，只有 Webhook URL 不同（参见 Webhook）。

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当当前模式没有私密密钥时（此时结账页面会隐藏该付款方式）或没有 Webhook 签名密钥时（此时订单仅在顾客付款后返回店铺时才会被确认），页面会向您发出提醒；测试模式开启时，页面会显示 测试模式已开启：不会接受真实付款。。若您没有修改扩展的权限，页面仍会显示设置，但无法保存。

保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为整数，Total 必须为 0 或更大的数字。如果某个密钥或密钥串的前缀不符合预期，设置仍会保存，并在设置上方显示一条指出对应字段的警告。

Stripe Checkout

Enable/Disable：Enable Stripe Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称，也是订单中保存的付款方式名称。默认：Stripe。必填。

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay securely with your credit or debit card via Stripe.

Sort Order：Stripe 在结账时付款方式中的排列位置。可留空或填写整数。

Geo Zone：仅对所选地区内的付款地址提供 Stripe。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total：订单在结账时必须达到的金额（以店铺默认货币计），才会提供 Stripe。留空则对任何金额都提供 Stripe。

API 密钥

从 Stripe Dashboard > Developers > API keys 复制私密密钥（该页面提供了链接）。测试密钥与正式密钥是分开的。测试模式仅使用测试密钥，正式模式仅使用正式密钥。

Test Mode：使用 Stripe 测试密钥。不会扣除真实资金；请使用 Stripe 测试卡（例如 4242 4242 4242 4242）付款。默认：开启。关闭后即可接受真实付款。开启时，顾客在 Confirm Order 步骤中会看到 测试模式：不接受真实付款。

Test Secret Key：测试模式的私密密钥。以 sk_test_ 开头（若为受限密钥，则以 rk_test_ 开头）。

Test Webhook Secret：在测试模式下创建的 Webhook 端点的签名密钥（whsec_...）。

Live Secret Key：正式模式的私密密钥。以 sk_live_ 开头（若为受限密钥，则以 rk_live_ 开头）。

Live Webhook Secret：在正式模式下创建的 Webhook 端点的签名密钥（whsec_...）。

已保存的密钥和密钥串不会再次显示。该字段会保持为空，并显示 已保存——留空即保持不变。。只有在需要更改时才输入新值。如要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

Webhook

Webhook 用于告知您的店铺某笔付款已完成。在 Stripe Dashboard > Developers > Webhooks 中，分别为测试模式和正式模式添加一个端点。请使用本节 Endpoint URL 中显示的 URL。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_stripe_gateway/webhook，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_stripe_gateway/payment/wcp_stripe_gateway.webhook，由您 OpenCart 安装的前台地址生成。请完全按照设置中显示的内容复制该 URL。

为每个端点选择以下事件（本节也列出了这些事件）：

创建每个端点后，请从 Stripe 复制其签名密钥（whsec_...），并将其粘贴到 Test Webhook Secret 或 Live Webhook Secret 中。签名无效的 Webhook 会被拒绝。只有使用付款所在模式的密钥签名的事件才会被接受，因此测试密钥绝不会确认真实付款。如果没有 Webhook，订单只有在顾客付款后返回店铺时才会被确认。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（即未完成的订单）。只有在 Stripe 确认付款之后，订单才会获得状态。下方每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款成功后设置的状态。默认：Processing。

Awaiting Payment Status：延迟付款：结账已完成，但 Stripe 尚未确认款项。默认：Pending。

On Hold (Review) Status：付款需要您审核（参见订单状态）。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Failed Payment Status：延迟付款失败。默认：Failed。

Refunded Status：在订单页面将付款全额退款后设置。默认：Refunded。

高级

Logging：将 Stripe 请求和 Webhook 写入 OpenCart 日志文件夹（storage/logs）中的 strg_debug.log.php。该文件无法通过网页打开；当其达到 5 MB 时，会被移动为 strg_debug.old.log.php。密钥和顾客数据不会被记录。默认：关闭。关闭时不会写入任何内容，包括错误。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete Data on Uninstall：开启后，卸载扩展时会删除网关设置和日志。Stripe 交易和退款始终会保留，因此旧订单仍可退款。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。私密密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的私密密钥会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Stripe）。在 Confirm Order 步骤中，顾客会看到您填写的描述，以及提示 即将跳转到 Stripe，以安全地完成付款。。OpenCart 在此步骤创建订单，此时仍无状态。顾客点击 Confirm Order 后，扩展会以订单金额和订单币种创建一个 Stripe Checkout 会话，并将顾客跳转到 Stripe 的付款页面。顾客在该页面使用信用卡或借记卡付款。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。顾客的电子邮件会传给 Stripe，并且在 Stripe 页面上，付款会以 Order # 加订单号的形式显示。

付款后，顾客会返回您的店铺。只有在 Stripe 确认付款之后，订单才会被标记为已付款：通过已签名的 Webhook，或在顾客返回时由服务器向 Stripe 发出请求确认。之后，订单会以 OpenCart 的标准方式获得状态，发送常规的订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。对于延迟付款，该页面还会显示 您的付款正在由 Stripe 确认。确认后，您将收到一封电子邮件。。如果顾客返回时 Stripe 尚未确认付款，则会显示一个 付款确认 页面，内容相同，并带有 Check again 按钮；Webhook 一到达就会设置订单状态。

如果顾客在 Stripe 页面上取消，Stripe 会话会被关闭，顾客返回结账页面，并看到 付款已取消。您可以重试或选择其他付款方式。。如果付款未完成或延迟付款失败，提示为 付款未完成。您可以重试或选择其他付款方式。。购物车会被保留。在 OpenCart 4 中，这些提示会显示在结账页面上方。每次新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会更新结账中的订单）都会关闭该购物车之前未完成的 Stripe 会话，因此无法重复付款。如果某个之前的会话被发现已经付款，则会确认该笔付款，而不是发起新的付款。如果同一购物车的另一个订单已通过 Stripe 付款，则不会发起新的付款，顾客会看到订单成功页面。购物车的任何变动（包括新的数量）都会被视为需要单独付款的新购物车。

OpenCart 4 会将订单保留在结账流程中，直到显示成功页面。如果该订单在此期间未付款即已被关闭（例如其延迟付款失败，或您取消了该订单），顾客将被带回结账页面，并看到关于未完成付款的提示，下一次点击 Confirm Order 时将为一个新订单付款。已付款的订单绝不会在其他购物车中显示为已付款。

如果 Stripe 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短提示，例如 订单金额低于 Stripe 在该币种下可收取的最低金额。请选择其他付款方式。。技术原因会写入日志。

即使店铺处于维护模式，Webhook 也能正常工作，因为 OpenCart 允许付款扩展的请求通过。

该扩展仅接受银行卡付款，并在 Stripe 页面上立即扣款。它不支持保存的银行卡、订阅或定期付款，不提供您网站上的银行卡表单，也不提供您网站上的 Apple Pay 或 Google Pay 按钮，且不支持单独的授权和扣款。

订单与退款

订单状态

无状态（未完成订单）：顾客已被发送至 Stripe 但尚未付款，或 Stripe 尚未确认付款。在 Sales > Orders 中，此类订单仅在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：付款已确认。备注会显示 Stripe 付款（pi_...）、会话以及确认方式（Webhook 或返回）。

Awaiting Payment Status（默认 Pending）：顾客使用延迟付款方式完成了结账。当 Stripe 确认付款时，订单会转为 Order Status After Payment；当付款失败时，订单会转为 Failed Payment Status。OpenCart 会就这些变化通知顾客。

On Hold (Review) Status（默认 Pending）：Stripe 报告的金额或币种与订单总额不符，或付款在订单已取消或状态已变更之后才到达。备注会对此进行说明。请检查订单并完成处理，或退还付款。

Refunded Status（默认 Refunded）：付款已通过该扩展全额退款。

如果已付款的订单又收到第二笔付款，该订单不会被更改。备注会提示您检查并在 Stripe Dashboard 中退还重复的付款。当付款属于同一购物车中另一个已付款的订单时，情况相同：该订单保持无状态，备注会添加到已付款的订单上。

备注是订单 History 中的条目，顾客看不到。

VibeFox Stripe Gateway 标签页

在 Sales > Orders 中打开一笔通过 Stripe 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Stripe Gateway 标签页会显示 Stripe 付款 ID（链接到 Stripe Dashboard 中的付款），测试付款会带有 Test mode 标签；此外还显示 Checkout Session、付款 Status、Paid / refunded 金额、退款表单、退款历史以及订单的 Stripe notes。该标签页仅对有权访问该扩展的用户显示。

退款

在 VibeFox Stripe Gateway 标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Stripe。确认提示 是否通过 Stripe 退还此金额？此操作无法撤销。。支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 Stripe 扣款时的金额和币种进行，而不是按订单总额。退款会发送到付款时所在的模式（测试或正式），因此必须设置该模式的私密密钥。如果 Stripe 不接受退款，标签页会显示错误，且不会记录退款。成功的退款会连同 Stripe 退款 ID 添加到历史和备注中。全额退款会将订单设为 Refunded Status，不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。退款需在 Stripe 确认付款之后才可进行。

Sales > Returns 中的商品退货不会通过 Stripe 退款。

在 Stripe Dashboard 中进行的退款会通过 charge.refunded Webhook 送达，并连同 Stripe 中的累计退款金额一起添加到备注中。订单状态不会自动更改。如有需要，请手动更新。

许可证密钥

该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥才能运行。许可证区块 License — VibeFox Stripe Gateway 位于 Extensions > Extensions > Payments > VibeFox Stripe Gateway > Edit 页面的最上方，在设置之前。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期及您的域名），以及以下按钮：Check now 用于重新检查状态，Change key 用于输入另一个密钥，Remove key 用于从此店铺移除该密钥。其下方是 Product: opencart-payment-stripe 一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加日期。在店铺地址变更后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 Stripe。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one.。在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并带有 (unlicensed — visible to admins only) 标记，因此您可以在购买密钥前完成扩展的设置与测试。在 OpenCart 4 中没有此预览功能：店铺无法看到后台登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已开始的付款仍会被确认，退款也照常可用。

许可证过期后，扩展会继续运行，但更新和支持需要续期。当您打开后台的 Dashboard 或 Edit 页面时，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，许可证密钥和许可证状态总会被删除。

故障排除

Stripe 未在结账页面中显示：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否有私密密钥：测试模式下为 Test Secret Key，正式模式下为 Live Secret Key。缺少密钥时，设置页面会显示警告。另外还需检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：Webhook 没有生效。请在 Stripe Dashboard 中检查该端点是否存在于您使用的模式（测试或正式）中，其 URL 是否与 Endpoint URL 中显示的完全一致，以及四个事件是否均已选中。检查该端点的签名密钥是否位于对应字段中（Test Webhook Secret 或 Live Webhook Secret）。Stripe Dashboard 会显示您的店铺对每个 Webhook 的响应。顾客付款后返回店铺时，订单也会获得状态。

Webhook 返回 Webhook secret not configured：两个 Webhook 密钥都未设置。请将签名密钥粘贴到设置中。

Webhook 返回 Invalid signature：签名密钥属于另一个端点或另一个模式，或服务器时间不正确。Stripe 签名仅在服务器时间的 5 分钟内被接受。当正式付款的事件使用测试密钥签名，或反之，返回结果同样是 Invalid signature：请检查测试密钥和正式密钥是否被调换。

Webhook 返回 Busy, retry：订单在同一时刻正被另一个请求确认，或订单状态无法设置。Stripe 会自动重试 Webhook。请开启 Logging 查看原因。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 Stripe 的请求。

保存时出现 The value does not look right 警告：密钥被粘贴到了错误的字段中。私密密钥以 sk_test_ / rk_test_ 或 sk_live_ / rk_live_ 开头，Webhook 密钥以 whsec_ 开头。

顾客在 Confirm Order 之后看到错误：请开启 Logging 并查看扩展页面上的 Log 字段。This payment method is not available. Please reload the checkout page. 表示付款会话已不再与订单匹配，或该付款方式在此期间已被关闭：顾客需要重新加载结账页面。密钥错误会显示付款方式配置不正确的消息。低于 Stripe 在该币种下最低金额的订单总额（例如 0.50 EUR）无法通过 Stripe 付款。

测试付款无法确认正式付款：测试付款和正式付款是分开处理的。请将 Test Mode 切换到您想要的模式，并使用该模式的密钥和 Webhook。

付款后订单处于审核状态：请阅读 VibeFox Stripe Gateway 标签页中的备注（参见订单状态），然后完成订单或退还付款。

标签页中没有退款表单：标签页会说明原因：付款尚未确认、已全额退款，或您的用户组没有修改扩展的权限。

退款因模式相关的消息而失败：付款是在测试或正式模式下进行的，而该模式的私密密钥未设置。请输入后重试。

开发人员须知：在创建 Stripe 会话之前，扩展会触发 OpenCart 事件 strg_checkout_session_params，并附带会话参数和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Stripe Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件和启动操作，启动操作用于在维护模式下放行 Webhook）。如果 Delete Data on Uninstall 已开启，则其余网关设置（标题、描述、测试模式、密钥、Webhook 密钥、日志）和日志都会被删除。如果已关闭，这些内容会保留，供日后重新安装使用。Stripe 交易和退款始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Stripe Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

Stripe 是其各自所有者的商标。本扩展与 Stripe 无关联，也未获得 Stripe 的认可或背书。