QRIS Gateway | Real Simulation Flows

Real Simulation Playbook

Operational flow for Error Handling and Incident Investigation

Cara Baca Halaman

1. KPI + Bagian 1-3 untuk validasi create/query/callback dari data DB.

2. Error Handling untuk simulasi edge case dan recovery delivery.

3. Incident Investigation untuk investigasi insiden dan recovery.

Flow Use Case KPI Core Flow Error Handling Snapshot Investigation

Operational Design

Flow End-to-End QRIS

Alur teknis dari create QR, pembayaran, callback, sampai notifikasi merchant.

Flow

sequenceDiagram
    autonumber
        actor U as User
        participant M as Merchant
        participant G as Payment Gateway (Manjo)
        participant B as Switching/Bank
    participant O as Outbox Worker

        M->>G: Generate QR (Create Transaksi)
        G-->>M: QRIS Data + transactionNo
        Note over M,G: Status awal: PENDING

        M-->>U: Tampilkan QR
        U->>B: Scan QR dan lakukan pembayaran
        B->>G: Proses otorisasi pembayaran
        B-->>G: Callback hasil pembayaran

        G->>G: Validasi signature + parse payload
        G->>G: Update qris_transactions
        G->>G: Tulis callback_logs + transaction_status_histories

        alt Pembayaran berhasil
            G->>G: Set status SUCCESS + settlement upsert
        else Pembayaran gagal
            G->>G: Set status FAILED/REJECTED/EXPIRED
        end

        G->>G: Insert merchant_notification_outboxes (PENDING)
        O->>G: Dispatch outbox (sync/worker)
        O-->>M: Kirim notifikasi status transaksi
        M-->>O: ACK / gagal (retry)

Step 1

Create transaksi -> status awal PENDING.

Step 2

Pembayaran diproses issuer/acquirer.

Step 3

Callback update status + settlement.

Step 4

Outbox dispatch notifikasi ke merchant.

Operational Design

Use Case Sistem

Use case utama aktor merchant, customer, gateway, dan operator saat operasi normal maupun insiden.

Use Case

flowchart LR
    Merchant(("👤 Merchant"))
    User(("👤 User/Pelanggan"))
    Bank(("👤 Switching/Bank"))
    Outbox(("👤 Outbox Worker"))
    Ops(("👤 Ops/Admin"))

    subgraph SYS[QRIS Payment Gateway System]
      UC1([UC-01
Generate QRIS])
      UC2([UC-02
Scan dan Bayar QRIS])
      UC3([UC-03
Terima Callback Pembayaran])
      UC4([UC-04
Update Status Internal])
      UC5([UC-05
Dispatch Notifikasi Merchant])
      UC6([UC-06
Cek Status Transaksi])
      UC7([UC-07
Retry Outbox])
      UC8([UC-08
Investigasi dan Recovery])
    end

    Merchant --> UC1
    Merchant --> UC6
    User --> UC2
    Bank --> UC2
    Bank --> UC3
    Outbox --> UC5
    Ops --> UC7
    Ops --> UC8

    UC2 -. "include" .-> UC3
    UC3 -. "include" .-> UC4
    UC4 -. "include" .-> UC5
    UC8 -. "extend" .-> UC6
    UC7 -. "extend" .-> UC5

Actor

Merchant, User/Pelanggan, Switching/Bank, Outbox Worker, dan Ops/Admin.

Use Case Utama

UC-01 sampai UC-08 mencakup create, pay, callback, update status, dispatch, query, retry, dan investigasi.

Relasi Use Case

Relasi antar use case memakai pola include dan extend sesuai alur operasional.

Include Chain

UC-02 include UC-03, UC-03 include UC-04, dan UC-04 include UC-05.

Extend Case

UC-08 extend UC-06 (saat mismatch) dan UC-07 extend UC-05 (saat delivery gagal/pending).

Narasi Alur

Alur bergerak dari create transaksi, pembayaran, callback, update internal, dispatch outbox, hingga investigasi dan recovery bila ada anomali.

Total 24h

Pending

Failed / Rejected / Expired

Outbox Pending/Failed

Core Operational Flow (Database-backed)

Ringkasan progres untuk create, query, dan callback/settlement. Detail endpoint tetap di API DOCS.

api Buka API DOCS

qris_transactions

Generate QRIS

Pembuatan transaksi QRIS baru dan validasi idempotency create request.

Total data: 5

transaction_query_logs

Query Status

Pelacakan status transaksi melalui endpoint query hingga status final.

Total data: 2

callback_logs + settlements

Callback & Settlement

Penerimaan callback, update status, dan rekonsiliasi settlement transaksi.

Total data: 6

Error Handling and Edge Case

Simulasi ini memvalidasi callback gagal, retry outbox, idempotency callback, dan sinkronisasi status. Semua langkah didesain supaya bisa dipresentasikan end-to-end saat demo praktikum.

Flow Diagram

flowchart LR
    A["1. Create QR -> PENDING"] --> B["2. Dispatch gagal -> FAILED"]
    B --> C["3. Retry scheduler/aksi admin"]
    C --> D["4. Callback delivered -> SENT"]
    D --> E["5. Notification bell admin"]

    classDef pending fill:#fef3c7,stroke:#b45309,color:#78350f,stroke-width:1px;
    classDef failed fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-width:1px;
    classDef retry fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e,stroke-width:1px;
    classDef success fill:#dcfce7,stroke:#166534,color:#14532d,stroke-width:1px;
    classDef notify fill:#ede9fe,stroke:#6d28d9,color:#4c1d95,stroke-width:1px;

    class A pending;
    class B failed;
    class C retry;
    class D success;
    class E notify;

1. Create QR -> PENDING

2. Dispatch gagal -> FAILED

3. Retry scheduler/aksi admin

4. Callback delivered -> SENT

5. Notification bell admin

4.1 Callback Tidak Diterima

Buat transaksi dari Simulator, lanjut scan dari HP sampai pembayaran SUCCESS.
Set destination callback ke endpoint yang gagal lalu trigger dispatch.
Pastikan outbox berubah ke FAILED dan retry_count naik.
Jalankan retry manual dari Filament: Retry Now atau Retry via Mock Callback.
Expected: status transaksi tetap SUCCESS, outbox akhirnya SENT.

4.2 Callback Duplikat (Idempotent)

Pakai transaksi yang sudah SUCCESS.
Kirim callback success lagi untuk transaksi yang sama.
Expected: sistem return aman tanpa double processing.
Expected: tidak ada perubahan status final kedua kali.

4.3 Status Tidak Sinkron

Buat transaksi PENDING.
Tahan callback sementara atau buat dispatch gagal.
Jalankan query status dari simulator.
Expected: status internal tersinkron ke final state yang valid.

Command Operasional

docker compose exec php php artisan qris:outbox-dispatch --limit=100

docker compose exec php php artisan schedule:run

docker compose exec db mysql -uroot -pp455w0rd manjo -e "SELECT id,delivery_status,retry_count,last_error FROM merchant_notification_outboxes ORDER BY id DESC LIMIT 10;"

Live Delivery Snapshot

Data realtime dari tabel merchant_notification_outboxes.

SUCCESS

PENDING

FAILED

EXPIRED

REJECTED

Outbox ID	Transaction	Delivery
3	TXN-20260725040515-BOGJGI	SENT
2	TXN-MANJO-0001	SENT
1	TXN-20260725035358-RPYYXP	SENT

Investigasi Real Case

Kasus: customer sudah bayar tetapi merchant belum update. Tujuan investigasi adalah membedakan masalah status transaksi vs masalah delivery callback.

A. Reproduce Incident

Customer bayar dari HP sampai SUCCESS.
Paksa notifikasi merchant gagal (dispatch failed).
Hasil: transaksi SUCCESS, merchant belum terupdate.

B. Triage Matrix

If transaction SUCCESS + outbox FAILED: fokus retry callback.
If transaction PENDING: fokus query/sync status.
If outbox SENT tapi merchant belum update: cek endpoint merchant side.

C. Recovery

Trigger retry dari Filament.
Pastikan row outbox berubah ke SENT.
Konfirmasi merchant menerima callback.
Tutup insiden + catat akar masalah.

Acceptance Criteria Demo (PASS/FAIL)

AC-01

Flow sukses dari scan HP sampai notifikasi admin tampil.

AC-02

Dispatch gagal bisa recovery ke SENT via retry.

AC-03

Callback duplikat tidak menimbulkan update ganda.

AC-04

Triage insiden mengarah ke recovery yang tepat.

Simulator (In-Page)

Menu Simulator sekarang tetap di halaman flows ini, tidak pindah halaman.

Quick Links

Jalankan simulasi lalu validasi di dashboard admin.

play_circle Open Simulator notifications Open Admin Panel