VibeFox Klarna for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

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

货币：您所在地区的 Klarna 货币：欧洲为 EUR、SEK、NOK、DKK、GBP、CHF、PLN、CZK、HUF 或 RON；北美为 USD、CAD 或 MXN；大洋洲为 AUD 或 NZD。该货币必须已在 System > Localisation > Currencies 中添加。

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

安装

下载文件是一个压缩包，包含两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包中有 README.txt、OpenCart 3 安装包 wcp_klarna_payment-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_klarna_payment.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

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

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

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

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 6 步输入许可证密钥、API region、凭据和收款方式。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见通知）。

新安装时，支付方式默认关闭，测试模式默认开启。每笔 Klarna 订单都会发送通知 URL，因此无需在 Klarna 中进行任何设置。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Klarna Payments > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示 TEST MODE: Klarna playground, no real payments. 或 LIVE: real Klarna payments.。如果当前模式的用户名或密码缺失（此时结账时会隐藏 Klarna），或者商店的默认货币不被所选 API 区域的 Klarna 支持，页面会发出警告。如果没有修改扩展的权限，页面仅显示设置，无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数（允许负数），Total 须为 0 或更大的数字，且 API 区域、收款方式、地理区域和订单状态必须有效。否则不会保存任何内容，页面会指出出错的字段。缺少凭据不影响保存。

Klarna 支付

Enable/Disable：开启或关闭该支付方式。默认：关闭。只有当当前模式的用户名和密码已填写，且客户的账单国家属于所选 API 区域的 Klarna 市场，并以该国货币付款时，结账页面才会显示 Klarna。

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

Description：在 Confirm Order 步骤中显示给客户、位于 Klarna 小部件上方的文字。默认：Pay now, later or in instalments with Klarna.

Sort Order：Klarna 在结账页面支付方式中的位置。可留空或输入整数。

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

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

API 凭据

Klarna API 凭据（用户名和密码）在 Klarna Merchant Portal 的 Settings > Klarna API credentials 下创建（该处有相应部分的链接）。测试凭据来自 Playground 门户：欧洲一组，北美和大洋洲一组。每个 API 区域都有各自的凭据。

Test mode：使用 Klarna Playground 环境（测试凭据，无真实付款）。默认：开启。测试模式开启时，客户在 Confirm Order 步骤会看到 TEST MODE: Klarna playground, no real payment is made.。订单会保留其下单时所在的环境：Playground 订单的收款和退款始终使用测试凭据。

API region：您 Klarna 商户账户所属的区域。客户只能从该区域的国家使用 Klarna 付款，并以其所在国家的货币支付。国家取自订单的支付地址。

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

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

Test username (UID)：Playground API 用户名。

Test password：Playground API 密码（共享密钥）。

已保存的密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it.。只有在需要更改时才输入新值。要删除已保存的密码，请勾选字段下方的 Clear the saved password on save，然后点击 Save。

订单管理

已下单的 Klarna 订单是一项授权：只有在订单被收款（capture）后才会向客户扣款。未收款的授权会过期，通常为 28 天，因此请及时发货，或使用自动收款。

Capture：客户被扣款的时机。只有已收款的金额才能退款。

Cancellation：当尚未收款的订单被设置为下方的 Canceled Status 时，取消 Klarna 订单（释放授权）。默认：开启。

订单状态

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 Klarna 为小部件中确认的购买创建了 Klarna 订单之后，订单才会获得状态。Klarna 未批准的购买会使订单保持无状态，客户停留在 Confirm Order 步骤。下方每个字段都列出您的 OpenCart 订单状态。

Order Status After Payment：Klarna 已接受该购买（欺诈状态 ACCEPTED）。款项已按 Capture 的设置进行授权和收款。默认：Processing。

Awaiting Fraud Review Status：Klarna 将订单记为 PENDING（欺诈审核）。在 Klarna 的通知接受该订单之前请勿发货；订单会自动更新。默认：Pending。

On Hold Status：Klarna 返回了意外的欺诈状态，或 Klarna 报告的金额或货币与订单不符。备注会说明需要检查什么。默认：Pending。

Payment Error Status：Klarna 在欺诈审核后拒绝或终止了该购买。请勿发货。默认：Failed。

Canceled Status：将尚未收款的订单设置为此状态会取消 Klarna 订单（参见 Cancellation）。Klarna 报告 Klarna 订单已取消、过期或关闭时，也会设置此状态。默认：Canceled。

Refunded Status：在订单页面的 Klarna 标签中，已收款金额被全额退款。部分退款仅添加备注。默认：Refunded。

OpenCart 没有用于欺诈审核或暂挂付款的专用状态。您可以在 System > Localisation > Order Statuses 中创建它们，并在此处选择。

通知

Klarna 会将欺诈审核的结果（以待处理方式下的订单）发送到 Notification URL 中显示的地址。在 OpenCart 3 中，它的形式为 https://your-store/index.php?route=extension/payment/wcp_klarna_payment/notification；在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_klarna_payment/payment/wcp_klarna_payment.notification。每笔订单都会自动发送该 URL，因此无需在 Klarna 中进行任何配置。通知内容永远不被信任：每条通知都会使用订单下单时所在环境和区域的凭据，通过 Klarna Order Management API 进行验证，并且 Klarna 订单必须引用此订单号。扩展依据 Klarna 报告的内容采取行动：

如果您在取消或退款订单之后，Klarna 又接受了该购买，订单不会被重新打开，Klarna 授权会被释放。商店处于维护模式时，通知仍然有效：OpenCart 3 允许支付扩展的请求通过，而在 OpenCart 4 中，扩展会添加一个启动动作，允许通知和客户从 Klarna 的返回请求通过。

高级

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

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

Delete data on uninstall：开启时，卸载扩展会删除网关设置、日志以及临时的小部件会话。订单数据（Klarna 订单 ID、退款）始终保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤，客户选择支付方式（默认为 Klarna）。OpenCart 在 Confirm Order 步骤创建订单，此时仍无状态。在此步骤，客户会看到 Klarna 标识、您的说明以及 Klarna 小部件。扩展会根据该订单在服务器上创建 Klarna 会话：包括带选项的商品、礼品券、运费、优惠券、代金券和积分抵扣、税费以及地址。在小部件中，客户可以根据 Klarna 提供的选项选择立即付款、稍后付款或分期付款。客户点击 Confirm Order 时，Klarna 会在小部件中授权该购买，扩展则使用 OpenCart 订单的数据在服务器端创建 Klarna 订单。Klarna 订单会将 OpenCart 订单号作为商户参考号。

在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中）。此时 Klarna 小部件会出现在结账页面底部的订单确认区块中，位于 Confirm Order 按钮上方。OpenCart 4 没有礼品券，因此不会发送给 Klarna。OpenCart 4 默认不要求付款地址；此时扩展会将配送地址作为付款地址，并将其国家作为购买国家。

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

如果 Klarna 无法接受订单，客户会停留在 Confirm Order 步骤，并看到简短提示，例如 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.，或者在授权已过期时，提示客户再次点击 "Confirm Order"。详细信息会写入日志，订单会附带备注。如果客户的国家和货币与您所在区域的 Klarna 市场不匹配，客户会看到 Klarna is not available for your billing country and currency. Please choose another payment method.

重复点击、刷新页面，或在第二个浏览器标签页中为同一购物车付款，都不会创建第二个 Klarna 订单（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账的订单，因此在购买被拒绝后，客户会支付同一订单）。如果 Klarna 已批准购买但无法设置订单状态，客户会看到 Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. 下一次尝试或 Klarna 的通知将根据已保存的 Klarna 订单设置状态，无需重新授权。购物车发生变化（包括数量变化）时，视为需要单独付款的新购物车。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在未付款的情况下已被关闭（例如您取消了订单），客户会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. 如果订单已经生成且购物车中现在有其他商品，提示为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. 两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。这些提示显示在结账页面上方。

该扩展不包含 Klarna Checkout（KCO，即完整替换结账页面）、Klarna Express Checkout 按钮、On-site messaging 或 Sign in with Klarna，不支持订阅或已保存的支付方式，也不支持按订单行部分收款。订单下达后，如果您编辑订单，订单行不会再次发送给 Klarna。

订单和退款

订单状态

No status (missing order)：客户未完成 Klarna 授权，或 Klarna 拒绝了该购买。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders 时才会显示此类订单。

Order Status After Payment（默认 Processing）：Klarna 接受了该购买。备注会显示 Klarna 订单 ID 以及收款时间。

Awaiting Fraud Review Status（默认 Pending）：该购买正在等待 Klarna 的欺诈审核。Klarna 的通知会将订单转为 Order Status After Payment、Payment Error Status 或 Canceled Status。

On Hold Status（默认 Pending）：Klarna 返回了意外的欺诈状态，或 Klarna 报告的金额或货币与订单不符。备注会说明原因。请在 Klarna Merchant Portal 中检查订单。

Payment Error Status（默认 Failed）：Klarna 在欺诈审核后拒绝或终止了该购买。请勿发货。

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

Refunded Status（默认 Refunded）：已收款金额通过扩展被全额退款。

备注是订单 History 中的条目，客户看不到。它们以 Klarna 一词开头。

Capture

选择 When the order is shipped / completed 时，在 Sales > Orders 中（通过 Add History）将订单状态更改为已完成状态，会在保存新状态之前收取订单总额。如果 Klarna 拒绝收款（例如在编辑订单后，订单总额超过了仍被授权的金额），状态不会改变，不会发送邮件，订单页面会显示原因而不是成功提示。备注会说明客户并未被扣款。请解决问题后再次更改状态以重试，或在 Klarna Merchant Portal 中收款并将 Capture 改为手动。收款成功会添加一条备注，其中包含已收款金额和收款 ID。新订单的首个状态，以及从一个已完成状态切换到另一个已完成状态，都不会触发收款。扩展已安装但被关闭时，收款和取消仍会正常工作。在 OpenCart 4.1 中，被拒绝的状态更改也会在订单页面显示原因；在 OpenCart 4.0.x 中，状态同样不变，但原因仅显示在订单历史的备注中。

VibeFox Klarna Payments 标签

在 Sales > Orders 中打开一笔使用 Klarna 付款的订单。在订单页面底部，紧邻 History 和 Additional，VibeFox Klarna Payments 标签会显示 Klarna 订单 ID（及其环境和区域）、测试订单的 Playground 标签、欺诈状态和 Klarna 状态、Authorized 金额、Captured / refunded 金额、退款表单、退款历史以及该订单的 Klarna notes。该标签仅对有权访问此扩展的用户显示。

退款

在 VibeFox Klarna Payments 标签中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via Klarna。确认提示 Refund this amount through Klarna? This cannot be undone.。支持对已收款金额进行全额和部分退款，上限为 Klarna 报告的已收款金额减去已退款金额。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。退款会发送至下单时所在的环境和区域，因此必须已设置该环境的凭据。如果 Klarna 不接受退款，标签会显示错误，且不会记录任何退款。成功的退款会连同 Klarna 退款 ID 一起添加到退款历史和备注中。全额退款会将订单设置为 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。重试的退款绝不会被执行两次。

尚未收款的订单无法退款：请改为取消该订单以释放授权。将 Capture 设为手动后，商店无法得知您在 Klarna Merchant Portal 中收取了多少金额。此时退款表单会以空金额显示，提交时由 Klarna 核对金额。

Sales > Returns 中的商品退货不会通过 Klarna 退还款项。在 Klarna Merchant Portal 中进行的退款不会添加到该标签中，但会计入 Klarna 仍允许退款的金额。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Klarna Payments 位于 Extensions > Extensions > Payments > VibeFox Klarna Payments > Edit 页面的最上方，位于设置之上。将密钥粘贴到 License key 并点击 Activate。此后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方有 Product: opencart-payment-klarna 一行，以及打开您 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 账户中释放该名额。

没有有效密钥时，结账页面不会向客户显示 Klarna。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在商店中看到该支付方式，并标有 (unlicensed — visible to admins only)，这样您可以在购买密钥之前进行设置和测试。在 OpenCart 4 中没有此预览：商店看不到管理员登录状态，因此没有有效密钥时，支付方式对所有人都隐藏。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：Klarna 通知仍会被处理，订单仍可收款、取消和退款。

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

故障排除

Klarna 未出现在结账页面：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式的凭据是否已填写：测试模式下填写测试用户名和密码，正式模式下填写正式凭据。如果凭据缺失，设置页面会显示警告。客户的付款国家必须是您 API region 中的 Klarna 国家，并以该国货币付款（例如，瑞典客户必须使用 SEK 付款）。另外请检查支付地址是否在所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍停留在 Awaiting Fraud Review Status：该购买正在等待 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. 请检查当前模式的凭据以及客户的国家和货币。

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

退款失败：请阅读标签中的信息。订单可能尚未收款（请改为取消），金额可能超过仍可退款的金额，或订单所在环境的凭据可能缺失。

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

客户看到 This order is already being paid：同一购买的另一个请求正在处理中，例如重复点击。请稍候片刻，并检查订单是否已获得状态。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Klarna Payments 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Order statuses 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中还包括其启动动作，该动作在维护模式下允许通知和客户的返回请求通过），因此状态更改将不再收款或取消 Klarna 订单。如果 Delete data on uninstall 已开启，其他网关设置（标题、描述、测试模式、API 区域、凭据、收款、取消、日志记录）、日志以及临时小部件会话都会被删除。如果未开启，这些内容会保留，以便之后重新安装时使用。Klarna 订单和退款始终会保留，因此之前的订单在重新安装后仍可收款和退款。现有订单会保留其付款备注。

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

Klarna 是其所有者的商标。本扩展与 Klarna 无关联，也未获得 Klarna 的认可。