VibeFox Pin Payments for OpenCart — ヘルプ

要件

OpenCart: 3.0.x（3.0.5.0 でテスト済み）、または 4.0.2 以降（4.1.0.3 でテスト済み）。

PHP: 8.0 以降。

Pin Payments アカウント: Pin Payments の加盟店アカウント（オーストラリアまたはニュージーランドの法人向け。購入者はどこからでも支払えます）。本番環境用と、テスト用のテスト環境用の、publishable key と secret key が必要です。webhook の secret は不要です。この拡張機能は webhook を使用しません。カード情報は購入者のブラウザから Pin.js によって Pin Payments に直接送信され、貴店のサーバーには届きません。そのため、ストアは PCI SAQ A-EP の対象となります。

通貨: AUD、USD、NZD、SGD、EUR、GBP、CAD、HKD、JPY、MYR、THB、PHP、ZAR、IDR。注文は元の通貨で請求されます。

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

インストール

ダウンロードは、両方の OpenCart バージョン用のパッケージを含む 1 つの zip ファイルです。コンピューターで解凍してください。内容は README.txt、OpenCart 3 用のパッケージ wcp_pinpayments_gateway-oc3-(version).ocmod.zip、OpenCart 4 用のパッケージ wcp_pinpayments_gateway.ocmod.zip です。お使いの OpenCart のバージョンのパッケージだけをインストールしてください。ライセンスキーは両方のバージョンで同じです。

OpenCart 3

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_pinpayments_gateway-oc3-(version).ocmod.zip を選択します。この拡張機能には OCMOD の変更がないため、Extensions > Modifications の更新は不要です。インストーラーを使う代わりに、このパッケージの upload フォルダの内容をストアのルートフォルダにコピーすることもできます。

2. Extensions > Extensions に移動し、種類 Payments を選択します。VibeFox Pin Payments Gateway を見つけて、Install（緑色の + ボタン）をクリックします。管理者ユーザーに、決済拡張機能の一覧を変更する権限が必要です。

3. Edit（鉛筆のボタン）をクリックして設定ページを開きます。ページ上部のライセンスブロックにある License key に VibeFox ライセンスキーを貼り付け、Activate をクリックします（License key を参照）。

4. Pin Payments のダッシュボードで Account > API Keys を開き、テスト用のキーを Test publishable key と Test secret key にコピーします。Test mode はオンのままにし、Enable/Disable をオンにして、Save をクリックします。

5. Pin Payments のテストカードでテスト注文を行います。すべて正常に動作したら、本番のキーを入力し、Test mode をオフにして保存します。

OpenCart 4

1. 管理画面で Extensions > Installer に移動し、Upload をクリックして、ファイル wcp_pinpayments_gateway.ocmod.zip を選択します。ファイル名は変更しないでください。OpenCart 4 は拡張機能のコードをファイル名から取得するため、名前を変更したパッケージは動作しません。

2. インストール済み拡張機能の一覧に、同じページでパッケージが表示されます。その横の Install（緑色の + ボタン）をクリックします。

3. Extensions > Extensions に移動し、種類として Payments を選択します。VibeFox Pin Payments Gateway を見つけ、Install（緑色の + ボタン）をクリックしてから、Edit（鉛筆ボタン）をクリックします。

4. OpenCart 3 の手順 3 から 5 と同じように、ライセンスキーと Pin Payments のキーを入力します。設定ページとその欄は両方のバージョンで同じです。

新規インストールでは、決済方法は無効、テストモードは有効の状態で始まります。

設定

すべての設定は拡張機能のページにあります：Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit。セクションは左側に一覧表示されます。一覧の下にある Save ボタンでページ全体を保存します。設定の上では、テストモードがオンの間、ページに Pin Payments is in TEST MODE: the test API and test keys are used, no real charges are made. と表示されます。現在のモードの publishable key または secret key が空の場合はエラーが表示されます（この場合、チェックアウトでは決済方法が非表示になります）。ストアの既定通貨を Pin Payments がサポートしていない場合もエラーが表示されます（サポートされている通貨の一覧付き）。拡張機能を変更する権限がない場合、ページには設定が表示されますが、保存はできません。

保存時に、いずれかのフィールドに誤りがあると、何も保存されません。Title は空にできません（Enter a title for the payment method (at most 128 characters).）。Sort Order は整数である必要があります（負の値も可）。Total は 0 以上の数値で、Geo Zone と注文ステータスは存在している必要があります。

Pin Payments

Enable/Disable: Enable Pin Payments で決済方法の有効／無効を切り替えます。既定値: 無効。

Title: チェックアウトで購入者に表示される決済方法の名前です。注文にも決済方法名としてこの名前が保存されます。既定値: Credit card (Pin Payments)。必須、最大 128 文字。

Description: Confirm Order ステップで、カードフォームの上に購入者に表示されるテキストです。既定値: Pay with your credit card via Pin Payments.

Sort Order: チェックアウトの決済方法の中で Pin Payments が表示される位置です。空欄のままにするか、整数を入力します。

Geo Zone: 選択したジオゾーン内の支払い先住所に対してのみ、カードフォームを表示します。既定値: All zones。ジオゾーンは System > Localisation > Geo Zones で設定します。

Total: 決済方法を提供するために注文が到達している必要がある、ストアの既定通貨でのチェックアウト合計金額です。空欄にすると、どの金額でも提供します。

API キー

キーは Pin Payments のダッシュボード（このページは dashboard.pinpayments.com へのリンクを掲載しています）の Account > API Keys にあります。テストキーはテスト API でのみ、本番キーは本番 API でのみ機能します。publishable key は、購入者のブラウザで Pin.js が使用します。secret key が貴店のサーバーの外に出ることはありません。

Test mode: Pin Payments のテスト環境（test-api.pinpayments.com）とテストキーを使用します。実際の請求は行われず、購入者にはカードフォームの上に TEST MODE — no real charges will be made. と表示されます。オフにすると、本番 API と本番キーが使用されます。注文の返金は、常に注文が支払われた環境のキーを使用します。既定値: 有効。

Test publishable key: Pin Payments のテストアカウントの publishable key です。

Test secret key: Pin Payments のテストアカウントの secret key です。

Live publishable key: Pin Payments の本番アカウントの publishable key です。

Live secret key: Pin Payments の本番アカウントの secret key です。

キーの前後の空白は削除されます。保存済みの secret key は二度と表示されません。フィールドは空のままで、保存済み — 変更しない場合は空欄のままにしてください。 と表示されます。変更したい場合にのみ新しい値を入力してください。保存済みの secret key を削除するには、フィールドの下にある Clear the saved value on save をオンにして Save をクリックします。

注文

OpenCart は Confirm Order ステップで、ステータスなしの注文（欠落注文）を作成します。注文にステータスが付くのは、Pin Payments が請求に応答した後だけです。以下の各フィールドには、OpenCart の注文ステータスが一覧表示されます。

Order Status After Payment: カードは注文の金額と通貨で正確に請求されました。既定値: Processing。

On Hold (Review) Status: 請求された金額または通貨が注文と異なる、請求は承認されたがキャプチャされていない、または Pin Payments が明確な応答を返さなかった（タイムアウト、サーバーエラー）ため、請求が存在する可能性がある状態です。メモには、Pin Payments のダッシュボードで確認すべき内容が記載されます。既定値: Pending（OpenCart には On hold ステータスがないため）。独自のステータスは System > Localisation > Order Statuses で作成し、ここで選択できます。

Refunded Status: 注文のタブから決済を全額返金した後に設定されます。既定値: Refunded。

詳細設定

Debug log: Pin Payments の API 呼び出しを、OpenCart のログフォルダ（storage/logs）にある wc_ppg_debug.log.php に書き込みます。このファイルは Web から開くことができず、5 MB に達すると wc_ppg_debug.old.log.php に移動されます。エラーと警告は常に記録されます。すべての API 呼び出しも記録するには、このオプションをオンにしてください。カード情報、API キー、顧客の個人データは記録されません。既定値: 無効。

Log: ログのサイズと最新のエントリを表示します。Clear log をクリックすると、ログを空にできます。

Delete data on uninstall: オンの場合、拡張機能のアンインストール時にゲートウェイの設定とログを削除します。注文の決済データ（請求と返金）は常に保持されます。既定値: 無効。

インポート / エクスポート

Export: Download JSON で、設定を JSON ファイルとして保存します。secret key はエクスポートされません。

Import: 以前にエクスポートした JSON を貼り付け、Import をクリックして設定を復元します。保存済みの secret key は保持されます。

チェックアウト

決済方法は、有効になっていて、現在のモードの両方のキーが設定されており、注文の通貨が対応する 14 種類の通貨のいずれかであり、支払い先住所が選択した Geo Zone に含まれ、注文が Total に達している場合に表示されます。

Payment Method ステップで、購入者は決済方法を選択します（既定では Credit card (Pin Payments)）。OpenCart は Confirm Order ステップで注文を作成しますが、このときもステータスはありません。このステップで購入者には、あなたの説明文、Visa、Mastercard、American Express のアイコン、カードフォームが表示されます：Card number、Expiry (MM / YY)、CVC、Name on card。OpenCart 4 では、購入者は決済方法ブロックの Choose ボタンを押し、Payment method options ウィンドウで決済方法を選びます。その後、カードフォームは、Confirm Order ボタンの上にあるチェックアウトページ下部の確認ブロックに表示されます。送信前に、フォームはカード番号の桁数、有効期限の月と年、3 桁または 4 桁の CVC、名前を確認します。

購入者が Confirm Order をクリックすると、Pin.js がカード情報と注文の支払い先住所（OpenCart 4 では、チェックアウトが支払い先住所を求めない場合は配送先住所）をブラウザから Pin Payments に直接送信し、1 回限りのカードトークンを取得します。貴店に送信されるのはこのトークンだけです。その後、拡張機能は注文の通貨で注文合計額のキャプチャ済みの請求を作成し、購入者のメールアドレスと IP アドレス、説明 <store name> - Order <order number> を添えます。Pin Payments は同じリクエストの中で応答します。

請求が成功すると、注文は通常の OpenCart の方法でステータスを受け取り、通常の注文メールと在庫の更新が行われます。カートは空になり、購入者には Your card payment has been received. と表示される OpenCart の注文完了ページが表示されます。注文が審査ステータスになった場合、ページには カード決済を受け付けました。現在審査中です。審査が完了次第、注文を更新します。 と表示されます。

Pin Payments が応答しない場合（タイムアウト、サーバーエラー、読み取れない応答）、請求がすでに作成されている可能性があります。その場合、注文はメモ付きで審査ステータスになり、完了ページには Pin Payments で決済を確認できませんでした。もう一度お支払いいただく前に、メールとカードの明細をご確認いただくか、お問い合わせください。 と表示されます。同じカートを再送信しても、2 回目の請求が作成されることはありません。

カートごとに同時に実行される決済の試行は 1 回だけです。2 回目の送信では この注文はすでに決済処理中です。しばらくお待ちいただき、再試行する前にメールをご確認ください。 と表示されます。OpenCart 3 は Confirm Order ステップが表示されるたびに新しい注文を作成し、OpenCart 4 はチェックアウトの注文を更新します（拒否されたカードの後、購入者は同じ注文を支払います）。そのため、別の注文ですでに支払われたカートは直接完了ページに進みます。また、請求された（またはされた可能性のある）以前の試行は、新しい請求を作成する代わりに、そのステータスを注文に引き継ぎます。カードトークンは 1 回しか使用できません。失敗した試行の後、または購入者がカード情報を変更した場合には、新しいトークンが作成されます。

OpenCart 4 では、完了ページが表示されるまで注文がチェックアウト内に保持されます。その注文が、購入者による新しい購入の確定時にすでにステータスを持っている場合（たとえば、支払い済みで完了ページが開かれなかった、またはあなたがキャンセルした場合）、購入者はチェックアウトに戻され、次の Confirm Order で現在のカートの新しい注文の決済が行われます。チェックアウトページの上には、注文が閉じられていた場合は Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.、以前のカートのために注文が出されていた場合は Your previous order #（番号）has already been placed. Your cart has changed: please confirm the new order to pay for it. と表示されます。支払い済みの注文が、別のカートの支払い済みとして表示されることはありません。

決済が失敗した場合、注文はステータスなしのままです。購入者は Confirm Order ステップにとどまり、カートは保持されます。カードフォームの上には、次のいずれかのメッセージが表示されます：カードが拒否されました。別のカードをご利用いただくか、お取引の銀行にお問い合わせください。；カードの残高が不足しています。別のカードをご利用ください。；カードの有効期限が切れています。別のカードをご利用ください。；カードのセキュリティコード（CVC）が正しくありません。；このカードの種類は受け付けられません。Visa、Mastercard、American Express をご利用ください。；決済に失敗しました: 拒否された情報について Pin Payments が示した理由が続きます；カード情報の有効期限が切れています。もう一度入力して、やり直してください。（トークンが使用できない場合）；安全なカードフォームを読み込めませんでした。ページを再読み込みするか、別の決済方法をお選びください。（Pin.js が読み込まれない場合）；現在カード決済をご利用いただけません。しばらくしてからもう一度お試しいただくか、別の決済方法をお選びください。（Pin Payments が secret key を拒否した場合）；お支払いを処理できませんでした。もう一度お試しいただくか、別の決済方法をお選びください。（その他のエラー）。技術的な理由はログに記録されます。

この拡張機能には 3-D Secure のフローはありません。Pin Payments のアカウントで 3-D Secure が必須になっている場合、請求は保留のままになり、注文にはステータスが付かず、購入者には カード決済を完了できませんでした（追加の認証が必要です）。別のカードまたは別の決済方法をお試しください。 と表示されます。後でキャプチャするオーソリのみのモード、保存済みカード、サブスクリプション、Apple Pay または Google Pay、webhook はサポートされていません。

注文と返金

注文ステータス

ステータスなし（欠落注文）: カードが拒否された、請求に 3-D Secure が必要だった、または購入者が支払っていない状態です。Sales > Orders では、このような注文は Order Status フィルターを Missing Orders に設定した場合にのみ表示されます。

Order Status After Payment（既定値 Processing）: Pin Payments が、注文の金額と通貨で正確に、成功してキャプチャされた請求を報告した状態です。メモには金額と請求トークンが表示されます（テスト決済の場合は TEST MODE も表示されます）。

On Hold (Review) Status（既定値 Pending）: 請求にはあなたの確認が必要です。メモには理由が記載されます。Pin Payments が注文と異なる金額または通貨を請求した、請求は承認されたがキャプチャされていない（Pin Payments のダッシュボードでキャプチャしてから、注文ステータスを変更してください）、または Pin Payments が明確な応答を返さなかった（注文を発送する前に、Pin Payments のダッシュボードで請求の説明を探してください）のいずれかです。

Refunded Status（既定値 Refunded）: 請求が拡張機能を通じて全額返金された状態です。

すでに支払い済みのカートに対して 2 回目の請求が行われた場合、支払い済みの注文は変更されません。メモで、それを確認して Pin Payments のダッシュボードで返金するよう求められます。

メモは注文の History に記録されるエントリで、購入者には表示されません。

VibeFox Pin Payments Gateway tab

Sales > Orders で、Pin Payments で支払われた注文を開きます。注文ページの下部、History と Additional の隣にある VibeFox Pin Payments Gateway タブには、テスト決済の場合は Test ラベル付きの Charge トークン、Status、Card のブランドと下 4 桁、Charged / order / refunded の金額、Charge description、返金フォーム、返金履歴、注文の Pin Payments notes が表示されます。このタブは、拡張機能へのアクセス権を持つユーザーに表示されます。

返金

VibeFox Pin Payments Gateway タブで Amount を入力します（まだ返金されていない金額が自動入力されます）。必要に応じて Reason (optional) を入力し、Refund via Pin Payments をクリックします。Pin Payments 経由でこの金額を返金しますか？この操作は取り消せません。 という確認に応じてください。全額返金と一部返金に対応しています。拡張機能を変更する権限が必要です（System > Users > User Groups で設定します）。返金は、Pin Payments が実際に請求した金額と通貨に制限されます。そのため、金額または通貨の不一致の後は、注文合計ではなく、購入者が支払った金額まで返金できます。返金は、注文が支払われた環境（テストまたは本番）に送信されるため、そのモードの secret key が設定されている必要があります。Pin Payments は返金を非同期で処理するため、ステータスは通常 Pending になります。成功したリクエストは、Pin Payments の返金トークンとそのステータスとともに、返金履歴とメモに追加されます。全額返金では、購入者に通知せず、商品を在庫に戻さずに、手動でのステータス変更と同様に注文を Refunded Status にします。一部返金ではステータスは変わりません。Pin Payments が返金を拒否した場合、または応答しなかった場合、タブにはエラーが表示され、返金は記録されません。

注文に記録された請求がない場合（Pin Payments が明確な応答を返さなかった場合）、タブには返金フォームが表示されず、Pin Payments のダッシュボードで探すべき説明が示されます。

Sales > Returns での商品返品では、Pin Payments を通じて代金が返金されることはありません。Pin Payments のダッシュボードで行った返金は OpenCart に同期されないため、返金は注文ページから行ってください。

ライセンスキー

この拡張機能は、vibefox.net で取得した VibeFox ライセンスキーで動作します。ライセンスブロック License — VibeFox Pin Payments Gateway は、Extensions > Extensions > Payments > VibeFox Pin Payments Gateway > Edit の最初のブロックで、設定の上にあります。キーを License key に貼り付け、Activate をクリックします。その後、ブロックにはマスクされたキー、ステータス（例: ライセンスの有効期限日とドメイン）、そして以下のボタンが表示されます：ステータスを再確認する Check now、別のキーを入力する Change key、このストアからキーを削除する Remove key。その下には Product: opencart-payment-pinpayments という行と、vibefox.net のアカウントを開く Manage licenses and domains in your account のリンクがあります。キーを変更できるのは、この拡張機能に対する Modify 権限を持つ管理者ユーザーだけです。ブロックのテキストは管理画面の言語に従います（英語とロシア語を含みます）。

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

1 つのキーは 1 つのドメインで動作します。OpenCart の設定にあるストアのアドレスです。ストアからキーを削除しても、ドメイン枠は解放されません。vibefox.net のアカウントで枠を解放してください。

有効なキーがない場合、Pin Payments はチェックアウトで購入者に表示されません。それでも決済が開始された場合、購入者には This payment method is not available. Please choose another one. と表示されます。同じブラウザで管理画面にログインしている管理者ユーザーには、ストア内で決済方法が表示され、(unlicensed — visible to admins only) と表示されます。そのため、キーを購入する前に拡張機能を設定してテストできます。OpenCart 4 では、このプレビューは利用できません。ストアからは管理画面へのログインが見えないため、有効なキーがない場合は、決済方法がすべてのユーザーに対して非表示になります。Edit ページを一度開くと、管理画面の Dashboard にリマインダーが表示されます。× で閉じると、7 日間非表示になります。既存の注文には影響しません。以前に支払われた注文の返金は、引き続き機能します。

ライセンスの期限が切れても、拡張機能は動作を続けますが、アップデートとサポートには更新が必要です。管理画面の Dashboard または Edit ページを開くと、ステータスが自動的に再確認されます。キーを入力してから最初の 14 日間は 1 日に 1 回、その後は週に 1 回です。cron ジョブは必要ありません。拡張機能をアンインストールすると、ライセンスキーとライセンスステータスは常に削除されます。

トラブルシューティング

チェックアウトに Pin Payments が表示されない: ライセンスが有効であること、Enable/Disable が有効であること、現在のモードの両方のキーが入力されていること（テストモードでは Test publishable key と Test secret key、それ以外の場合は本番キー）、注文の通貨が対応する 14 種類の通貨のいずれかであることを確認してください。また、支払い先住所が選択した Geo Zone に含まれていること、注文が設定の Total に達していることも確認してください。設定ページには、キーが不足している場合やストアの通貨がサポートされていない場合にエラーが表示されます。

決済は完了したが、注文が審査ステータスになっている: VibeFox Pin Payments Gateway タブのメモを確認してください（注文ステータスを参照）。Pin Payments が明確な応答を返さなかった場合は、Pin Payments のダッシュボードで <store name> - Order <order number> という説明の請求を探し、その後、注文を処理するか、ダッシュボードで請求を返金してください。

購入者に「Your payment was received, but the order could not be completed automatically」と表示される: カードには請求されましたが、注文ステータスを設定できませんでした（例: その間に注文が削除された）。理由はログにあります。購入者には、再度支払わないようお願いしています。同じカートを再送信すると、新たな請求なしで注文にステータスが付きます。

購入者に「This payment method is not available. Please reload the checkout page.」と表示される: チェックアウトのセッションが注文と一致しなくなったか、その間に決済方法が無効化されました。購入者はチェックアウトページを再読み込みします。

購入者に「Card payments are temporarily unavailable」と表示される: Pin Payments が secret key を拒否したか、現在のモードのキーがありません。テストキーはテストモードでのみ、本番キーは本番モードでのみ機能します。ログに理由が表示されます。

「additional verification is required」で注文が失敗する: Pin Payments のアカウントで 3-D Secure が必須になっていますが、この拡張機能はそれをサポートしていません。Pin Payments に、必須の 3-D Secure を無効にするよう依頼してください。

安全なカードフォームを読み込めませんでした: Pin Payments の CDN から Pin.js が、ブラウザで読み込まれませんでした。例えば、スクリプトブロッカーや、スクリプトを結合または変更する拡張機能が原因である可能性があります。そのような最適化の対象からチェックアウトを除外してください。

Pin Payments が応答しませんでした: 30 秒以内にブラウザでカードトークンが作成されませんでした。購入者は接続を確認して、もう一度お試しいただけます。請求は行われていません。

Pin Payments の理由で決済に失敗した: Pin Payments が請求の詳細を拒否しました。例えば、その通貨の最低請求額を下回る金額です。購入者には理由が表示され、ログにはエラーコードが記録されます。

返金に失敗する: タブのメッセージを確認してください。TEST または LIVE モードに関するメッセージは、注文が支払われたモードの secret key が空であることを意味します。Pin Payments did not confirm the refund は、応答がなかったことを意味します。再試行する前に、Pin Payments のダッシュボードで請求を確認してください。at most は、請求からまだ返金可能な金額を示します。

テスト決済: テストモードでは、テスト環境とテストキーを使用します。Pin Payments の開発者向けドキュメントにあるテストカードを使用してください。例えば 4200 0000 0000 0000（成功）で、有効期限は将来の任意の日付、CVC は任意の値です。注文は支払われたモードを保持するため、モードを切り替えた後も、返金は正しい環境に送られます。

エラーの確認先: エラーは常にログに記録されます。拡張機能のページの Log フィールドを確認してください。すべての API 呼び出しを確認するには、Debug log をオンにします。

アンインストール

Extensions > Extensions に移動し、種類 Payments を選択して、VibeFox Pin Payments Gateway の横にある Uninstall（赤い − ボタン）をクリックします。この拡張機能のライセンスキーとライセンスステータスは、常に削除されます。OpenCart は拡張機能自身の設定を常に削除します：Enable/Disable、Sort Order、Geo Zone、Total、および Orders セクションにある注文ステータスです。これらは再インストール時に既定値に戻ります。拡張機能の OpenCart イベントも削除されます（OpenCart 4 では、メッセージを成功ページとチェックアウトページの上に表示する 2 つのイベントも削除されます）。Delete data on uninstall がオンの場合は、その他のゲートウェイ設定（タイトル、説明、テストモード、キー、デバッグログのスイッチ）とログも削除されます。オフの場合は、後で再インストールするために保持されます。Pin Payments の請求と返金は常に保持されるため、以前に支払われた注文は、再インストール後も返金できます。既存の注文は、決済メモを保持します。

OpenCart 4 で拡張機能のファイルも削除するには、アンインストール後に Extensions > Installer に移動し、インストール済み拡張機能の一覧で VibeFox Pin Payments Gateway の横にある Uninstall（オレンジ色の − ボタン）をクリックしてから、アップロードしたパッケージを削除するために Delete（赤いゴミ箱ボタン）をクリックします。

Pin Payments は、それぞれの所有者の商標です。この拡張機能は Pin Payments と提携しておらず、Pin Payments による承認も受けていません。