VibeFox Klarna for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。未安装 WooCommerce 时，插件无法激活。

PHP：8.0 或更高版本。

HTTPS：Klarna 要求正式付款必须使用 HTTPS。

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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_klarna_payment 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Klarna Payments > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 选择您的 Klarna 商户账户所属的 API region。

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

7. 输入 Klarna Merchant Portal 中的正式用户名和密码，取消勾选 Test mode，并选择订单的扣款时机（默认：订单标记为「已完成」时）。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > Klarna Payments。页面标题旁会显示 TEST MODE 或 LIVE 标识。当当前模式的用户名或密码缺失时（此时 Klarna 会在结账时隐藏），页面会发出警告；当所选 API 区域不销售店铺货币时，页面也会发出警告。在付款方式列表中，在输入当前模式的凭据之前，Klarna 会标记为需要设置；测试模式开启期间，还会显示测试模式标识。

常规

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: Use the Klarna playground (test credentials, no real payments)。默认：开启。测试模式开启时，结账页面会显示 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 密码（共享密钥）。

订单管理

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

Capture:顾客被扣款的时机。仅已扣款的金额可以退款。扣款失败时，订单会被置为「保留」并附带备注。

When the order is Completed (recommended):将订单标记为「已完成」时扣款（默认），即发货时扣款。扣款金额为订单总额减去已扣款金额，且不超过仍处于授权状态的金额。

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」下单的订单）发送至本节显示的通知 URL。URL 格式如下：https://your-site/wc-api/wc_kl_payment/。该 URL 会自动随每笔订单发送，因此无需在 Klarna 中进行任何设置。通知内容绝不被视为可信：每条通知都会通过 Klarna Order Management API 进行验证，且 Klarna 订单必须引用本店铺的这笔订单。插件会根据 Klarna 报告的结果执行操作：

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

REJECTED or STOPPED：该笔购买未通过欺诈审核。订单将变为「失败」。

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

如果您在取消或退款订单之后，Klarna 才接受该笔购买，订单不会重新打开，Klarna 授权将被释放。

高级

Debug log: Log API calls and payment events，位于 WooCommerce > Status > Logs，来源为 wcp_klarna_payment。错误始终会被记录。日志绝不包含凭据或顾客数据。默认：关闭。

Uninstall: Delete the plugin settings and logs when the plugin is deleted。订单数据（Klarna 订单 ID）始终保留。默认：关闭。

结账

顾客选择付款方式（默认为 Klarna），Klarna 小部件会加载到结账页面中。顾客可在此根据 Klarna 提供的选项选择立即付款、先买后付或分期付款。顾客点击「下订单」时，Klarna 会在小部件中授权该笔购买。在结账区块中，Klarna 会话会先以最终购物车进行更新，因此之后对配送或总额的更改不会导致 Klarna 拒绝订单。随后，插件会以 WooCommerce 订单的商品行、总额和地址在服务器端创建 Klarna 订单。

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

ACCEPTED：订单立即被标记为已付款，顾客将进入「订单已接收」页面。金额已授权，并将根据 Capture 设置进行扣款。

PENDING：订单会被置为「保留」，直到收到 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.，或者在授权已过期时，提示顾客重新点击「下订单」。详细信息会添加到订单备注和日志中。如果顾客的账单国家和币种与您所在区域的任何 Klarna 市场都不匹配，顾客会看到 Klarna is not available for your billing country and currency. Please choose another payment method.

该付款方式适用于经典结账、结账区块和 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。

本插件不支持 Klarna Checkout（KCO，完全替代结账页面）、Klarna Express Checkout 按钮、On-site messaging 或 Sign in with Klarna，也不支持订阅、保存的付款方式以及按订单行部分扣款。订单创建后再编辑订单时，订单行不会重新发送给 Klarna。

订单与退款

订单状态

Processing or Completed:Klarna 已接受该笔购买。WooCommerce 会为已付款订单设置常规状态。订单备注会显示 Klarna 订单 ID 以及扣款时间。交易 ID 即 Klarna 订单 ID。订单扣款后，备注会显示已扣款金额和扣款 ID。

On hold:该笔购买正在等待欺诈审核，Klarna 返回了意外的欺诈状态，Klarna 报告的金额或币种与订单不符，或扣款失败。订单备注会说明具体原因。

Failed:Klarna 在欺诈审核后拒绝或停止了该笔购买。请勿发货。

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

扣款

使用 When the order is Completed 时，将订单标记为「已完成」会扣除订单总额。如果扣款失败（例如，订单编辑后总额超过了已授权金额），订单会被置为「保留」，备注会注明顾客未被扣款，且顾客不会收到「已完成订单」邮件。请解决问题后将订单重新标记为「已完成」以重试，或在 Klarna Merchant Portal 中扣款。

退款

打开订单，点击 Refund，输入金额后点击 Refund via Klarna Payments。已扣款金额支持全额和部分退款，上限为已扣款金额减去已退款金额。退款会发送至下单时所在的环境和区域，因此必须已设置该环境的凭据。如果 Klarna 不接受退款，WooCommerce 会显示错误，且不会记录任何退款。退款成功后，会将 Klarna 退款 ID 添加到订单备注中。重试的退款绝不会重复执行。

尚未扣款的订单无法退款：请改为取消订单以释放授权。在 Klarna Merchant Portal 中进行的退款不会同步回 WooCommerce。

许可证密钥

本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Klarna Payments 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 可重新检查状态，Change key 用于输入其他密钥，Remove key 用于从本站点移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额，请在 vibefox.net 账户中释放名额。

没有有效密钥时，结账页面不会向顾客显示 Klarna。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的商店管理员仍可看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。已有订单不受影响：通知仍会继续处理，扣款、取消和退款也仍可正常进行。

许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

结账时未显示 Klarna：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式的凭据是否已填写：测试模式下填写测试用户名和密码，正式模式下填写正式凭据。顾客的账单国家必须是您 API region 中的 Klarna 国家，并且须以该国家的货币付款（例如，瑞典顾客必须以 SEK 付款）。

付款已完成，但订单仍为 On hold：该笔购买正在等待 Klarna 的欺诈审核，收到 Klarna 通知后订单才会更新。请检查您的站点能否接收 Klarna 发送到设置中所示通知 URL 的请求，并确认订单下单时所在环境的凭据仍已填写。查看 WooCommerce > Status > Logs，来源为 wcp_klarna_payment。

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

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

通知返回 mismatch_ref：Klarna 订单未引用本店铺订单。订单不会被更改。

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

扣款失败，订单 On hold：请阅读订单备注。订单总额可能超过了仍可授权的金额，Klarna 订单可能尚未被接受，或授权可能已过期。请解决问题后将订单重新标记为「已完成」，或在 Klarna Merchant Portal 中扣款。

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

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。

卸载

停用插件会保留所有数据。如需删除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。网关设置和日志（来源为 wcp_klarna_payment）仅在 Uninstall（Delete the plugin settings and logs when the plugin is deleted）开启时才会删除。否则，它们会保留，以便日后重新安装时使用。已有订单会保留其付款备注和交易 ID。

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