VibeFox Datatrans for WooCommerce — ヘルプ

要件

WordPress: 6.0 以降。

WooCommerce: 7.0 以降。インストールして有効化されていること。

PHP: 8.0 以降。

HTTPS: Datatrans がウェブフックを配信できるよう、サイトにインターネットから HTTPS でアクセスできる必要があります。

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

通貨: ストアの通貨（またはマルチ通貨プラグインの注文通貨）が、Datatrans の加盟店アカウントで有効になっている必要があります。

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

インストール

1. WordPress で Plugins > Add New > Upload Plugin を開き、プラグインの ZIP ファイルを選択して Install Now をクリックします。FTP で wcp_datatrans_gateway フォルダーを /wp-content/plugins/ にアップロードすることもできます。

2. Activate をクリックします。WooCommerce が有効になっている必要があります。

3. 設定を開きます: WooCommerce > Settings > Payments > Datatrans > Manage。または、プラグイン一覧ページでプラグイン名の下にある Settings をクリックします。

4. ページ上部のライセンスブロックに VibeFox ライセンスキーを入力し、Activate をクリックします。

5. サンドボックスの認証情報を入力し、実際の支払いを受け付ける場合は本番の認証情報も入力します（「設定」を参照）。

6. Enable/Disable をオンにします。テスト中は Sandbox mode をオンのままにし、実際の支払いを受け付けるときはチェックを外します。

設定

すべての設定は 1 つのページにあります: WooCommerce > Settings > Payments > Datatrans。ゲートウェイが有効なのに現在の環境の 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. と表示されます。

ウェブフック

Webhook URL は設定の上部に表示されます。形式は https://your-site/wc-api/datatrans_payment_callback/ のようになります。プラグインはトランザクションごとにこの URL を Datatrans に送信するため、どこにも入力する必要はありません。Datatrans Web Admin のウェブフック設定にも入力すると、そちらで行ったキャプチャやキャンセルの更新を受け取れます。

ウェブフックはトランザクションの状態を通知します。プラグインは次の状態に対して動作します:

HMAC 署名キーを設定すると、各ウェブフックは Datatrans-Signature ヘッダーで検証されます。有効な署名のないウェブフックは拒否されます。署名キーがない場合、プラグインはウェブフックの内容を信用せず、すべてのウェブフックを Datatrans のステータス API で確認します。ウェブフックがない場合、注文が確認されるのは、購入者が支払い後にストアへ戻ったときだけです。

一般

Enable/Disable: Enable Datatrans Payment で決済方法のオン/オフを切り替えます。デフォルト: オフ。

Title: チェックアウトで購入者に表示される決済方法の名前。デフォルト: Datatrans。

Description: チェックアウトで決済方法の下に表示されるテキスト。デフォルト: Pay securely via Datatrans。

Sandbox mode: Use the Datatrans sandbox (test payments, no real money)。API と決済ページのホスト、および以下の認証情報の両方を切り替えます。返金とキャプチャは、常に支払いが行われた環境を使用します。デフォルト: オン。実際の支払いを受け付けるにはチェックを外します。

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

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 で再確認されます。

署名キーは、Datatrans が発行した 16 進文字列でなければなりません。それ以外の値は保存されず、ページにエラーが表示されて以前の値が保持されます。バージョン 1.0 から更新する場合、そのバージョンの単一の認証情報は、サンドボックスモードがオンだったときはサンドボックスのフィールドに移され、そうでなければ本番のフィールドに残ります。

決済処理

Auto settle: Capture (settle) payments immediately。デフォルト: オン。オフにすると、支払いはオーソリのみ行われます。注文は保留中になり、後で注文アクションの Capture Datatrans payment でキャプチャするか、Cancel Datatrans authorization で解除します。

Order status after payment: 支払いが清算されたときに設定される注文ステータス。ステータスはすぐに設定され、2 回目のステータス変更は行われません。

詳細設定

Logging: Log payment events and API calls は、詳細を WooCommerce > Status > Logs のソース wcp_datatrans_gateway に書き込みます。エラーは常に記録されます。キー、カード情報、購入者データは書き込まれません。デフォルト: オフ。

Delete data on uninstall: Remove the plugin settings when the plugin is deleted。デフォルト: オフ。

チェックアウト

購入者は決済方法（デフォルトでは Datatrans）を選んで注文します。プラグインは、注文の合計額を注文の通貨で、注文 ID を参照として Datatrans のトランザクションを作成し、購入者を Datatrans の決済ページへ移動させます。購入者はそこで、Datatrans アカウントで有効なあらゆる方法（たとえばカード、TWINT、PostFinance）で支払います。サイトがドイツ語、英語、フランス語、イタリア語のいずれかを使っている場合、決済ページはその言語で開きます。それ以外の場合は、Datatrans が言語を選びます。

支払い後、購入者はストアの注文受付ページに戻ります。注文が支払い済みになるのは、Datatrans が確認した後だけです。確認は、ウェブフック、または購入者が戻ったときに Datatrans のステータス API へ行うサーバー側のリクエストによって行われます。戻り先のアドレスには注文キーが含まれますが、戻ること自体で注文が支払い済みになることはありません。

購入者が決済ページでキャンセルすると、Pay for order ページに移動し、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 が支払いを開始できない場合、購入者には The payment could not be started. Please try again or choose another payment method. と表示されます。理由はログに書き込まれます。

この決済方法は、クラシックチェックアウト、チェックアウトブロック、Pay for order ページで動作します。WooCommerce の High-Performance Order Storage（HPOS）と互換性があります。

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

注文と返金

注文ステータス

Pending payment: 購入者は Datatrans に移動したがまだ支払っていない、決済ページでキャンセルした、または Datatrans がまだ支払いを確認していません。新しいトランザクションごとに、その ID と環境が注文にメモされます。

Processing, Completed or On Hold: 支払いが清算されました。ステータスは Order status after payment に従います。注文メモには、金額、決済方法、Datatrans のトランザクション ID、環境（サンドボックスまたは本番）が表示されます。トランザクション ID は注文に保存されます。

On hold, authorized: Auto settle がオフの場合、支払いはオーソリされたもののキャプチャされていません。注文を開き、注文アクションで Capture Datatrans payment または Cancel Datatrans authorization を選びます。キャプチャには現在の注文合計が使われ、オーソリ額を超えてはいけません。超えている場合や、Datatrans がキャプチャまたはキャンセルを拒否した場合は、その理由が注文メモに追加されます。

On hold after payment: Datatrans が注文合計と異なる金額または通貨を報告した（たとえば、支払い開始後に注文が編集された）か、注文がキャンセルされた後に支払いが届きました。注文メモにその説明が記されます。Datatrans Web Admin でトランザクションを確認し、注文を履行するか、支払いを返金してください。

Failed: 支払いが失敗したか、拒否されました。購入者は再試行できます。

Cancelled: 注文アクションまたは Datatrans Web Admin で、オーソリが解除されました。

遅れて届いた失敗やキャンセルの通知が、支払い済みの注文を変更することはありません。すでに支払い済みの注文に 2 回目の決済成功が届いた場合、注文は変更されません。メモで二重請求の可能性が通知され、必要に応じて Datatrans で返金するよう案内されます。

返金

注文を開き、Refund をクリックして金額を入力し、Refund via Datatrans をクリックします。全額返金と一部返金に対応しています。返金は支払いが行われた環境に送信されるため、その環境の認証情報が設定されている必要があります。再試行された返金が二重に返金されることはありません。Datatrans が返金を受け付けない場合、WooCommerce にエラーが表示され、返金は記録されません。返金が成功すると、金額と Datatrans の返金トランザクション ID とともに注文メモに追加されます。

オーソリのみの支払いの場合、全額を返金するとオーソリが取り消されます。支払いがキャプチャされるまで、一部返金はできません。

Datatrans Web Admin で行った返金は WooCommerce には記録されません。必要に応じて、WooCommerce で Refund via Datatrans を使わない手動の返金を作成してください。

ライセンスキー

本プラグインは、vibefox.net の VibeFox ライセンスキーで動作します。ライセンスブロックは WooCommerce > Settings > Payments > Datatrans の上部にあります。キーを License key に貼り付けて Activate をクリックします。ブロックには、ライセンスの有効期限やドメインなどのステータスが表示されます。Check now でステータスを再確認し、Change key で別のキーを入力し、Remove key でこのサイトからキーを削除します。Manage licenses and domains in your account のリンクから、vibefox.net のアカウントが開きます。

1 つのキーは 1 つのドメインで使用できます。サイトからキーを削除しても、そのドメインの枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、Datatrans はチェックアウトで購入者に表示されません。それでも支払いが開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。ログイン中のストア管理者には、決済方法が (unlicensed — visible to admins only) と表示されたままなので、キーを購入する前にプラグインを設定してテストできます。プラグイン一覧ページと WooCommerce のページにリマインダーが表示されます。既存の注文には影響しません。すでに開始された支払いは引き続き確認され、返金とキャプチャも動作します。

ライセンスの期限が切れても、プラグインは動作し続けますが、アップデートとサポートにはライセンスの更新が必要です。ステータスはバックグラウンドで自動的に再確認されます。

トラブルシューティング

チェックアウトに Datatrans が表示されない: ライセンスが有効であること、Enable/Disable がオンであること、現在の環境の Merchant ID と API パスワードが設定されていることを確認してください。サンドボックスモードではサンドボックスのフィールド、それ以外では本番のフィールドです。設定ページに不足しているフィールドが一覧表示されます。

支払いは完了したが、注文が支払い待ちのまま: Datatrans がウェブフックの URL に到達できず、購入者もストアに戻りませんでした。サイトがインターネットから HTTPS でアクセスできること、セキュリティプラグインやファイアウォールが /wc-api/datatrans_payment_callback/ へのリクエストをブロックしていないことを確認してください。設定の署名キーが、支払いの環境のものであることを確認してください。Logging をオンにして、WooCommerce > Status > Logs のソース wcp_datatrans_gateway を確認します。

ウェブフックが Invalid signature と応答する: 設定の HMAC 署名キーが Datatrans Web Admin のものと一致していないか、もう一方の環境のものです。キーをもう一度コピーしてください。

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

HMAC 署名キーが保存されない: キーは 16 進文字列でなければなりません。Datatrans Web Admin からもう一度コピーしてください。

購入者に The payment could not be started と表示される: Merchant ID または API パスワードが間違っているか、もう一方の環境のものか、その通貨が Datatrans アカウントで有効になっていません。Logging をオンにして理由を確認してください。

支払い後に注文が保留中になる: 注文メモを読んでください。支払われた金額または通貨が注文と異なっていた、注文がキャンセルされた後に支払いが届いた、または支払いがオーソリのみでキャプチャ待ちの状態です。

キャプチャできない: 注文合計がオーソリ額より高くなっています。キャプチャには現在の注文合計が使われるため、オーソリ額以下に下げてください。

返金が認証情報に関するメッセージで失敗する: 支払いがもう一方の環境で行われており、その認証情報が設定されていません。入力してもう一度お試しください。オーソリのみの支払いの場合は、全額を返金するか、先にキャプチャしてください。

ライセンスブロックにエラーが表示される: ブロック内のメッセージに従ってください。たとえば、キーがすでに別のドメインで使われている場合は、vibefox.net のアカウントで枠を解放し、Check now をクリックします。サイトのアドレスが変わった場合は、Check now をクリックして新しいドメインでキーを有効にします。ライセンスサーバーに接続できない場合、プラグインは最後に確認されたステータスで動作を続けます。

開発者向けに、readme ではフィルター wcp_datatrans_gateway_init_request を紹介しています。たとえば、Datatrans のページに表示される決済方法を制限するために使えます。

アンインストール

プラグインを無効化しても、すべてのデータは保持されます。削除するには、Plugins ページで無効化してから削除します。このプラグインのライセンスキーとライセンスステータスは、常に削除されます。ゲートウェイの設定が削除されるのは、Delete data on uninstall がオンだった場合のみです。それ以外の場合は、後で再インストールするときのために残ります。既存の注文には、支払いメモとトランザクション ID が残ります。

Datatrans は、それぞれの所有者の商標です。本プラグインは Datatrans と提携しておらず、Datatrans の承認も受けていません。