VibeFox Datatrans for PrestaShop — ヘルプ

要件

PrestaShop: 8.0 から 9.x。

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

Datatrans アカウント: Merchant ID、サーバー間 API パスワード、そして推奨されるウェブフック用の HMAC-SHA256 署名キーが必要です。サンドボックスの認証情報は Datatrans のサンドボックス Web Admin（admin.sandbox.datatrans.com）から、本番の認証情報は本番の Web Admin（admin.datatrans.com）から取得します。サンドボックスと本番は、Merchant ID とキーが異なる別々の Datatrans アカウントです。

到達可能なショップ: Datatrans はウェブフックを自社のサーバーから送信するため、ショップがインターネットから到達可能である必要があります。

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

インストール

1. 管理画面で Modules > Module Manager に進み、Upload a module をクリックします。モジュールの ZIP ファイルを選択します。

2. アップロードが完了したら Configure をクリックします。後から確認する場合は、モジュール一覧で VibeFox Datatrans Gateway を探し、Configure をクリックします。

3. Configure ページの上部にあるライセンスブロックの License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（「ライセンスキー」を参照）。

4. Datatrans のサンドボックス Web Admin からサンドボックスの認証情報を入力します（設定の項を参照）。

5. Enable/Disable をオンにして Save をクリックします。サンドボックスモードでテスト決済を行います。すべて正常に動作したら、本番の認証情報を入力し、Sandbox mode をオフにします。

インストール時に、モジュールは注文ステータス Datatrans payment on hold を作成します。PrestaShop は新しい決済モジュールを、すべての通貨、国、顧客グループに対して既定で有効にします。これらは Payment > Preferences で制限できます。Datatrans は、そこで許可された通貨に対してのみ表示されます。

設定

すべての設定はモジュールのページにあります：Modules > Module Manager > VibeFox Datatrans Gateway > Configure。各セクションには個別の Save ボタンがあり、ページ全体が保存されます。決済方法は有効でも現在の環境に Merchant ID または API パスワードがない場合、ページには Datatrans is hidden at checkout until these settings are filled in: と未入力の項目が表示されます。サンドボックスモードがオンの間は、ページに Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged. と表示されます。

Datatrans

Enable/Disable: Enable Datatrans Payment で決済方法のオン／オフを切り替えます。既定値：オフ。

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

Description: チェックアウトで決済方法の下に表示されるテキストです。既定値：Pay securely via Datatrans.

Sandbox mode: Datatrans のサンドボックスを使用します。テスト決済となり、実際の料金は発生しません。このスイッチは Datatrans のサーバーと、新しい決済に使われる認証情報の両方を切り替えます。既定値：オン。実際の決済を受け付けるにはオフにします。オンの間、購入者には決済方法の下に Sandbox mode: no real payment is taken. と表示されます。返金とキャプチャは、このスイッチの状態に関係なく、常に決済が行われた環境を使用します。

サンドボックスの認証情報

Datatrans のサンドボックス Web Admin（admin.sandbox.datatrans.com）からコピーします。署名キーは同じ画面のセキュリティ設定にあります。

Sandbox merchant ID: サンドボックスアカウントの Merchant ID です。

Sandbox API password: サンドボックスアカウントのサーバー間 API パスワードです。

Sandbox HMAC sign key: ウェブフックの Datatrans-Signature ヘッダーを検証するために使う 16 進数のキーです。これがないと、すべてのウェブフックが Datatrans のステータス API で再確認されます。

本番の認証情報

Datatrans の本番 Web Admin（admin.datatrans.com）からコピーします。

Production merchant ID: 本番アカウントの Merchant ID です。

Production API password: 本番アカウントのサーバー間 API パスワードです。

Production HMAC sign key: 本番のウェブフックの Datatrans-Signature ヘッダーを検証するために使う 16 進数のキーです。これがないと、すべてのウェブフックが Datatrans のステータス API で再確認されます。

保存済みのパスワードと署名キーは二度と表示されません。フィールドは空のままで、Saved — leave empty to keep it. と表示されます。変更する場合にのみ新しい値を入力してください。署名キーは、Datatrans から発行された形式の 16 進数の文字列である必要があります。それ以外の値は保存されません。ページにはエラーが表示され、以前の値が保持されます。他の設定は保存されます。

Clear saved secrets: パスワードまたは署名キーにチェックを入れて Save をクリックすると、削除されます。フィールドを空のままにすると、保存済みの値が保持されます。

Webhook URL

このセクションにはショップのウェブフック URL が表示されます。フレンドリー URL を有効にしている場合、https://your-shop/module/wcp_datatrans_gateway/webhook のような形式になります。先頭に /en/ のような言語コードが付くこともあります。モジュールはすべてのトランザクションでこの URL を Datatrans に送信するため、どこにも入力する必要はありません。Datatrans の Web Admin のウェブフック設定に入力しておくと、そこで行われたキャプチャやキャンセルの更新を受け取れます。設定画面に表示されたとおりに、正確にコピーしてください。Datatrans の Web Admin で行った返金は、注文には反映されません。

ウェブフックはトランザクションの状態を通知します。モジュールは次の状態に応じて動作します：

HMAC 署名キーがある場合、各ウェブフックは決済が行われた環境の署名キーを使って、Datatrans-Signature ヘッダーで検証されます。有効な署名のないウェブフックは拒否されます。署名キーがない場合、モジュールはウェブフックの内容を信頼せず、すべてのウェブフックを Datatrans のステータス API で確認します。ウェブフックがない場合、購入者が決済後にショップへ戻ったときにのみ注文が作成されます。

決済処理

Auto settle: 決済を即座にキャプチャ（確定）します。オフの場合、決済はオーソリのみ行われます。注文は Datatrans payment on hold になり、後で注文の Datatrans ブロックにある Capture Datatrans payment でキャプチャするか、Cancel Datatrans authorization でオーソリを解放します。既定値：オン。

Order status after payment: 決済が確定した後の注文ステータスです。

オーソリのみの決済と、金額や通貨の不一致は、常に Datatrans payment on hold になります。

詳細設定

Logging: 決済イベントと API 呼び出しを、モジュールフォルダー内の logs/datatrans_p_debug.log.php に書き込みます。このファイルは Web から開くことはできません。このスイッチがオフでも、エラーは常に記録されます。キー、カードデータ、購入者データは書き込まれません。既定値：オフ。

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

Delete data on uninstall: オンにすると、モジュールのアンインストール時にモジュールの設定とログが削除されます。注文に残る Datatrans の決済記録（トランザクション、返金）と注文ステータスは、常に残ります。既定値：オフ。

チェックアウト

支払いの段階で、購入者は決済方法（既定では Datatrans）を選び、You will be redirected to the Datatrans payment page to complete the payment securely. という注記を確認します。確定すると、モジュールはカートの合計額をカートの通貨で Datatrans のトランザクションとして作成し、購入者を Datatrans の決済ページへ送ります。ショップの言語がドイツ語、英語、フランス語、イタリア語のいずれかであれば、そのページもその言語で開きます。購入者はそこで、Datatrans アカウントで有効になっている任意の方法で支払います。この時点では、まだ注文は存在しません。

支払い後、購入者はショップに戻ります。注文が支払い済みとしてマークされるのは、Datatrans がそれを確認した後のみです。ウェブフック経由、または購入者が戻った時点でサーバーから Datatrans のステータス API へリクエストすることで確認されます。戻り先のアドレスにはカートの安全なキーが含まれていますが、戻り処理そのものが注文を作成することはありません。その後、注文が作成され、購入者には Your payment with Datatrans has been received. と表示される標準の注文確認ページが表示されます。オーソリのみの決済の場合、ページには Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. と表示されます。Datatrans がまだ決済を確認していない場合、Payment confirmation ページに Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. と表示され、Check again ボタンが付きます。ウェブフックが届き次第、注文が作成されます。

購入者が Datatrans のページでキャンセルすると、チェックアウトに戻り、The payment was canceled. You can try again or choose another payment method. と表示されます。決済が失敗した場合は、The payment was not completed. Please try again or choose another payment method. と表示されます。カートは保持されます。再試行すると新しい Datatrans トランザクションが作成されます。以前の試行の遅延した決済も引き続き認識されます。

Datatrans が決済を開始できない場合、購入者は The payment could not be started. Please try again or choose another payment method. と表示されたままチェックアウトに残ります。技術的な理由はログに記録されます。

ウェブフックは、ショップがメンテナンスモードの間も機能し、ショップの国別制限によってブロックされることもありません。

モジュールは、Datatrans の決済ページで 1 回限りの決済を受け付けます。ショップ上での保存済みカードやエイリアス、サブスクリプション、Lightbox や Secure Fields、設定での決済方法の選択、オーソリの一部キャプチャには対応していません。

注文と返金

注文ステータス

まだ注文はありません: 購入者は Datatrans に移動しましたが、支払いをしていない、決済に失敗した、またはキャンセルされた、あるいは Datatrans がまだ確認していません。カートだけが存在します。

Payment accepted、Delivered、または Datatrans payment on hold: 決済が確定しました。ステータスは Order status after payment に従います。決済は Datatrans のトランザクション ID とともに記録され、メモには金額、決済方法、環境、確認方法（ウェブフックまたは戻り）が表示されます。

オーソリ後の Datatrans payment on hold: Auto settle がオフで、決済はオーソリのみです。注文ブロックでキャプチャまたはキャンセルしてください。

決済後の Datatrans payment on hold: Datatrans がカートの合計額と異なる金額または通貨を報告した（例えば、決済開始後にカートが変更された）、または注文がキャンセルされた後に決済が届いた場合です。メモに理由が説明されています。Datatrans の Web Admin でトランザクションを確認し、注文を処理するか、決済を返金してください。

Canceled: 注文ブロックまたは Datatrans の Web Admin でオーソリが解放されました。

Refunded: モジュールを通じて決済が全額返金されました。

すでに支払い済みまたはオーソリ済みのカートに 2 回目の決済が届いた場合、注文は変更されません。メモで内容を確認し、Datatrans で重複分を返金するように促されます。失敗またはキャンセルされたトランザクションが、支払い済みの注文を降格させることはありません。

Datatrans payment ブロック

注文画面には Datatrans payment ブロックが表示され、トランザクション ID、Datatrans のステータス、決済方法、金額、支払い済み額と返金済み額、サンドボックス決済用の Sandbox バッジ、返金履歴、注文の Datatrans notes が含まれます。このブロックの操作には注文を編集する権限が必要です。モジュールのページへのアクセス権は必要ありません。

キャプチャとキャンセル

オーソリのみの決済の場合、ブロックには Capture Datatrans payment と Cancel Datatrans authorization が表示されます。キャプチャは現在の注文合計額で決済を確定します。その額はオーソリ額を超えてはいけません。その後、注文は Order status after payment のステータスに移ります。キャンセルはオーソリを解放し、注文を Canceled に設定します。どちらの操作も決済の環境に対して行われます。Datatrans が拒否した場合、ブロックにエラーが表示され、メモが追加されます。

返金

Datatrans payment ブロックで金額を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて理由を入力し、Refund via Datatrans をクリックします。Refund this amount through Datatrans? This cannot be undone. の確認に応答してください。全額返金と一部返金に対応しており、上限は Datatrans が実際に請求した金額から、それ以前の返金額を差し引いた額です。返金は決済の環境に送信されるため、その環境の Merchant ID と API パスワードが設定されている必要があります。再試行された返金は二重に入金されません。Datatrans が返金を受け付けない場合、ブロックにエラーが表示され、返金は記録されません。成功した返金は、Datatrans の返金トランザクション ID とともに履歴とメモに追加されます。全額返金を行うと、注文は Refunded になります。一部返金ではステータスは変わりません。

オーソリのみの決済では、まだ何も請求されていません。「返金」できるのは全額のみで、これはオーソリをキャンセルします。返金は Datatrans が決済を確定した後にのみ利用できます。金額が一致しないオーソリは、確定されるまで返金できません。

モジュールはクレジットスリップを作成しません。注文画面にある PrestaShop の標準の返金ボタンでは、Datatrans を通じて返金されることはありません。Datatrans の Web Admin で行った返金は、PrestaShop には記録されません。

ライセンスキー

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

キーが受け付けられない場合、ブロックに理由が表示されます（例：Key not found、This key belongs to another product、Domain limit reached、または日付付きの License expired on）。ショップの URL を変更した後、またはアカウントでドメインの枠を解放した後は、Check now をクリックしてください。ライセンスサーバーに接続できない場合、モジュールは最後に確認されたステータスで動作を続けます。

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

有効なキーがないと、決済時に Datatrans は購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。PrestaShop のストアフロントは、管理画面にログインしていることを認識しないため、この決済方法は管理者にも非表示になります。キーを購入する前にモジュールを設定することはできますが、決済時にテストすることはできません。Modules > Module Manager の Alerts タブにリマインダーが表示されます。既存の注文は影響を受けません。すでに開始された決済は引き続き確認され、返金も機能します。

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

トラブルシューティング

Datatrans does not appear at checkout: ライセンスが有効であること、Enable/Disable がオンであること、現在の環境に Merchant ID と API パスワードがあることを確認してください。サンドボックスモードではサンドボックスのフィールド、それ以外では本番のフィールドです。設定ページには未入力の項目が表示されます。Payment > Preferences で、カートの通貨、購入者の国、購入者のグループに対してモジュールが許可されているか確認してください。

The payment went through, but no order was created: Datatrans がウェブフック URL に到達できず、購入者もショップに戻りませんでした。ショップがインターネットから到達可能であり、ファイアウォールがウェブフック URL へのリクエストをブロックしていないか確認してください。設定の署名キーが決済の環境のものかどうかも確認してください。モジュールページの Log フィールドを確認してください。

Webhook answers Invalid signature: 設定の HMAC 署名キーが Datatrans の Web Admin のものと一致しないか、別の環境のものです。キーをもう一度コピーしてください。

Webhook answers Not configured or Verification failed: ウェブフックは Datatrans のステータス API で確認する必要がありましたが、その環境の認証情報がないか、Datatrans が応答しませんでした。Datatrans はウェブフックを再試行します。

Webhook answers Busy, retry: 同じタイミングで別のリクエストが注文を確定していたか、注文を作成できませんでした（例えばモジュールが無効になっている）。Datatrans はウェブフックを再試行します。ログに理由が表示されます。

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

The HMAC sign key is not saved: キーは 16 進数の文字列である必要があります。Datatrans の Web Admin からもう一度コピーしてください。

The customer sees Datatrans payments are not configured yet: 現在の環境の Merchant ID または API パスワードがありません。

The customer sees The payment could not be started: Log フィールドを確認してください。Merchant ID や API パスワードの誤り、または別の環境の認証情報が一般的な原因です。

Order is Datatrans payment on hold after payment: 注文ブロックの Datatrans notes を読み（注文ステータスの項を参照）、その後注文を処理するか、決済を返金してください。

Capture is refused: 注文合計額がオーソリ額より多くなっています。Datatrans はオーソリされた額を超えて確定できません。

Refund or capture fails with a message about missing credentials: 決済は別の環境で行われており、その環境の Merchant ID または API パスワードが設定されていません。それらを入力して、もう一度お試しください。

アンインストール

Modules > Module Manager に進み、VibeFox Datatrans Gateway の横にあるメニューを開いて Uninstall を選択します。本モジュールのライセンスキーとライセンスステータスは常に削除されます。Delete data on uninstall がオンの場合、モジュールの設定とログが削除されます。オフの場合、後日の再インストールに備えてすべての設定が保持されます。Datatrans のトランザクションと返金、および Datatrans payment on hold の注文ステータスは常に保持されるため、以前に支払われた注文は再インストール後も返金やキャプチャができます。既存の注文は、決済のメモとトランザクション ID を保持します。

Datatrans は、各所有者の商標です。本モジュールは Datatrans と提携しておらず、Datatrans による推奨もありません。