VibeFox Klarna for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

PHP: 8.0 以降。古いバージョンの PHP ではモジュールはインストールされません。

Klarna 加盟店アカウント: 1 つの API リージョン用の Klarna 加盟店アカウントの API 認証情報（ユーザー名とパスワード）と、Klarna テスト環境ポータルのテスト用認証情報が必要です（設定を参照）。API リージョンごとに認証情報は異なります。1 つのストアで使用できる加盟店アカウントは 1 つ（API リージョン 1 つ）のみです。

通貨: お住まいのリージョンの Klarna 通貨: ヨーロッパでは EUR、SEK、NOK、DKK、GBP、CHF、PLN、CZK、HUF、RON。北米では USD、CAD、MXN。オセアニアでは AUD、NZD。

VibeFox ライセンスキー: vibefox.net で購入します。1 つのキーは 1 つのドメインで使用できます。

インストール

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 をオフにして、注文をキャプチャするタイミングを選択します（既定: 発送時）。

インストール時に、モジュールは 2 つの注文ステータス 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 を利用できます。国はカートの請求先住所から取得されます。

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: 購入者に請求するタイミングです。返金はキャプチャされた金額に対してのみ可能です。

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 が報告した内容に基づいて動作します:

注文をキャンセルまたは返金した後で Klarna が購入を承認した場合、注文は再度開かれず、Klarna の承認は解放されます。通知はストアがメンテナンスモードの間も機能し、ストアの国制限によってブロックされることはありません。

詳細設定

Debug log: API 呼び出しと支払いイベントを、モジュールフォルダ内の logs/wc_kl_debug.log.php に記録します。このファイルは Web からは開けません。エラーは常に記録されます。ログには認証情報、認可トークン、購入者データが含まれることは決してありません。既定: オフ。

Log: ログのサイズと最新のエントリを表示し、クリアするボタンがあります。

Uninstall: モジュールをアンインストールするときに、モジュールの設定とログを削除します。注文データ（Klarna 注文 ID、返金）は常に保持されます。既定: オフ。

チェックアウト

支払いステップで、購入者は支払い方法（既定は Klarna、Klarna バッジ付き）を選択し、Klarna ウィジェットが支払いステップ内に読み込まれます。モジュールはサーバー上でカートから Klarna セッションを作成します。ウィジェット内で購入者は、Klarna が提供する「今すぐ支払い」「後払い」「分割払い」から選択します。購入者が注文すると、Klarna セッションはまず最終的なカートで更新され、Klarna がウィジェット内で購入を承認します。その後、モジュールはカートの注文明細、合計、住所を使って、サーバー側から Klarna 注文を作成します。カートの割引は Klarna に別の明細行として送信されます。Klarna が応答するまで注文は存在しません。

結果は Klarna の不正審査ステータスによって異なります:

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. が表示されます。

ダブルクリックしても、同じカートに対して 2 つ目の 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 をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認できたステータスで動作を続けます。

1 つのキーは 1 つのドメインで使用できます。ドメインとはメインストアのドメインを指し、マルチストア構成でも同様です。ストアからキーを削除しても、ドメインの枠は解放されません。枠は vibefox.net のアカウントで解放してください。

有効なキーがない場合、Klarna はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. が表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、管理画面にログインしているご自身にも支払い方法は表示されません。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。Klarna の通知は引き続き処理され、注文のキャプチャ、キャンセル、返金も行えます。

ライセンスの期限が切れると、モジュールは引き続き動作しますが、アップデートとサポートには更新が必要です。ステータスは、管理画面での作業中に自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは不要です。モジュールをアンインストールまたはリセットすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

Klarna がチェックアウトに表示されない: ライセンスが有効であること、Enable/Disable がオンであること、有効なモードの認証情報が入力されていることを確認してください。テストモードではテスト用のユーザー名とパスワード、本番モードでは本番用の認証情報です。未入力の場合、設定ページに警告が表示されます。購入者の請求先の国は、API region の Klarna 対応国であり、その国の通貨で支払う必要があります（例: スウェーデンの購入者は SEK で支払う必要があります）。Payment > Preferences で、モジュールがカート通貨、購入者の国、顧客グループに対して許可されているかを確認してください。

支払いは完了したが、注文が Awaiting Klarna fraud review のまま: 購入は Klarna の不正審査を待っており、注文は Klarna の通知が届いたときに更新されます。ストアが設定に表示されている Notification URL で Klarna からのリクエストを受信できること、そして注文が作成された環境の認証情報がまだ入力されていることを確認してください。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 による推奨も受けていません。