HandyCafe Docs
owner it-admin

POS連携

連携設定ページでは、対象となるHandyCafeサーバーをÖdealのD2D端末に接続します。利用できるかどうかはHandyCafeクラウドを通じて確認されます。カフェがÖdealの利用を許可されていない場合、メニューとページは完全に非表示になります。

はじめる前に

有効なHandyCafeクラウドのサブスクリプション、Ödealのマーチャントキー、Ödealのシークレットキーが必要です。また、ÖdealのCihazlarım（マイデバイス）画面で端末を作成しておく必要があります。その端末に付けた名前が、そのまま externalDeviceKey になります。まずはStage（検証）環境から始めてください。本番環境への切り替えは、Ödealが本番用の資格情報とコールバック設定を承認した後に行います。

Ödealを設定する

  1. 設定を開き、連携を選択します。
  2. Ödealアカウントに、Ödealから提供されたマーチャントキーとシークレットキーを入力します。HandyCafeはこれらの値をHandyCafeクラウドへ直接送信します。値は暗号化され、ローカルデータベースには保存されず、再表示されることもありません。
  3. 接続テストを選択します。新しいキーが入力されている場合、HandyCafeはÖdeal APIへの接続をテストする前に、キーを安全に保存します。このテストで確認できるのはÖdealアカウントだけです。端末がペアリングされていることや、オンラインであることの証明にはなりません。
  4. 端末を追加します。わかりやすいローカルのデバイス名を入力します。**Ödealデバイス名（externalDeviceKey）**には、Ödealで作成した端末名を正確に入力します。続いて、任意項目のPaxID、環境、支払い待ち時間、顧客の市、顧客の地区、セッションのVAT（付加価値税）率、注文のVAT率を入力します。
  5. POS連携を有効化をオンにして、保存を選択します。
  6. Stage環境で現金レシートの発行とカード決済をそれぞれ完了させ、端末のペアリングと両方の精算経路を確認します。

このリリースでは、1台のサーバーにつき有効なÖdeal端末は1台のみサポートされます。キャッシャー向けの端末選択機能が用意されるまで、意図しない端末に支払いが送信されるのを防ぐためです。

HandyCafeは、クラウドが新しい資格情報の組み合わせを検証する前に、端末情報をローカルへ保存します。Ödealが資格情報を拒否しても、端末名やペアリング用の項目が破棄されることはありません。新しい資格情報が必要な端末は、選択された環境でその資格情報が検証されるまで、無効な状態で保存されます。

連携ページは、端末情報をローカルのSQLiteデータベースから直接読み込み、クラウドを待たずに表示します。クラウドへのリクエストが必要なのは、暗号化された資格情報の状態と、リモートのプロバイダー利用許可だけです。

Ödealが設定を拒否した場合、HandyCafeはÖdealから返された説明を表示します。組織プロフィールが見つからないという応答は、マーチャントキーとシークレットキーの組み合わせが、選択したStage環境または本番環境の組織に属していないことを意味します。

決済時の動作

有効な支払い方法が現金またはカードの場合、PCセッションの精算、コンソールセッションの精算、単独の注文の締めでは、冪等なバスケットがÖdealへ送信されます。現金は、Ödealが定める CASH 支払いオプションとして送信されます。端末は現金支払いを記録し、カード決済の画面を開かずに正規レシートまたはe-Archiveレシートを印刷します。カードは CREDITCARD として送信され、顧客が端末で支払いを完了する間、HandyCafeはコールバックの結果を待ちます。現金とカードの両方を含む精算では、それぞれの金額とともに両方の支払いオプションが送信されます。

カードと加盟店契約が対応している場合、顧客は端末で分割払いを選択できます。HandyCafeは、報告された分割回数をローカルの売上とあわせて保存します。ローカルの売上は、Ödealが取引を確認した後にのみ確定されます。確認後にローカルの確定処理が失敗した場合、HandyCafeは当日中のキャンセルを要求します。キャンセルに失敗すると手動照合エラーとなるため、Ödealの取引レポートで確認する必要があります。現金とカード以外の支払い方法は、これまでどおりHandyCafe側の精算フローで処理されます。

テストと端末操作

接続テストで確認できるのは、Ödealのマーチャント資格情報とAPIへのアクセスだけです。レシートの印刷、カードへの課金、externalDeviceKey と端末のペアリングの確認は行いません。

提供されているD2D APIのドキュメントには、テストレシート印刷やテスト課金に相当する専用のエンドポイントは定義されていません。受け入れテストは、Stage環境で通常のバスケットを使って行います。まず現金のバスケットを送信して印刷されたレシートを確認し、次にカードのバスケットを送信して、端末で一括払いまたは分割払いの取引を完了します。テストカードは、Ödealから提供されたStage用のカード情報のみを使用してください。

Ödealの受け入れ項目には日次締めと直前レシートの再印刷が含まれますが、これらは端末側の操作です。D2Dではこれらに対応するリモートAPIが規定されていないため、HandyCafeはリモート操作用のボタンとして提供していません。

リモートでの有効化と無効化

HandyCafeの管理者は、ダッシュボードの管理 > 管理設定 > POSプロバイダーからÖdealを制御します。全体スイッチが最上位の制御です。国ごとの既定値は、TR のような2文字のISOコードで指定します。カフェ単位の制御では、1つのライセンスに対してÖdealを明示的に開放または遮断できます。カフェ単位の判定は、国ごとの既定値より優先されます。カフェ単位の判定をリセットすると、そのカフェは再び自国の既定値に従います。

判定の優先順位は、全体スイッチ、カフェ単位の判定、国ごとの既定値の順です。全体スイッチをオフにすると、すべてのカフェでÖdealが遮断されます。カフェを明示的に遮断すると、その国が開放されていてもページは非表示になります。カフェを明示的に開放すると、その国が既定の一覧に含まれていなくてもページを利用できます。アクセスをオフにすると、新しいバスケットの作成は直ちにブロックされます。進行中の支払いが宙に浮かないよう、既存の保留中の取引は引き続き確認またはキャンセルできます。

サーバーはHandyCafeクラウドを通じて利用可否を確認し、最後に検証に成功した国とカフェの判定をキャッシュします。プロバイダーカタログは、資格情報が無効な場合でもHTTP 200を返し、構造化された error.code を含めます。デスクトップ側はこの応答を受けて資格情報を更新し、再試行します。一時的な認証エラーやネットワーク障害によって、有効という管理者の判定が無効と解釈されることはないため、連携メニューの表示は安定しています。その後の応答が成功すれば、管理者による無効化の判定も含めてキャッシュは直ちに更新されます。以前に検証済みの判定がない状態では、カフェの国が不明、サブスクリプションが無効、プロバイダーが無効のいずれかに該当すると、ページは非表示のままになります。キャッシュされた表示状態を使っている場合でも、新しいÖdealの操作は必ずクラウドで改めて認可されます。同期されたカフェプロフィールに国が設定されていない場合は、ライセンスに保存されている国が使われます。

セキュリティと復旧

Ödealの資格情報は、デプロイメントのボルトキーによってHandyCafeクラウド上で暗号化されます。コールバックのリクエストは、設定されたリクエストキー、またはÖdealのマーチャントヘッダーとシークレットヘッダーによって認証されます。バスケットの参照コードは、注文やセッションごとに一定です。同じ精算を繰り返しても、二重に課金されることはありません。

Ödealのキャンセルは、端末のバッチが締まる前で、かつÖdealの当日ルールの範囲内でのみ利用できます。支払いが完了する前であれば、保留中のバスケットを個別に削除できます。Ödeal D2Dには汎用の返金操作がありません。キャンセル可能な期間を過ぎた場合は、Ödealのバックオフィスと取引レポートを使用してください。

Ödeal D2Dには、リモートからのZレポートや日次締めに相当する規定の操作がありません。日次締めは端末で行ってください。HandyCafeは照合用に取引レポートを読み取り、Ödealからのペイバックコールバックを記録します。