HandyCafe Docs
owner it-admin

Integrasi POS

Halaman pengaturan Integrasi menghubungkan server HandyCafe yang memenuhi syarat ke terminal Ödeal D2D. Ketersediaannya diperiksa melalui HandyCafe Cloud. Menu dan halaman ini disembunyikan sepenuhnya ketika kafe tidak diizinkan memakai Ödeal.

Sebelum Anda Mulai

Anda memerlukan langganan HandyCafe Cloud yang aktif, merchant key Ödeal serta secret key Ödeal. Anda juga harus membuat terminal di area Cihazlarım milik Ödeal. Nama persis yang diberikan pada terminal tersebut adalah externalDeviceKey-nya. Mulailah dengan lingkungan Stage. Beralihlah ke Production hanya setelah Ödeal menyetujui kredensial produksi dan penyiapan callback.

Mengonfigurasi Ödeal

  1. Buka Pengaturan lalu pilih Integrasi.
  2. Pada Akun Ödeal, masukkan merchant key dan secret key yang diberikan Ödeal. HandyCafe mengirim nilai ini langsung ke HandyCafe Cloud. Nilai tersebut dienkripsi serta tidak disimpan di database lokal maupun ditampilkan kembali.
  3. Pilih Tes Koneksi. Ketika ada kunci baru, HandyCafe menyimpannya secara aman sebelum menguji koneksi ke API Ödeal. Tes ini hanya memverifikasi akun Ödeal. Tes ini tidak membuktikan bahwa terminal sudah dipasangkan atau sedang online.
  4. Tambahkan terminal. Masukkan nama perangkat lokal yang jelas. Untuk Nama perangkat Ödeal (externalDeviceKey), masukkan nama perangkat persis seperti yang dibuat di Ödeal. Kemudian isi PaxID opsional, lingkungan, waktu tunggu pembayaran, kota pelanggan, distrik pelanggan, tarif PPN sesi serta tarif PPN pesanan.
  5. Aktifkan Integrasi POS Aktif lalu pilih Simpan.
  6. Selesaikan satu struk tunai Stage dan satu pembayaran kartu Stage untuk memverifikasi pemasangan terminal serta kedua jalur penyelesaian pembayaran.

Hanya satu terminal Ödeal aktif yang didukung per server pada rilis ini. Hal ini mencegah pembayaran dialihkan ke terminal yang tidak dituju sebelum pemilih terminal untuk kasir tersedia.

HandyCafe menyimpan inventaris terminal secara lokal sebelum Cloud memverifikasi pasangan kredensial baru. Penolakan kredensial oleh Ödeal tidak menghapus nama terminal atau kolom pemasangannya. Terminal yang memerlukan kredensial baru disimpan sebagai tidak aktif sampai kredensial tersebut diverifikasi untuk lingkungan yang dipilihnya.

Halaman Integrasi membaca inventaris terminal langsung dari database SQLite lokal dan menampilkannya tanpa menunggu Cloud. Hanya status kredensial terenkripsi serta izin penyedia jarak jauh yang memerlukan permintaan ke Cloud.

Jika Ödeal menolak konfigurasi, HandyCafe menampilkan penjelasan yang dikembalikan Ödeal. Respons organization profile not found berarti pasangan merchant dan secret tidak terdaftar pada organisasi mana pun di lingkungan Stage atau Production yang dipilih.

Perilaku Pembayaran

Ketika metode pembayaran yang aktif adalah tunai atau kartu, penutupan sesi PC, penutupan sesi konsol serta penutupan pesanan mandiri mengirimkan keranjang idempoten ke Ödeal. Tunai dikirim sebagai opsi pembayaran CASH sesuai dokumentasi Ödeal. Terminal mencatat pembayaran tunai lalu mencetak slip fiskal atau struk e-Archive tanpa membuka layar penagihan kartu. Kartu dikirim sebagai CREDITCARD; HandyCafe menunggu hasil callback selagi pelanggan menyelesaikan pembayaran di terminal. Penutupan yang memuat tunai sekaligus kartu mengirimkan kedua opsi pembayaran beserta jumlahnya masing-masing.

Pelanggan dapat memilih opsi cicilan di terminal ketika kartu dan perjanjian merchant mendukungnya. HandyCafe menyimpan jumlah cicilan yang dilaporkan bersama penjualan lokal. Penjualan lokal hanya dicatat setelah Ödeal mengonfirmasi transaksi. Jika pencatatan lokal gagal setelah konfirmasi, HandyCafe meminta pembatalan pada hari yang sama. Pembatalan yang gagal menghasilkan kesalahan rekonsiliasi manual dan harus diperiksa pada laporan transaksi Ödeal. Jenis metode pembayaran selain tunai dan kartu tetap berjalan melalui alur penyelesaian HandyCafe yang sudah ada.

Pengujian dan Operasi Terminal

Tes Koneksi hanya memverifikasi kredensial merchant Ödeal serta akses API. Tes ini tidak mencetak struk, tidak menagih kartu dan tidak membuktikan bahwa externalDeviceKey sudah dipasangkan dengan terminal.

Dokumentasi API D2D yang tersedia tidak mendefinisikan endpoint Cetak Struk Uji atau Uji Penagihan secara terpisah. Pengujian penerimaan memakai keranjang biasa di lingkungan Stage: kirim keranjang tunai lalu periksa slip yang tercetak, kemudian kirim keranjang kartu dan selesaikan transaksi sekali bayar atau cicilan di terminal. Gunakan hanya detail kartu uji Stage yang disediakan Ödeal.

Kasus penerimaan Ödeal mencakup tutup hari dan cetak ulang struk terakhir, tetapi keduanya adalah operasi terminal. D2D tidak mendokumentasikan panggilan API jarak jauh untuk keduanya, sehingga HandyCafe tidak menyediakannya sebagai tombol jarak jauh.

Mengaktifkan dan Menonaktifkan dari Jarak Jauh

Administrator HandyCafe mengendalikan Ödeal dari Admin > Pengaturan Admin > Penyedia POS di Dasbor. Sakelar global adalah kendali utama. Nilai bawaan per negara memakai kode ISO dua huruf seperti TR. Kontrol kafe dapat membuka atau menutup Ödeal secara eksplisit untuk satu lisensi. Keputusan khusus kafe mengesampingkan nilai bawaan negaranya. Mengatur ulang keputusan kafe membuat kafe itu kembali mengikuti negaranya.

Urutan keputusannya adalah sakelar global, keputusan khusus kafe lalu nilai bawaan negara. Sakelar global yang mati menutup Ödeal untuk setiap kafe. Penutupan kafe secara eksplisit menyembunyikan halaman meskipun negaranya terbuka. Pembukaan kafe secara eksplisit mengizinkan halaman meskipun negaranya tidak ada dalam daftar bawaan. Mematikan akses langsung memblokir pembuatan keranjang baru. Transaksi tertunda yang sudah ada masih dapat diperiksa atau dibatalkan supaya pembayaran yang sedang berjalan tidak terkatung-katung.

Server memeriksa ketersediaan melalui HandyCafe Cloud dan menyimpan cache keputusan negara/kafe terakhir yang berhasil diverifikasi. Katalog penyedia mengembalikan HTTP 200 dengan error.code terstruktur ketika kredensialnya tidak valid. Desktop menangani respons itu dengan menyegarkan kredensial lalu mencoba lagi. Kegagalan autentikasi atau jaringan yang bersifat sementara tidak membuat keputusan admin yang mengaktifkan Ödeal ditafsirkan sebagai penonaktifan, sehingga menu Integrasi tetap stabil. Respons berikutnya yang berhasil langsung memperbarui cache, termasuk keputusan admin untuk menonaktifkan. Tanpa keputusan yang pernah diverifikasi sebelumnya, negara kafe yang tidak diketahui, langganan yang tidak aktif atau penyedia yang dinonaktifkan membuat halaman tetap tersembunyi. Operasi Ödeal yang baru selalu diotorisasi ulang oleh Cloud sekalipun visibilitas dari cache sedang dipakai. Negara yang tersimpan pada lisensi dipakai ketika profil kafe yang disinkronkan tidak memiliki negara.

Keamanan dan Pemulihan

Kredensial Ödeal dienkripsi di HandyCafe Cloud dengan kunci vault deployment. Permintaan callback diautentikasi oleh kunci permintaan yang dikonfigurasi atau oleh header merchant dan secret Ödeal. Kode referensi keranjang bersifat tetap untuk setiap pesanan atau sesi. Mengulangi penutupan yang sama tidak menciptakan tagihan kedua.

Pembatalan di Ödeal hanya tersedia dalam aturan hari yang sama milik Ödeal, yaitu sebelum batch terminal ditutup. Keranjang yang tertunda dapat dihapus secara terpisah sebelum pembayaran selesai. Ödeal D2D tidak menyediakan operasi pengembalian dana umum. Gunakan back office dan laporan transaksi Ödeal ketika jendela pembatalan sudah lewat.

Ödeal D2D tidak menyediakan operasi laporan Z atau tutup hari jarak jauh yang terdokumentasi. Selesaikan tutup hari di terminal. HandyCafe dapat membaca laporan transaksi untuk rekonsiliasi serta mencatat callback payback dari Ödeal.