VibeFox Omise for PrestaShop — ヘルプ

要件

PrestaShop：8.0 から 9.x。

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

HTTPS：カード入力欄はチェックアウトページに表示されるため、チェックアウトは HTTPS で提供する必要があります。それでもカード情報がストアのサーバーに届くことはありません。Omise は HTTPS のアドレスにのみ Webhook を送信し、銀行の 3-D Secure ページも HTTPS のアドレスである必要があります。

通貨：THB、JPY、SGD、MYR、USD、EUR、GBP、AUD、CAD、CHF、CNY、DKK、HKD のいずれか。これ以外の通貨のカートでは、チェックアウトで決済方法が表示されません。

Omise アカウント：テストモードと本番モードのそれぞれについて、Omise アカウントの公開キーと秘密キーが必要です。キーは Omise ダッシュボードの Settings > Keys で確認できます。また、Settings > Webhooks で Webhook のエンドポイントを設定する必要があります（設定セクションを参照してください）。

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

インストール

1. 管理画面で Modules > Module Manager を開き、Upload a module をクリックします。モジュールの ZIP ファイルを選択してください。

2. アップロードが完了したら Configure をクリックします。後からモジュール一覧で VibeFox Omise Payment を見つけ、Configure をクリックすることもできます。

3. Configure ページ上部のライセンスブロックの License key に VibeFox ライセンスキーを入力し、Activate をクリックしてください（ライセンスキーの項を参照）。

4. Omise のテストキーと本番キーを入力し、設定ページに表示される Webhook URL を Omise ダッシュボードに追加してください（設定セクションを参照）。

5. Enable/Disable をオンにして Save をクリックします。テストモードで、4242 4242 4242 4242 などの Omise テストカードを使って決済を試し、その後 Test mode をオフにしてください。

インストール時、モジュールは 3 つの注文ステータスを作成します：Omise payment authorized、Omise payment on hold、Awaiting Omise payment。決済方法は、インストール時に有効になっている国に表示されます。後から国を追加する場合は、Payment > Preferences でその国にもモジュールを許可してください。通貨や顧客グループによる制限もそこで設定できます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Omise Payment > Configure。各セクションには独自の Save ボタンがあり、ページ全体を保存します。フィールドの上には、テストモードがオンの間 Test mode is on — orders are charged with the test keys, no real money is moved. と表示され、現在のモードの公開キーまたは秘密キーがない場合に警告します。また、Omise がストアの既定通貨を受け付けない場合にも警告します。これらの場合、チェックアウトでは決済方法が非表示になります。

Omise

Enable/Disable: Enable card payments via Omise で決済方法のオン／オフを切り替えます。既定値：off。

Title: チェックアウトで購入者に表示される決済方法の名前です。注文にも保存されます。既定値：Credit / Debit Card。必須。

Description: チェックアウトでカードフォームの上に表示されるテキストです。既定値：Pay securely with your credit or debit card via Omise.

API キー

キーは Omise ダッシュボードの Settings > Keys にあります。テストキーは pkey_test_ と skey_test_ で始まり、本番キーは pkey_ と skey_ で始まります。保存時に、誤った接頭辞のキー（たとえば本番用の欄にテストキーを入力した場合）は保存されません。以前の値が維持され、警告が表示されます。

Test mode: テストキーを使用し、実際の課金は行いません。両方のキーが切り替わります。注文のキャプチャ、返金、ステータス確認は、注文が支払われたモードのキーを常に使用します。既定値：on。

Test public key: テストモードの公開キー、pkey_test_...

Test secret key: テストモードの秘密キー、skey_test_...

Live public key: 本番モードの公開キー、pkey_...

Live secret key: 本番モードの秘密キー、skey_...

保存済みの秘密キーは再表示されません。欄は空のままで、Saved — leave empty to keep it. と表示されます。変更する場合のみ新しい値を入力してください。

Clear saved secrets: 秘密キーにチェックを入れて Save をクリックすると削除されます。空欄の場合は保存済みの値が維持されます。

決済と Webhook

Webhook URL: ストアの Webhook のアドレスです。わかりやすい URL を有効にしている場合、次のような形式になります：https://your-shop/module/wcp_omise_payment/webhook。設定画面に表示されたとおりにコピーし、Omise ダッシュボードの Settings > Webhooks に追加してください（HTTPS のみ）。モジュールは次のイベントを処理します（このセクションにも一覧があります）：

Omise は Webhook に署名しないため、Webhook の内容は信頼されません。課金は、このストアがそのカートのために作成したものである必要があり、そのステータスは、決済モードの秘密キーを使って Omise API から再取得されます。Webhook がない場合、3-D Secure の途中で購入者がブラウザーを閉じた注文は自動的には作成されず、Omise ダッシュボードで行われたキャプチャも、Sync payment status をクリックするまで取り込まれません。

Payment action: カードの金額をどう扱うかを決めます。

Per-charge webhook: 課金ごとに Webhook URL を送信します。複数のストアが 1 つの Omise アカウントを共有している場合に便利です。ストアが HTTPS を使用している場合のみ機能します。そうでない場合は、ダッシュボードの Webhook が使用されます。既定値：off。

詳細設定

Debug log: API リクエストと決済イベントを、モジュールフォルダー内の logs/omise_p_debug.log.php に書き込みます。このファイルは Web から読み取ることはできません。キー、トークン、カード情報は決してログに記録されません。既定値：off。オフの間は、エラーを含め何も書き込まれないため、問題を調べるときにオンにしてください。

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

Delete data on uninstall: オンにすると、モジュールをアンインストールしたときに設定とデバッグログが削除されます。注文の Omise の課金と返金は決済履歴であり、常に保持されます。既定値：off。

チェックアウト

支払いステップで、購入者は決済方法（既定では Credit / Debit Card）を選択し、カードフォームに入力します：Name on card、Card number、Expiry month (MM)、Expiry year (YYYY)、Security code (CVV)。テストモードでは、フォームに TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. と表示されます。購入者が注文を確定すると、Omise.js がブラウザー内でカードを 1 回限りのトークンに変換します。その際、カートの請求先住所が使われます。カード情報がストアに送信されることはありません。入力漏れや無効な項目は、フォームの下に表示されます。例：Please enter a valid card number.

その後、ストアはカートの通貨で、カートの合計金額について秘密キーを使用して課金を作成します。課金の説明はストア名とカート番号で、カート ID は課金のメタデータに保存されます。この時点ではまだ注文は存在しません。銀行が 3-D Secure を要求する場合、購入者は銀行のページに移動してからストアに戻り、結果は Omise API から再取得されます。

注文は、Omise が確認した後にのみ支払い済みとしてマークされます。課金がキャプチャされていること、金額と通貨がカートと一致していることが必要です。購入者には標準の注文確認ページが表示され、Your card payment has been received. と表示されます。Authorize only の場合は、ページに Your card payment has been authorized. The amount will be charged when your order is processed. と表示されます。Omise がまだ支払いを保留中と報告している場合、注文は Awaiting Omise payment として作成され、ページには Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. と表示されます。3-D Secure の直後に支払いを確認できない場合は、Payment confirmation ページに We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. と表示され、Check again ボタンが表示されます。

カードが拒否された場合、注文は作成されません。購入者はチェックアウトに留まり、Payment failed: と理由（例：残高不足、セキュリティコードの誤り、カード発行会社による拒否）が表示されます。同じカートで再試行できます。3-D Secure が失敗した場合も、購入者は理由とともにチェックアウトに戻ります。その間に課金の期限が切れたか取り消された場合、メッセージは The payment was not completed. Please try again. です。

再試行によって二重に課金されることはありません。カートの前回の課金がすでに支払い済みまたは承認済みの場合、新たな課金を行わずに注文が作成されます。完了していない 3-D Secure の試行は、新たな課金の前に期限切れになります。すでに注文があるカートについて 2 件目の課金が支払い済みのまま残っている場合（たとえば別のブラウザータブで）、注文は変更されず、Omise ダッシュボードで返金または取り消しを行うよう通知が表示されます。

Webhook は、ストアがメンテナンスモードの間も動作し、ストアの国による制限でブロックされることもありません。

本モジュールはカード決済のみに対応しています。PromptPay、TrueMoney、モバイルバンキング、分割払いなど、その他の Omise の決済方法、保存済みカードや Omise の顧客、サブスクリプション、部分キャプチャには対応していません。

注文と返金

注文ステータス

No order yet: 購入者は 3-D Secure の途中か、カードが拒否されています。カートのみが存在します。

Payment accepted: 支払いが確認されました。支払いは、Omise の課金 ID（chrg_...）をトランザクション ID として記録され、メモには金額、課金、確認方法（チェックアウト、3-D Secure からの戻り、Webhook、支払いの再試行、手動キャプチャ、手動同期のいずれか）が表示されます。メモは注文に付けられた非公開のメッセージで、管理画面でのみ表示されます。

Omise payment authorized: カードは Authorize only で承認されました。Capture payment または Void authorization を使用してください。

Awaiting Omise payment: Omise はまだ支払いを確認していません。Webhook または Sync payment status で注文が更新されます。

Omise payment on hold: 課金の金額または通貨が注文と一致しません。たとえば 3-D Secure の途中でカートが変更された場合などです。メモには両方の値が表示されます。キャプチャされた支払いは注文に記録されたままです。注文を確認し、対応するか、支払いを返金してください。

Payment error: 保留中の支払いが後で失敗しました。支払い済みの注文が、後から発生した失敗イベントによって格下げされることはありません。

Canceled: 課金の期限が切れたか、承認が取り消されました。

Refunded: 支払いはモジュールを通じて全額返金されました。

すでにキャンセルまたは返金済みになっている注文に、支払い済みまたは承認済みの課金が届いても、注文は再度開かれません。その場合、メモによって、Omise ダッシュボードを確認し、注文を手動で返金または再度開くよう通知されます。

Omise 決済ブロック

注文画面には Omise payment ブロックが表示され、課金 ID、支払い操作、課金ステータス、カードブランドと下 4 桁、請求額・注文額・返金額、テスト決済の Test mode バッジ、返金履歴が含まれます。ブロックのボタンには、注文を編集する権限と、支払いが行われたモードの秘密キーが必要です。モジュールのページへのアクセスは不要です。各操作の結果は、ブロックの上部に表示されます。

Capture payment: 承認された全額をキャプチャし、注文を Payment accepted に設定します。承認済みの注文のみに表示されます。

Void authorization: 承認を取り消します。金額はキャプチャされず、注文は Canceled に設定されます。承認済みの注文のみに表示されます。

Sync payment status: Omise から課金を読み込み、注文を更新します。メモには、Omise で返金された合計も表示されます。

返金

Omise payment ブロックで金額を入力し（まだ返金されていない金額が自動入力されます）、必要に応じて理由を入力して、Refund via Omise をクリックします。確認の質問 Refund this amount through Omise? This cannot be undone. に同意してください。全額返金と部分返金に対応しています。返金は Omise が課金した金額と通貨で行われるため、金額や通貨に不一致があった場合は、注文合計ではなく、購入者が実際に支払った金額まで返金できます。返金は支払いが行われたモードで送信されるため、そのモードの秘密キーが設定されている必要があります。理由は返金と一緒に Omise に保存されます。返金が成功すると、返金履歴とメモに Omise の返金 ID とともに追加されます。全額返金すると注文は Refunded になります。部分返金の場合、ステータスは変わりません。まだキャプチャされていない承認については、全額返金のみ可能で、その場合は承認が取り消されます。Omise が返金を拒否すると、ブロックに Refund failed. と Omise のメッセージが表示され、返金は記録されません。

本モジュールはクレジットメモを作成しません。注文画面の標準の PrestaShop の返金ボタンでは、Omise を通じて返金されません。Omise ダッシュボードで行った返金は PrestaShop に記録されません。Sync payment status で返金合計を確認できます。

ライセンスキー

このモジュールは、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Omise Payment は、Modules > Module Manager > VibeFox Omise Payment > Configure ページの最上部にあるブロックで、設定の上に表示されます。License key にキーを入力し、Activate をクリックしてください。その後、ブロックにはマスクされたキー、ステータス（ライセンスの有効期限日や、ご利用のドメインなど）、そして次のボタンが表示されます：Check now（ステータスを再確認）、Change key（別のキーを入力）、Remove key（このストアからキーを削除）。その下には Product: presta-payment-omise の行と、Manage licenses and domains in your account のリンクがあり、vibefox.net のアカウントを開きます。キーを変更できるのは、このモジュールの Configure 権限を持つ従業員のみです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

キーが受け付けられない場合、ブロックには理由が表示されます。例：キーが見つかりません、このキーは別の製品のものです、ドメインの上限に達しました、または日付付きの ライセンスの有効期限が切れました。ストアのアドレスを変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。

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

有効なキーがない場合、チェックアウトで購入者に Omise の決済方法は表示されません。それでも決済が開始された場合、購入者には この決済方法は利用できません。別の方法を選択してください。 と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、決済方法はご自身にも非表示になります。キーを購入する前にモジュールを設定することはできますが、チェックアウトでテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金も動作します。

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

トラブルシューティング

Omise does not appear at checkout: ライセンスが有効であること、Enable/Disable がオンであること、現在のモードの両方のキーが入力されていること（テストモードではテストキー、それ以外は本番キー）、およびカートの通貨がサポートされている通貨であることを確認してください。キーが不足している場合、設定ページに警告が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループについてモジュールが許可されているか確認してください。

The payment went through, but no order was created or the order stays Awaiting Omise payment: Webhook が機能していません。Omise ダッシュボードで、Webhook URL が Webhook URL に表示されたものと正確に一致し、HTTPS を使用しているか確認してください。既存の注文では Sync payment status をクリックしてください。Webhook の応答を確認するには Debug log をオンにしてください。

Webhook answers Charge ID does not match order or Order not found: イベント内の課金は、このストアがそのカートのために作成したものではありません。何も変更されません。

Webhook answers Order is being processed, retry later or Failed to verify charge: 同じタイミングで別のリクエストによってカートがロックされた、Omise API に接続できなかった、または支払いモードの秘密キーがない、のいずれかです。Omise は Webhook を再試行します。

Webhook answers The order could not be created, retry later: 注文を作成できませんでした。たとえばモジュールが無効になっている場合です。理由を確認するには Debug log をオンにしてください。

The webhook URL shows Method not allowed in the browser: これは正常です。この URL は Omise からのリクエストのみを受け付けます。

Warning on save: key must start with ... or must be a live key: キーが誤った欄に貼り付けられ、保存されませんでした。テストキーは pkey_test_ / skey_test_ で始まり、本番キーは pkey_ / skey_ で始まります。

The customer sees Card payments are temporarily unavailable: キーが誤っているか、カードトークンが別のモードのものです（本番モードでテストトークンを使う、またはその逆）。キーと Test mode を確認してください。

The customer sees We could not reach the payment provider: 課金の作成時に、Omise から有効な応答がありませんでした。課金は作成されている可能性があります。購入者が再度支払う前に、Omise ダッシュボードを確認してください。

The customer sees This order is already being paid: チェックアウトが同時に 2 回送信されました。購入者はしばらく待ち、メールを確認してから再試行してください。

Order is Omise payment on hold after payment: 注文のメモ（注文ステータスを参照）を読み、注文を処理するか、支払いを返金してください。

Refund fails with a message about the mode: 支払いはテストモードまたは本番モードで行われましたが、そのモードの秘密キーが設定されていません。キーを入力して、もう一度お試しください。

Partial refund of an authorized order fails: 支払いは承認のみの状態です。先にキャプチャするか、承認を取り消すために全額返金してください。

アンインストール

Modules > Module Manager に移動し、VibeFox Omise Payment の横のメニューを開いて Uninstall を選択します。このモジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、設定とデバッグログが削除されます。オフの場合、後で再インストールできるように、すべての設定が保持されます。Omise の課金と返金、および注文ステータスの Omise payment authorized、Omise payment on hold、Awaiting Omise payment は常に保持されるため、再インストール後も以前に支払われた注文を返金できます。既存の注文は、支払いのメモとトランザクション ID を保持します。

Omise は、それぞれの所有者の商標です。本モジュールは Omise と提携しておらず、Omise による承認も受けていません。