VibeFox Klarna for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。模块拒绝在更早的 PHP 版本上安装。

Klarna 商户账户：您需要某一 API 区域的 Klarna 商户账户 API 凭据（用户名和密码），以及 Klarna 测试环境门户的测试凭据（参见配置）。每个 API 区域都有各自的凭据。每个店铺只能使用一个商户账户（一个 API 区域）。

货币：您所在区域的 Klarna 货币：欧洲为 EUR、SEK、NOK、DKK、GBP、CHF、PLN、CZK、HUF 或 RON；北美为 USD、CAD 或 MXN；大洋洲为 AUD 或 NZD。

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure；或稍后在模块列表中找到 VibeFox Klarna Payments，然后点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，于 License key 处输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。

4. 选择您的 Klarna 商户账户的 API region。

5. 输入 Klarna 测试环境门户中的测试用户名和密码，保持 Test mode 开启，打开 Enable/Disable，点击 Save，然后下一笔测试订单。

6. 输入 Klarna Merchant Portal 中的正式用户名和密码，关闭 Test mode，并选择订单的扣款时机（默认：发货时）。

安装时，模块会创建两个订单状态：Awaiting Klarna fraud review 和 Klarna payment on hold。两者都不计为已付款，也不会发送电子邮件。PrestaShop 会为所有货币、国家和客户组提供一个新的支付模块。您可以在 Payment > Preferences 中对其进行限制。

配置

所有设置都在模块页面中：Modules > Module Manager > VibeFox Klarna Payments > Configure。每个部分都有各自的 Save 按钮，点击后会保存整个页面。字段上方页面会显示 TEST MODE: Klarna playground, no real payments. 或 LIVE: real Klarna payments. 如果当前模式的用户名或密码缺失（此时 Klarna 会在结账时隐藏），或店铺默认货币在所选 API 区域未由 Klarna 销售，页面会发出警告。

Klarna Payments

Enable/Disable：Enable Klarna Payments 用于开启或关闭该支付方式。默认：关闭。

Title：顾客在付款步骤中看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Klarna。必填。

Description：显示在 Klarna 小部件上方、呈现给顾客的文字。默认：Pay now, later or in instalments with Klarna.

API 凭据

Klarna API 凭据（用户名和密码）在 Klarna Merchant Portal（portal.klarna.com）中创建，路径为 Settings > Klarna API credentials。测试凭据来自测试环境门户：欧洲使用 playground.eu.portal.klarna.com，北美和大洋洲使用 playground.us.portal.klarna.com。

Test mode：使用 Klarna 测试环境（测试凭据，不产生真实付款）。默认：开启。在测试模式开启期间，顾客会在支付方式下方看到 TEST MODE: Klarna playground, no real payment is made. 订单会保留其下单时所在的环境：测试环境订单的扣款和退款始终使用测试凭据。

API region：您的 Klarna 商户账户所在的区域。顾客只能从该区域的国家、以其所在国家的货币使用 Klarna 付款。国家取自购物车的账单地址。

Europe：奥地利、比利时、芬兰、法国、德国、希腊、爱尔兰、意大利、荷兰、葡萄牙、斯洛伐克和西班牙（EUR），瑞典（SEK），挪威（NOK），丹麦（DKK），英国（GBP），瑞士（CHF），波兰（PLN），捷克（CZK），匈牙利（HUF），罗马尼亚（RON）。默认。

North America (US, CA, MX)：美国（USD），加拿大（CAD），墨西哥（MXN）。

Oceania (AU, NZ)：澳大利亚（AUD），新西兰（NZD）。

Live username (UID)：正式 API 用户名，例如 PK12345_abcdef012345。

Live password：正式 API 密码（共享密钥）。

Test username (UID)：测试环境 API 用户名。

Test password：测试环境 API 密码（共享密钥）。

已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved passwords：勾选某个密码并点击 Save 即可将其删除。字段留空则保留已保存的值。

订单管理

已下的 Klarna 订单属于授权：只有在订单扣款时才会向顾客收费。未扣款的授权通常会在 28 天后过期，因此请及时发货，或使用自动扣款。

Capture：顾客何时被扣款。只有已扣款的金额才可以退款。

When the order is shipped (recommended)：将订单改为 Shipped 或 Delivered 等发货状态时扣款（默认）。扣款金额为订单总额减去已扣款金额，且不超过仍处于授权状态的金额。如果扣款失败，订单状态不会改变，原因会显示在订单页面上。

Immediately (auto capture)：立即向顾客扣款，适用于数字商品或服务。

Manually in the Klarna portal：模块不进行扣款。请在 Klarna Merchant Portal 中为订单扣款。

Cancellation：Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled。默认：开启。

通知

Klarna 会将欺诈审核的结果（以 "pending" 方式下单的订单）发送至 Notification URL 中显示的地址。使用友好 URL 时，地址形如 https://your-shop/module/wcp_klarna_payment/notification，并可能带有语言代码，例如 /en/。该 URL 会随每笔订单自动发送，因此无需在 Klarna 中做任何设置。通知内容永远不被信任：每条通知都会使用下单所在环境和区域的凭据，通过 Klarna Order Management API 进行验证，而且该 Klarna 订单必须指向本店铺的购物车。模块根据 Klarna 报告的结果执行相应操作：

ACCEPTED：Klarna 接受了该笔购买。在核对金额和币种后，订单被标记为已付款。

REJECTED or STOPPED：该笔购买未通过欺诈审核。订单变为 Payment error。

Klarna order CANCELLED, EXPIRED or CLOSED：顾客未被扣款。订单被取消。

如果您在取消或退款之后，Klarna 又接受了该笔购买，订单不会被重新打开，Klarna 授权会被释放。即使店铺处于维护模式，通知仍然有效，并且不受店铺国家限制的阻挡。

高级

Debug log：将 API 调用和付款事件记录到模块文件夹中的 logs/wc_kl_debug.log.php。该文件无法通过网页打开。错误始终会被记录。日志绝不包含凭据、授权令牌或顾客数据。默认：关闭。

Log：显示日志的大小和最新条目，并提供清空按钮。

Uninstall：卸载模块时删除模块设置和日志。订单数据（Klarna 订单 ID、退款）始终保留。默认：关闭。

结账

在付款步骤中，顾客选择支付方式（默认为 Klarna，带有 Klarna 标识），Klarna 小部件会在付款步骤内加载。模块由服务器根据购物车创建 Klarna 会话。顾客在小部件中可根据 Klarna 提供的选项，选择立即付款、先买后付或分期付款。顾客下单时，Klarna 会话首先以最终购物车更新，然后 Klarna 在小部件中授权该笔购买。之后，模块会使用购物车中的订单行、总额和地址，由服务器创建 Klarna 订单。购物车折扣会作为单独一行发送给 Klarna。在 Klarna 给出答复之前，不会存在任何订单。

结果取决于 Klarna 的欺诈状态：

ACCEPTED：订单以 Payment accepted 创建，顾客会看到标准的订单确认页面。金额已授权，并将按照 Capture 设置进行扣款。

PENDING：订单以 Awaiting Klarna fraud review 创建，直到 Klarna 的通知到达。在此之前请勿发货。

REJECTED：不会创建订单。顾客停留在结账页面，并看到 Klarna could not approve this purchase. Please choose another payment method.

如果 Klarna 无法接受该订单，顾客会停留在结账页面，并看到简短的提示，例如 Klarna could not accept this order. Please check your billing details or choose another payment method.、Klarna did not respond. Please try again in a moment.，或者在授权已过期时，提示顾客再次点击 "Place order"。详细信息会写入日志。如果顾客的国家和货币与您所在区域的任何 Klarna 市场不匹配，顾客会看到 Klarna is not available for your billing country and currency. Please choose another payment method.

重复点击绝不会为同一购物车创建第二笔 Klarna 订单。如果在 Klarna 答复期间购物车发生了变化（例如在另一个浏览器标签页中），订单会以 Klarna payment on hold 创建，并附带备注。如果 Klarna 已批准该笔购买，但订单无法创建，顾客会看到 Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. 下一次尝试或 Klarna 的通知会根据已保存的 Klarna 订单创建订单，无需重新授权。

Klarna Merchant Portal 中的 Klarna 订单会将购物车编号作为商户参考号，因为下单时 PrestaShop 订单尚不存在。

本模块不提供 Klarna Checkout（KCO，完整替换结账页面）、Klarna Express Checkout 按钮、On-site messaging 或 Sign in with Klarna，也不支持订阅、保存的付款方式，以及按订单行部分扣款。订单下单后如果您再编辑订单，订单行不会重新发送给 Klarna。

订单与退款

Order statuses

No order yet：顾客尚未完成 Klarna 授权，或 Klarna 拒绝了该笔购买。此时只存在购物车。

Payment accepted：Klarna 接受了该笔购买。付款以 Klarna 订单 ID 作为交易 ID 记录，并且一条私人备注会显示 Klarna 订单 ID 以及扣款时间。

Awaiting Klarna fraud review：该笔购买正在等待 Klarna 的欺诈审核。Klarna 的通知会将订单转为 Payment accepted、Payment error 或 Canceled。

Klarna payment on hold：Klarna 返回了意外的欺诈状态，或 Klarna 报告的金额或币种与订单不符。备注会说明原因。请在 Klarna Merchant Portal 中检查该订单。

Payment error：欺诈审核后，Klarna 拒绝或中止了该笔购买。请勿发货。

Canceled：您取消了订单，或 Klarna 报告该 Klarna 订单已取消、过期或关闭。开启 Cancellation 后，取消尚未扣款的订单会同时取消 Klarna 订单并释放授权，因此顾客不会被扣款。已扣款的订单不会在 Klarna 中取消：请退款以退还款项。

Refunded：已扣款金额已通过本模块全额退款。

Capture

选择 When the order is shipped 时，将订单改为发货状态会在保存新状态之前扣除订单总额。如果 Klarna 拒绝扣款（例如订单在编辑后总额超过了授权金额），订单状态不会改变，也不会发送电子邮件，原因会显示在订单页面和一条备注中：顾客并未被扣款。请解决问题后再次更改状态以重试，或在 Klarna Merchant Portal 中扣款并将 Capture 改为手动。在生产模式下的 PrestaShop 8 中，后台可能仍会保存该状态；此时模块会改为设置 Klarna payment on hold 并附带备注，确保订单永远不会在未扣款的情况下显示为已发货。成功扣款会添加一条备注，记录扣款金额和扣款 ID。

Klarna payment 区块

订单页面会显示一个 Klarna payment 区块，包含 Klarna 订单 ID、其环境和区域、测试订单的 Playground 标记、欺诈状态和 Klarna 状态、已授权金额、已扣款和已退款金额以及退款记录。

退款

在 Klarna payment 区块中输入金额（会预先填入尚未退款的金额），可选填原因，然后点击 Refund via Klarna。确认提示 Refund this amount through Klarna? This cannot be undone. 已扣款金额支持全额和部分退款，上限为 Klarna 报告的已扣款金额减去已退款金额。您需要具备编辑订单的权限；无需具备模块访问权限。退款会发送至下单时所在的环境和区域，因此必须已设置该环境的凭据。如果 Klarna 不接受退款，区块会显示错误，并且不会记录任何退款。成功的退款会添加到退款记录和备注中，并附带 Klarna 退款 ID。全额退款会将订单设为 Refunded；部分退款不会改变订单状态。重试的退款绝不会执行两次。

尚未扣款的订单无法退款：请改为取消该订单以释放授权。当 Capture 设置为手动时，店铺无法得知您在 Klarna Merchant Portal 中扣了多少款。此时退款表单会以空金额显示，Klarna 会在您提交时检查金额。

本模块不会生成贷项单。订单页面上的标准 PrestaShop 退款按钮不会通过 Klarna 退还款项。在 Klarna Merchant Portal 中进行的退款不会添加到该区块中，但会计入 Klarna 仍允许退款的金额。

许可证密钥

本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Klarna Payments 许可证区块位于 Modules > Module Manager > VibeFox Klarna Payments > Configure 页面中，位于设置上方，是第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以隐藏部分字符的方式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有一行 Product: presta-payment-klarna，以及链接 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 账户中释放名额。

没有有效密钥时，Klarna 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该支付方式对您也是隐藏的：您可以在购买密钥之前完成模块设置，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：Klarna 通知仍会被处理，订单仍可扣款、取消和退款。

许可证到期后，模块仍会继续运行，但更新和支持需要续期。在后台工作时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。

故障排除

结账时未显示 Klarna：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的凭据是否已填写：测试模式下填写测试用户名和密码，正式模式下填写正式凭据。缺失时设置页面会显示警告。顾客的账单国家必须是您 API region 中的 Klarna 国家，并且顾客须使用该国家的货币付款（例如，瑞典顾客必须使用 SEK 付款）。在 Payment > Preferences 中，请检查模块是否允许用于购物车货币、顾客所在国家和顾客组。

付款已完成，但订单仍停留在 Awaiting Klarna fraud review：该笔购买正在等待 Klarna 的欺诈审核，订单会在 Klarna 的通知到达后更新。请检查您的店铺能否接收 Klarna 发送到设置中所示 Notification URL 的请求，并确认下单所在环境的凭据仍已填写。开启 Debug log，并查看模块页面上的 Log 字段。

通知返回 Not configured：下单所在环境（测试或正式）的凭据缺失，因此无法验证通知。请填写这些凭据。Klarna 会重试通知。

通知返回 Verification failed：无法通过 Order Management API 读取 Klarna 订单。Klarna 会重试通知。

通知返回 Busy：该订单在同一时刻正被另一个请求更新。Klarna 会重试通知。

通知返回 mismatch_ref 或 Unknown order：该 Klarna 订单未指向本店铺的购物车，或模块不认识该订单。订单不会被修改。

小部件无法加载：顾客会看到 Klarna could not be loaded. Please try again or choose another payment method. 或 Klarna is not available for this purchase. 请检查当前模式的凭据以及顾客的国家和货币。

改为 Shipped 状态被拒绝：Klarna 扣款失败。请在 Klarna payment 区块或备注中查看原因。订单总额可能超出了仍处于授权状态的金额，Klarna 订单可能尚未被接受，或授权可能已过期。请解决问题后再次更改状态，或在 Klarna Merchant Portal 中扣款。

退款失败：请阅读区块中的提示信息。订单可能尚未扣款（此时请改为取消），金额可能超过了仍可退款的上限，或订单所在环境的凭据可能缺失。

顾客看到 This order is already being paid：同一购物车的另一个请求正在进行中，例如重复点击。请稍等片刻，然后检查订单是否已创建。

卸载

进入 Modules > Module Manager，打开 VibeFox Klarna Payments 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态总会被删除。如果 Advanced 部分中的 Uninstall 已开启，模块设置、日志和临时的小部件会话都会被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Klarna 订单和退款，以及 Awaiting Klarna fraud review 和 Klarna payment on hold 订单状态始终会保留，因此之前下的订单在重新安装后仍可扣款和退款。现有订单会保留其付款备注和交易 ID。

Klarna 是其各自所有者的商标。本模块与 Klarna 无关联，也未获得 Klarna 的认可。