MevvPos Documentation

インストール

MevvPos には WordPress 6.0+、PHP 8.1+、および WooCommerce 9.0 以降が必要です。WooCommerce はプラグインヘッダーで宣言された必須の依存関係です。無い場合、WordPress は有効化を拒否します。より古い WordPress では、プラグインは単に何もしません。

プラグイン → 新規追加 → プラグインのアップロードからプラグインをアップロードし、有効化します。
管理画面の左メニューから MevvPos を開きます。WooCommerce の下にもショートカットがあります。決済設定を探すとき、多くの方がそちらを見るからです。
一般タブで支払い方法を有効にし、購入手続きで顧客に表示されるタイトルを設定します。
銀行 API で銀行を選び、銀行から渡された認証情報を入力します。
分割払いと手数料で分割払いの料率を入力します。
本番稼働の前に、銀行のテスト用認証情報で動作を確認してください。

無料版はデータベーステーブルを作成せず、定期実行ジョブも登録しません。すべては WordPress のオプションと注文メタに保存されます。

Pro は無料版と並べてインストールする別のプラグインであり、無料版の置き換えではありません。無料版は WordPress.org で公開されており、そこで公開されたものはすべて GPL のもとで再配布できます。有料のソースコードを同じパッケージに入れていれば、ライセンス確認を削除した人が法的に再配布できてしまいます。ライセンスキーはライセンスタブで入力します。

WooCommerce → 設定 → 決済 → MevvPos を開くと、MevvPos の画面へ転送されます。これは意図的です。この設定の置き場所は一つであるべきで、食い違いうる二つがあってはならないからです。

仕組み

POS レコードを一つ以上定義します。POS レコードとは、ある銀行のバーチャルPOS 一つ分です。認証情報、ゲートウェイのアドレス、分割払いの料率をまとめたものです。
購入手続きで、お客様がカード情報を入力します。最初の 6 桁 — BIN — から発行銀行が特定されます。
MevvPos は BIN を照会し、その銀行にお客様の POS があれば、支払いをその POS へ送ります。無ければ、既定の POS が受け持ちます。
分割払いが提示されるのは、そのカードが当該 POS の銀行のものである場合だけです。銀行は他行のカードに分割払いを認めないからです。
お客様は銀行側で 3-D セキュアを通過し、銀行はお客様のサイト上にある一つのコールバックアドレスへ戻します。
戻り値の署名は、その注文が実際に使った POS の鍵で検証され、注文が完了し、結果が記録されます。

カード番号、有効期限、CVV が、データベースや WooCommerce のセッションに書き込まれることはありません。保持されるカード関連の情報は、最初の 6 桁と、判定された銀行名だけです。

POS レコード

POS のバーはタブの上にあり、どのタブでも表示されます。各カードには、銀行、加盟店番号、そして注意が必要なときにはバッジが表示されます。

既定: より適した対応先が見つからないときに支払いを受け持つ POS です。常にちょうど一つ存在します。
無効: 残してあるが、決済は受け付けない状態です。POS の設定は済んでいるものの、銀行側でまだ稼働していないときは、削除ではなくこの状態にしてください。そうしないと、その銀行のカードをお持ちのお客様が支払えなくなります。
ライセンス待ち: レコードは存在しますが、ライセンスが有効でないため休止しています。何も削除されておらず、ライセンスを更新すれば、止まったところから再開します。
API 情報が入力されていません: そのレコードには、まだ加盟店番号が入力されていません。

銀行はロゴではなく、色の帯で示します。銀行のロゴは商標であり、15 行分ともなれば法的な危険と、終わりのない保守の両方を抱え込むことになります。どの銀行がご自身のものかは、すでにご存じのはずです。

最後の POS は削除できず、最後に有効になっているものは無効にできません。カード決済を完全にやめるには、代わりに一般タブで支払い方法をオフにしてください。

無料版で使える POS は一つです。追加のレコードは Pro 版の機能であり、その結果として BIN による振り分けも Pro 版の機能になります。POS が一つしかなければ、振り分ける先がないからです。

銀行 API — 認証情報とゲートウェイのアドレス

銀行: その POS を開設している銀行を選びます。ゲートウェイのアドレスも、分割払いに使う BIN リストも、この選択に従います。まだ実装のない金融機関は「— yakında」(近日対応) と表示され、選択できません。
加盟店番号 (Client ID): 銀行から渡された加盟店番号です。
加盟店キー (Store key): 加盟店のセキュリティキーです。パスワード欄として保存され、保存後はマスク表示されます。
Gate URL: 決済フォームの送信先アドレスです。
テストモードをオンにする: 自動転送を止め、送信前にリクエストの内容を確認できるようにします。

保存時に Store Key を空欄のままにすることは、「変更しない」という意味です。空の値を書き込めば鍵が消え、エラーメッセージ一つ出ないまま、ストアは決済を受け付けなくなります。他の秘密情報の欄にも同じ規則が適用されます。

一部のプロトコル系統では追加の認証情報が必要で、フォームは選んだ銀行の分だけを表示します:

Garanti BBVA — Merchant ID、認証ユーザー名、認証パスワード。
VakıfBank — Terminal No (端末番号) と MPI のアドレス (空欄にするとテスト用アドレスが使われます)。
PayTR — Merchant Salt。
iyzico、Craftgate、Sipay — 追加の項目はありません: API キーを加盟店番号に、シークレットを加盟店キーに入力します。

これらの追加の認証情報は署名に組み込まれます。一つでも欠けていると、署名は空の値で計算され、銀行は黙って決済を拒否します。エラーもメッセージも出ず、ただ拒否されるだけです。

NestPay 系の 7 行については、銀行の選択からゲートウェイのアドレスが自動的に入るため、Gate URL は空欄のままで構いません。それ以外では自動入力されないので、銀行または決済事業者から渡されたアドレスを入力してください。入力しないと、決済フォームの送信先がありません。

対応している 13 の金融機関

NestPay / Asseco (Payten): İş Bankası、Akbank、Halkbank、QNB、Şekerbank、TEB、Ziraat Bankası
Garanti GT3D: Garanti BBVA
PayFlex V4: VakıfBank
決済事業者: iyzico、PayTR、Craftgate、Sipay

実装のない金融機関は「— yakında」と付けて意図的に銀行リストに残してあります。取り除いてしまうと、どのプロトコル系統がまだ未対応なのかが見えなくなります。お使いの銀行がその一つであれば、銀行リクエストタブでお知らせください。

銀行自身が公開している例に照らしたゴールデンベクターのテストがあるのは、NestPay の署名だけです。それ以外の事業者は、ソースコード上で beta と記されています。処理の流れはドキュメントどおりに実装してありますが、その金融機関の実際の加盟店アカウントで端から端まで検証できてはいません。検証が済むまで、この表示は外しません。

決済事業者はカードを発行しないため、BIN リストを持ちません。振り分け先としてではなく、ご自身の POS として選択します。

BIN による振り分け

カードの最初の 6 桁が、発行銀行を示します。MevvPos は、まさにその 6 桁で照合します。

BIN 表のスナップショットはプラグインに同梱されています。現在のビルドでは 36 行分・1.449 件の BIN です。そのため、無料版でも、インストールした瞬間からオフラインで振り分けが機能します。
Pro 版では、当社サーバーから毎週更新されます。この更新は同梱の表を置き換えるのではなく、上書きして統合します。不完全な応答や空の応答によって、ストアが BIN データを一切持たない状態に陥ってはならないからです。
BIN が 100 件に満たない応答は、あり得ないものとして拒否され、書き込まれません。
同じ BIN を二つの銀行が主張するような衝突は、一覧を送る前に当社側で解決します。ストア側で解決させると、あるカードを「自行のもの」と数えながら、同時に別の先へ振り分けてしまうことが起こり得ます。

認識できない BIN が拒否されることはありません。既定の POS へ回されます。単に記録が無いだけのカードを断ることは、参照表を守るために売上を捨てるのと同じです。

同じ表は、購入手続きの場でもう一つ別の問いにも答えます。このカードは、この POS の銀行のものか? という問いです。分割払いを提示するかどうかは、これで決まります。詳しくは以下をご覧ください。

BIN の正確さは有料の機能ではありません。Pro 版で対価を払う対象は正確さではなく、新しさです。同梱の一覧は同じ一覧であり、ビルド時点で固定されているだけです。

分割払いと手数料

料率は POS ごとに、一括払いから 12 回払いまで分割払いと手数料タブで設定します。パーセントで指定します: 5.5% なら 5.50 と書きます。

0: その選択肢は表示され、手数料は加算されません。
空欄: その選択肢はまったく表示されません。空欄とゼロは、同じではありません。

手数料は、「N Taksit Komisyonu」(N 回払い手数料) という課税対象の料金としてカートに表示され、送料と税を含むカート合計をもとに計算されます。

分割払いが提示されるのは、その POS の銀行が発行したカードだけで、これはサーバー側で強制されます。画面上で隠しているだけではありません。他行のカードは一括払いに戻され、手数料も取り消されます。

無料版でお客様に表示される分割回数は最大 3 回です。Pro 版では上限が 12 回に上がります。この上限は三つの場所で適用されます。お客様に見える一覧、フォームから届く値、そして銀行へ送る値です。最後の一つが重要なのは、ライセンスが有効なうちに選ばれた値がセッションに残り得るからです。

設定フォームは、ライセンスに関わらず常に 12 個すべての項目を表示します。ライセンス失効時に項目が消えていたら、ページを保存するだけで、すでに入力済みの料率が黙って削除されてしまいます。上限を超える項目には「Pro で利用可能」と表示され、入力された数値はそのまま保持されます。

銀行から提供される分割払いの表はありません。料率はお客様が入力したものであり、過去の注文の手数料は、その売上が立った日に適用されていた料率で計算されます。今日料率を変えても、昨日のレポートが書き換わることはありません。

決済の流れとカードの取り扱い

どのプロトコル系統でも 3-D セキュアを通ります。非 3D のモードも、それを無効にする設定もありません。

フォーム方式: NestPay、Garanti、PayTR、Sipay: ブラウザが署名済みのフォームを銀行へ送信し、お客様が認証を行い、銀行がサイトへ戻します。
サーバー方式: VakıfBank、iyzico、Craftgate: サーバーが事業者と通信して 3-D の画面を受け取り、それを表示し、認証後にサーバー間で決済を完了します。

銀行は常に、サイト上の一つのアドレス ?wc-api=mevvpos_callback へ戻します。その戻り値の署名は、注文自体に記録された、実際に使われた POS の鍵で検証されます。POS が複数ある場合、誤った鍵で検証すれば、すべての決済でハッシュエラーが発生します。

カード情報がデータベースに届くことはありません。転送のあいだだけブラウザに保持され、その後は削除されます。支払いページの読み込み時にそれが無い場合 — 新しいタブ、再読み込み、ストレージの無効化、銀行からの戻る操作 — は、空の項目を銀行へ送るのではなく、カード入力フォームを表示します。カードフォームが既定で表示されているのは意図的です。決済の流れが、JavaScript が動いたことを前提にしてはならないからです。

銀行が決済を承認した場合、3-D のステータスコードが想定外であっても、注文は完了します。注文メモにその異常が記録され、銀行自身の画面で確認するよう促されます。銀行が承認したと言うなら、お客様はすでに課金されています。それを拒否すれば「カードは課金されたのに注文は失敗した」という事態になります。

決済の試行ごとに、使用した POS、カードの銀行と BIN、分割回数と料率、結果、銀行の応答コードとメッセージ、そしてオーソリと取引の参照番号が記録されます。

レポート

レポートタブには、売上、成功した取引、成功率、一括払いと分割払いの内訳が日次のグラフとともに表示されます。銀行からの応答をまだ待っている取引は別に数えられ、成功率には含まれません。

無料版のレポートは 30 日固定の期間です。Pro 版では 7 / 30 / 90 日の期間と、三つの内訳が加わります:

分割払いと手数料の負担 — 分割回数ごとの件数、売上、手数料負担。
POS 別・銀行別の内訳 — POS ごと、発行銀行ごとの売上、成功、失敗、成功率。
拒否コードの分布 — CSV 書き出し付き。繰り返し現れる拒否コードは、直せる問題を指し示しています。残高不足はお客様側の問題ですが、3-D 認証や POS 設定のエラーはご自身の問題です。

レポートのもとになるデータを収集するのは無料版のプラグインです。そのため、Pro 版の有無にかかわらず履歴は蓄積され続けます。そうでなければなりません。アップグレードした時点で、過去のデータを後から作り出すことはできないからです。

導入したばかりのストアには、グラフがありません。記録はプラグインの導入とともに始まり、最初の決済の試行があってから画面が埋まっていきます。

銀行申請とサポート

銀行リクエスト: まだ実装していない金融機関を、その理由とともに一覧表示します。プロトコル系統が判明していないか、系統は分かっているがドキュメントを待っている、のいずれかです。特定の金融機関について申請を出すことも、一覧に無い金融機関の名前を挙げることもできます。
サポート: 件名、対象となる POS または銀行、どの操作で何が起きるか、そして銀行が表示したエラーメッセージ。

サポートフォームでは、カード番号やセキュリティコードを含めないようお願いしています。決済の問題を切り分けるのに、それらが必要になることはありません。また、どちらのフォームでも決済情報やカード情報が送信されることはありません。

無料版のプラグインが当社サーバーに接続するのは、これらのボタンを押したときだけです。定期的に送信されるものはなく、無料版にライセンス確認の通信は一切ありません。

無料版と Pro 版

線引きは機能ではなく、数量にあります。13 の金融機関すべて、3-D セキュア、テストモード、取引件数の無制限、基本の売上レポートは、いずれも無料版に含まれます。

無料: POS は一つ。お客様に表示される分割回数は最大 3 回。30 日固定の売上サマリー。プラグイン同梱の BIN 表。
Pro: POS レコードは無制限 — つまり BIN による振り分けが可能に。分割回数は最大 12 回。レポートの期間選択と、POS 別・銀行別・分割回数別・拒否コード別の内訳、および CSV 書き出し。毎週の BIN の自動更新。Pro プラグイン自体の自動アップデート。

ライセンスが失効した、または無い場合:

ストアは決済を受け付け続けます。決済の経路に、ライセンス確認は一つもありません。ストアの売上を止めることは、更新を促す手段として許されるものではありません。
既定の POS は、3-D セキュアとテストモードを含めて動作し続けます。
追加の POS レコードは休止しますが、認証情報も含めて削除されることはありません。更新すれば再開します。
分割回数の上限は 3 回に戻ります。それを超える回数に入力した料率は、消去されずに保持されます。
レポートは 30 日のサマリーに戻ります。蓄積された履歴が削除されることはありません。
BIN の自動更新は止まりますが、同梱の表は動き続けます。

当社のサーバーに接続できない場合でも、有効なライセンスは最後に成功した確認を根拠に 7 日間は動作し続けます。ただし、ライセンス自体の有効期限を過ぎている場合は、いずれにせよ失効として扱われます。そうでなければ、当社のアドレスを遮断することが、ライセンスを 1 週間延ばす手段になってしまいます。

うまく動かないとき

銀行がすべての決済を拒否し、有益なメッセージも出ない: ほとんどの場合、署名が原因です。署名が誤っていても、どこにもエラーは出ません。銀行はただ拒否するだけです。加盟店番号、ストアキー、そしてその系統で必要な追加の認証情報を確認してください。いずれも署名に組み込まれます。有用な確認方法として、銀行は署名エラーと無効なカードとで異なる応答を返します。「無効なカード」というメッセージが返るなら、署名は正しいということです。
POS が複数あるとき、戻りで「ハッシュエラー」が出る: 戻りは、セッションを持たない別のリクエストです。MevvPos は、その注文がどの POS を使ったかを記録し、その鍵で検証します。決済に使われた POS レコードを削除してしまうと、検証は既定の POS にさかのぼって行われ、失敗することがあります。
お客様が空の支払いページに着く、または Öde (支払う) ボタンが反応しない: キャッシュや最適化のプラグインがスクリプトを遅延させています。LiteSpeed では、mevvpos、jquery、および WooCommerce のフロントエンドスクリプトを遅延の対象から除外してください。カードフォームは既定で表示されるため処理自体は進みますが、自動転送は動きません。
決済に成功したのに、注文が「保留中」のまま: 銀行または決済事業者が、コールバックのアドレスに到達していません。?wc-api=mevvpos_callback が外部から到達できるか確認してください。メンテナンスモード、IP 制限、サイト前面のログイン要求は、これを遮ります。
決済フォームが同じページに送信されてしまう: アドレスが自動入力されない銀行で、Gate URL の欄が空になっています。銀行または決済事業者から渡されたアドレスを入力してください。
テストモードなのに、決済が本番の銀行へ送られる: テストモードは自動転送を止め、リクエストの内容を表示するものです。NestPay 系の銀行について、ゲートウェイのアドレスを書き換えることはありません。テスト中は、銀行のテスト用アドレスを Gate URL に入力してください。
分割払いが表示されない: その回数の料率がゼロではなく空欄になっているか、カードが他行のものであるか、無料版の上限である 3 回を超えているかのいずれかです。
アップグレード後、カードが誤った POS に振り分けられる: 旧バージョンには手書きの BIN 範囲が含まれており、一部が誤っていました。各 POS が、実際に開設している銀行の下に登録されているか確認してください。
管理画面のスタイルが当たらない、または修正が反映されない: ブラウザのキャッシュが古くなっています。キャッシュを迂回してページを再読み込みしてください。

できないこと

以下はいずれも意図したものです。不具合ではありません。

WordPress からの返金・取消はできません。このプラグインは WooCommerce の返金 API を実装しておらず、どの事業者にも返金の呼び出しを備えていません。返金は銀行自身の画面から行ってください。
トルコリラのみ対応。通貨コードはどの事業者でも固定されており、多通貨の設定はありません。
カードの保存、トークン化、サブスクリプションや継続課金には対応しません。
与信枠の確保 (プリオーソリ) はありません。すべての取引は即時の売上計上です。
ルールベースの振り分けはありません。振り分けは発行銀行のみによって行われ、金額、カードブランド、国は使いません。
決済フォームは、従来型の WooCommerce チェックアウト向けに作られています。ブロック版チェックアウト用の専用コンポーネントは、パッケージに含まれていません。
3D Pay Hosting は意図的に採用していません。銀行側のホスト型ページは PCI の対象範囲を減らしますが、同時に BIN と分割払いの表も失わせます。そしてこのプラグインの価値のすべては、それらによって可能になる振り分けにあります。
BIN の編集画面はありません。この表は当社が管理し、自動更新によって統合されます。手作業で編集する画面は用意していません。
26 の金融機関が一覧に載っていますが、未実装です。不足がはっきり見えるように、表示したままにしてあります。
NestPay を除くすべての事業者は、自らベータと宣言しています。実際の加盟店アカウントで端から端まで検証できるまで、この表示は続きます。
タブはページ内のものです。サイドバーの項目は MevvPos の画面を開きます。タブの切り替えは、そのページ上で行ってください。

どのような形でも保存しないもの: カード番号、有効期限、セキュリティコード。保持されるカード関連の情報は、最初の 6 桁と、そこから特定される銀行名だけです。セキュリティコードの保存はいかなる場合も禁じられており、マスクしたものであっても桁数が漏れてしまいます。

一つのバーチャルPOS から、カードを発行銀行へ振り分けるところまで。