HandyCafe Docs
owner it-admin

POS Integrations

The Integrations settings page connects an eligible HandyCafe server to an Ödeal D2D terminal. Availability is checked through HandyCafe Cloud. The menu and page are completely hidden when the cafe is not allowed to use Ödeal.

Before You Start

You need an active HandyCafe Cloud subscription, an Ödeal merchant key and an Ödeal secret key. You must also create the terminal in Ödeal's Cihazlarım area. The exact name assigned to that terminal is its externalDeviceKey. Start with the Stage environment. Switch to Production only after Ödeal has approved the production credentials and callback setup.

Configure Ödeal

  1. Open Settings and select Integrations.
  2. In Ödeal Account, enter the merchant key and secret key provided by Ödeal. HandyCafe sends these values directly to HandyCafe Cloud. They are encrypted and are not stored in the local database or displayed again.
  3. Select Connection Test. When new keys are present, HandyCafe saves them securely before testing the Ödeal API connection. This test verifies the Ödeal account only. It does not prove that the terminal is paired or online.
  4. Add the terminal. Enter a clear local device name. For Ödeal device name (externalDeviceKey), enter the exact device name created in Ödeal. Then enter the optional PaxID, environment, payment wait time, customer city, customer district, session VAT rate and order VAT rate.
  5. Enable POS Integration Active and select Save.
  6. Complete a Stage cash receipt and a Stage card payment to verify terminal pairing and both settlement paths.

Only one active Ödeal terminal is supported per server in this release. This prevents a payment from being routed to an unintended terminal before a cashier terminal selector is available.

HandyCafe saves the terminal inventory locally before Cloud verifies a new credential pair. An Ödeal credential rejection does not discard the terminal name or pairing fields. A terminal that needs new credentials is stored as inactive until those credentials are verified for its selected environment.

The Integrations page reads terminal inventory directly from the local SQLite database and displays it without waiting for Cloud. Only the encrypted credential status and remote provider permission require a Cloud request.

If Ödeal rejects the configuration, HandyCafe displays Ödeal's returned explanation. An organization profile not found response means the merchant and secret pair does not belong to an organization in the selected Stage or Production environment.

Payment Behavior

When the active payment method is cash or card, PC session checkout, console session checkout and standalone order closure send an idempotent basket to Ödeal. Cash is sent as Ödeal's documented CASH payment option. The terminal records the cash payment and prints the fiscal slip or e-Archive receipt without opening a card collection screen. Card is sent as CREDITCARD; HandyCafe waits for the callback result while the customer completes the payment on the terminal. A checkout containing both cash and card sends both payment options with their respective amounts.

The customer can choose an installment option on the terminal when the card and merchant agreement support it. HandyCafe stores the reported installment count with the local sale. The local sale is committed only after Ödeal confirms the transaction. If the local commit fails after confirmation, HandyCafe requests a same-day cancellation. A failed cancellation produces a manual reconciliation error and must be checked in the Ödeal transaction report. Payment method types other than cash and card continue through the existing HandyCafe settlement flow.

Tests and Terminal Operations

Connection Test only verifies the Ödeal merchant credentials and API access. It does not print a receipt, charge a card or prove that externalDeviceKey is paired with the terminal.

The supplied D2D API documentation does not define separate Print Test Receipt or Test Charge endpoints. Acceptance testing uses normal baskets in the Stage environment: send a cash basket and verify the printed slip, then send a card basket and complete a single-payment or installment transaction on the terminal. Use only Ödeal-provided Stage test card details.

The Ödeal acceptance cases include day close and last-receipt reprint, but these are terminal operations. D2D does not document remote API calls for them, so HandyCafe does not expose them as remote buttons.

Remote Enable and Disable

HandyCafe administrators control Ödeal from Admin > Admin Settings > POS Providers in the Dashboard. The global switch is the master control. Country defaults use two-letter ISO codes such as TR. Cafe controls can explicitly open or close Ödeal for one license. A cafe-specific decision overrides the country default. Resetting the cafe decision makes that cafe follow its country again.

The decision order is global switch, cafe-specific decision then country default. A disabled global switch closes Ödeal for every cafe. An explicit cafe close hides the page even when its country is open. An explicit cafe open allows the page even when its country is not in the default list. Turning access off blocks new basket creation immediately. Existing pending transactions can still be checked or cancelled so an in-progress payment is not stranded.

The server checks availability through HandyCafe Cloud and caches the last successfully verified country/cafe decision. The provider catalog returns HTTP 200 with a structured error.code when its credential is invalid. The desktop handles that response by refreshing the credential and retrying. A temporary authentication or network failure does not reinterpret an enabled admin decision as disabled, so the Integrations menu remains stable. A successful later response updates the cache immediately, including an admin disable decision. With no previously verified decision, an unknown cafe country, inactive subscription or disabled provider keeps the page hidden. New Ödeal operations are always authorized again by Cloud even when cached visibility is used. The country saved on the license is used when the synchronized cafe profile has no country.

Security and Recovery

Ödeal credentials are encrypted in HandyCafe Cloud with the deployment vault key. Callback requests are authenticated by the configured request key or by the Ödeal merchant and secret headers. Basket reference codes are stable for each order or session. Repeating the same checkout does not create a second charge.

Ödeal cancellation is available only under Ödeal's same-day rules before the terminal batch closes. A pending basket can be removed separately before payment completes. Ödeal D2D does not provide a general refund operation. Use the Ödeal back office and transaction report when a cancellation window has passed.

Ödeal D2D does not provide a documented remote Z report or close-day operation. Complete the day close on the terminal. HandyCafe can read transaction reports for reconciliation and records payback callbacks from Ödeal.