VibeFox Stripe for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
Stripe 账户：您需要 Stripe 账户的私密 API 密钥，以及 Stripe Dashboard 中的一个 Webhook 端点（参见配置）。模块只使用私密密钥和 Webhook 签名密钥。无需可发布密钥（pk_...），因为 Stripe Checkout 是 Stripe 托管的页面。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Stripe Gateway，点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（见许可证密钥）。
4. 粘贴您的 Stripe 私密密钥，在 Stripe Dashboard 中设置 Webhook，并粘贴其签名密钥（参见配置）。
5. 开启 Enable/Disable，点击 Save。使用测试卡 4242 4242 4242 4242 在测试模式下试付一次，然后关闭 Test Mode。
安装时，模块会创建两个订单状态：Awaiting Stripe payment 和 Stripe payment on hold。PrestaShop 会为所有币种、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中加以限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Stripe Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果当前模式没有私密密钥（此时付款方式会在结账时隐藏）或没有 Webhook 签名密钥（此时订单仅在顾客返回店铺后才会确认），页面会向您发出警告。测试模式开启时，页面还会显示 测试模式已开启：不会收取任何真实付款。
Stripe Checkout
Enable/Disable：Enable Stripe Gateway 用于开启或关闭付款方式。Default: off。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。Default: Stripe。必填。
Description：结账时显示在付款方式下方的文字。Default: Pay securely with your credit or debit card via Stripe。
API 密钥
从 Stripe Dashboard > Developers > API keys 复制私密密钥。测试密钥与正式密钥是分开的。测试模式只使用测试密钥，正式模式只使用正式密钥。保存时，如果某个值不是以预期的前缀开头（例如粘贴了可发布密钥而不是私密密钥），模块会发出警告。
Test Mode：使用 Stripe 测试密钥。不会扣除真实款项；请使用 Stripe 测试卡（例如 4242 4242 4242 4242）付款。Default: on。关闭它即可接受真实付款。开启时，顾客会在付款方式下方看到 测试模式：不会收取任何真实付款。
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 saved secrets：勾选某个密钥或签名密钥，然后点击 Save 即可将其删除。空字段会保留已保存的值。
Webhook
Webhook 用于告知您的店铺已完成付款。在 Stripe Dashboard > Developers > Webhooks 中，分别在测试模式和正式模式下各添加一个端点。使用本节 Endpoint URL 中显示的 URL。启用友好 URL 时，它的格式类似 https://your-shop/module/wcp_stripe_gateway/webhook，可能带有语言代码，例如 /en/。请完全按照设置中显示的内容复制 URL，因为 Stripe 不会跟随重定向。
为每个端点选择以下事件（本节也列出了这些事件）：
创建每个端点后，请从 Stripe 复制其签名密钥（whsec_...），并粘贴到 Test Webhook Secret 或 Live Webhook Secret 中。没有有效签名的 Webhook 会被拒绝。事件必须使用付款所在模式的密钥签名，因此测试密钥绝不会确认正式付款。如果没有 Webhook，只有在顾客付款后返回店铺时才会创建订单。
订单
Order Status After Payment：付款成功后设置的订单状态。
延迟付款会等待在 Awaiting Stripe payment 状态。金额或币种不一致的订单始终会进入 Stripe payment on hold。
高级
Logging：将 Stripe 请求和 Webhook 写入模块文件夹中的 logs/strg_debug.log.php。该文件无法通过网页打开。密钥和顾客数据不会被记录。Default: off。关闭时不会写入任何内容。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启时，卸载模块会删除网关设置和日志。Stripe 交易和退款以及模块的订单状态始终保留，因此现有订单可以继续正常使用。Default: off。
结账
在付款步骤中，顾客选择付款方式（默认为 Stripe），并看到提示 您将被重定向至 Stripe 以安全地完成付款。 确认后，模块会按购物车币种为购物车总额创建 Stripe Checkout 会话，并将顾客带到 Stripe 付款页面。顾客在该页面使用信用卡或借记卡付款。顾客的电子邮件会传递给 Stripe，付款在 Stripe 页面上显示为 Cart # 加购物车编号。此时尚未创建任何订单。
付款后，顾客返回您的店铺。只有在 Stripe 确认后，订单才会被标记为已付款：通过已签名的 Webhook，或在顾客返回时由服务器向 Stripe 发出的请求。随后订单被创建，顾客会看到标准的订单确认页面，并显示 您的 Stripe 付款已收到。 对于延迟付款，页面会显示 您的付款正在由 Stripe 确认。确认后我们会向您发送电子邮件。 如果延迟付款之后失败，页面会显示 您的 Stripe 付款未完成。请就此订单与我们联系。 如果顾客返回时 Stripe 尚未确认付款，Payment confirmation 页面会显示相同的文字以及一个 Check again 按钮；Webhook 一到达就会创建订单。
如果顾客在 Stripe 页面取消，Stripe 会话会关闭，顾客会返回结账页面，并看到 付款已取消。您可以重试，或选择其他付款方式。 如果付款未完成，提示为 付款未完成。您可以重试，或选择其他付款方式。 购物车会被保留。每次新的尝试都会关闭之前的 Stripe 会话，因此同一购物车无法被付款两次。如果之前的会话结果已经付款，则会创建订单，而不是再次付款。
如果 Stripe 无法发起付款，顾客会停留在结账页面，并看到一条简短提示，例如 订单金额低于 Stripe 在该币种下可收取的最低金额。请选择其他付款方式。 技术原因会写入日志。
如果购物车中的优惠券在付款与确认之间失效，PrestaShop 会将其从订单中移除。由于顾客已按折扣价付款，订单随后会进入 Stripe payment on hold 状态并附上备注。
即使店铺处于维护模式，Webhook 仍然有效，并且不受店铺的国家限制影响。
本模块仅接受银行卡付款，并在 Stripe 页面上立即扣款。它不支持保存银行卡、订阅或定期付款，不提供网站内银行卡表单，您的网站上也没有 Apple Pay 或 Google Pay 按钮，且不支持分开的授权与扣款。
订单与退款
订单状态
尚无订单：顾客已被转到 Stripe 但尚未付款，或 Stripe 尚未确认付款。此时只存在购物车。
Payment accepted, Delivered or Stripe payment on hold：付款已确认。状态遵循 Order Status After Payment。付款会以 Stripe 付款 ID（pi_...）作为交易 ID 记录，备注会显示 Stripe 付款、会话以及确认方式（Webhook 或返回）。
Awaiting Stripe payment：顾客使用延迟付款方式完成了结账。Stripe 确认付款后，订单会转为已付款状态。
Stripe payment on hold after payment：Stripe 报告的金额或币种与订单总额不同（例如付款开始后购物车被修改），优惠券被移除，或订单取消后才收到付款。备注会说明原因。请检查订单，然后处理订单或退还付款。
Payment error：延迟付款失败。
Refunded：付款已通过模块全额退款。
如果对已付款的订单又收到第二笔付款，订单不会被更改。备注会提醒您进行检查，并在 Stripe Dashboard 中退还重复付款。
Stripe payment 区块
订单页面会显示一个 Stripe payment 区块，包含 Stripe 付款 ID（链接到 Stripe Dashboard 中的付款）、Checkout Session、付款状态、Stripe 扣除的金额和已退款金额、测试付款的 Test mode 标识、退款记录，以及订单的 Stripe notes。
退款
在 Stripe payment 区块中输入金额（会自动填入尚未退款的金额），可选填退款原因，然后点击 Refund via Stripe。确认提示 通过 Stripe 退还此金额？此操作无法撤销。 支持全额和部分退款。您需要具有编辑订单的权限。退款以 Stripe 实际扣除的金额和币种进行，因此在金额或币种不一致之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会在付款所处的模式（测试或正式）下发送，因此该模式的私密密钥必须已设置。如果 Stripe 拒绝退款，区块会显示错误，且不会记录任何退款。成功的退款会连同 Stripe 退款 ID 一起添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会改变状态。只有在 Stripe 确认付款后，才能退款。
本模块不会开具退款单。订单页面上 PrestaShop 的标准退款按钮不会通过 Stripe 退款。
在 Stripe Dashboard 中进行的退款会通过 charge.refunded Webhook 送达，并连同 Stripe 中的累计退款总额一起添加到备注中。订单状态和退款单不会自动更改。如有需要，请手动更新。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Stripe Gateway 许可证区块位于 Modules > Module Manager > VibeFox Stripe Gateway > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以隐藏方式显示密钥，并显示状态（例如许可证有效的截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此商店中移除密钥）。它们下方有一行 Product: presta-payment-stripe 和链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。区块中的文字会跟随后台语言显示（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。更改商店地址后，或在账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后一次已知的状态。
一个密钥只能用于一个域名：即主商店的域名，多店铺设置中也是如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 Stripe。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账页面进行测试。提醒会出现在 Modules > Module Manager 的 Alerts 标签中。现有订单不受影响：已经开始的付款仍会被确认，退款也仍然可以进行。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台时，状态会自动重新检查：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Stripe：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否有私密密钥：测试模式需要 Test Secret Key，正式模式需要 Live Secret Key。缺少密钥时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客所在客户组。
付款已完成，但没有创建订单：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 的请求。
保存时出现值看起来不对的警告：有密钥被粘贴到了错误的字段中。私密密钥以 sk_test_ / rk_test_ 或 sk_live_ / rk_live_ 开头，Webhook 签名密钥以 whsec_ 开头。
顾客选择 Stripe 时看到错误：请开启 Logging，并查看模块页面中的 Log 字段。密钥错误时会提示付款方式配置不正确。低于 Stripe 在该币种下最低金额的订单总额（例如 0.50 EUR）无法通过 Stripe 付款。
测试付款不会确认正式付款：测试付款与正式付款是分开的。将 Test Mode 切换到您想要的模式，并使用该模式的密钥和 Webhook。
付款后订单处于 Stripe payment on hold 状态：请阅读 Stripe payment 区块中的备注（参见订单状态），然后处理订单或退还付款。
退款失败并提示与模式相关的信息：付款是在测试或正式模式下完成的，而该模式的私密密钥未设置。请输入该密钥后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox Stripe Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，网关设置和日志会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Stripe 交易和退款，以及订单状态 Awaiting Stripe payment 和 Stripe payment on hold，始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Stripe 是其各自所有者的商标。本模块与 Stripe 没有关联，也未获得 Stripe 的认可。