Qris-Soundbox/04-device-flows.md

Device Flows - QRIS Soundbox Platform v1

1. Soundbox Static Flow

Karakteristik

• QR merchant bersifat statis
• customer input nominal di aplikasi bank/e-wallet
• device menerima notifikasi hasil transaksi

Sequence

1. customer scan QR statis merchant
2. customer input nominal dan submit pembayaran
3. partner/bank memproses pembayaran
4. callback payment masuk ke backend
5. backend verifikasi signature dan status
6. transaction state diupdate
7. ledger internal diupdate
8. backend lookup binding merchant -> outlet -> terminal -> device
9. notification event dibuat
10. MQTT push ke device
11. device memainkan audio dan/atau menampilkan nominal

Catatan

• challenge utama adalah mapping transaksi ke device yang tepat
• perlu binding yang presisi dan fallback jika device offline

2. Soundbox Dynamic MQTT-only Flow

Karakteristik

• device tidak bisa hit API langsung
• request create QR lewat MQTT
• response dan success notification lewat MQTT

Sequence

1. merchant input nominal di device
2. device publish request create QR ke topic uplink
3. backend MQTT adapter menerima request
4. device auth dan capability check dilakukan
5. backend validasi nominal, merchant binding, idempotency key
6. backend request QR dynamic ke partner QRIS
7. transaction dibuat dengan status pending/awaiting_payment
8. response QR payload dipublish ke topic device
9. device render QR di layar
10. customer scan dan bayar
11. callback payment masuk ke backend
12. backend verifikasi dan update transaction
13. ledger internal diupdate
14. notification success dipublish ke device
15. device memainkan audio sukses

Catatan

• wajib ada request_id / correlation_id
• retry device tidak boleh menimbulkan double create
• MQTT handler jangan jadi pusat logic, hanya ingress adapter

3. Soundbox Dynamic API-direct Flow

Karakteristik

• device dapat call API backend langsung
• create QR dilakukan secara sinkron via API
• success notification tetap realtime via MQTT

Sequence

1. merchant input nominal di device
2. device call API create dynamic QR
3. backend auth device dan validasi payload
4. backend check capability dan idempotency
5. backend request QR dynamic ke partner QRIS
6. transaction dibuat dengan status pending
7. response API berisi QR payload + expiry + transaction reference
8. device render QR
9. customer scan dan bayar
10. callback payment masuk ke backend
11. backend verifikasi dan update transaction
12. ledger internal diupdate
13. success notification dikirim via MQTT
14. device memainkan audio sukses

Catatan

• ini flow paling bersih untuk engineering
• request-response lebih natural, observability lebih baik

4. Heartbeat Flow

1. device kirim heartbeat secara periodik
2. backend update last_seen_at
3. backend simpan health metrics yang tersedia
4. status device diturunkan menjadi online/stale/offline/degraded
5. ops dashboard menampilkan alert bila perlu

5. Provisioning Flow

1. device didaftarkan di TMS
2. credential/token/certificate dibuat
3. device dibinding ke merchant/outlet/terminal
4. config profile ditetapkan
5. device mengambil config awal atau dikirimkan via channel yang tersedia
6. device aktif dan mulai heartbeat