Qris-Soundbox/13-fase1-step2-callback-transaction-spec.md

# Fase 1 — Step 2: Transaction Engine + Webhook Callback (Spesifikasi Implementasi)

Dokumen ini merinci implementasi callback QRIS, state machine transaksi, dan eventing dasar untuk alur static flow.

## 1) Tujuan Step 2
- Menerima callback pembayaran dari partner secara aman dan idempotent
- Menyimpan state transaksi dari `initiated` sampai `paid/failed/expired`
- Menyimpan jejak event untuk audit dan observability
- Menyiapkan output event agar notifikasi MQTT dan pelaporan ops bisa dipicu

## 2) Alur State Transaksi (Static Flow)

1. `initiated`
2. `awaiting_payment`
3. `paid`
4. `failed`
5. `expired`
6. `reversed` (opsional untuk fase awal)

### Transisi Utama
- `initiated` -> `awaiting_payment`
  - terjadi saat transaksi static dibuat dari mapping merchant/outlet/terminal
  - saat ini boleh dilakukan di Step 2 sebagai fallback/manual test
- `awaiting_payment` -> `paid`
  - terjadi saat callback partner valid dengan status success
- `awaiting_payment` -> `failed`
  - status partner gagal/declined/rejected
- `awaiting_payment` -> `expired`
  - expiry waktu lewat atau event timeout dari partner
- `failed` / `paid` adalah terminal state untuk Step 1

## 3) API Endpoint: Webhook Callback

### Endpoint
- `POST /integrations/qris/callback`

### Request Headers
- `X-Partner-Signature`: signature HMAC (mandatory)
- `X-Partner-Event`: jenis event
- `Idempotency-Key` (jika tersedia dari partner)
- `X-Request-Id` (opsional, gunakan untuk trace)

### Behavior
- Validasi signature sebelum payload diproses
- Jika signature invalid: response `401` dan tidak membuat transaksi
- Parsing event_type:
  - sukses -> candidate `paid`
  - gagal -> candidate `failed`
  - expired / timeout -> candidate `expired`
- Kunci idempotency:
  - key = kombinasi partner_reference + signature_reference/transaction_reference + status event
- Jika sudah diproses:
  - kembalikan response sukses idempotent (tanpa mengubah state lagi)

### Request/Response Format
- Response sukses:
  - `status`: `accepted`
  - `request_id`
  - `event_id`
  - `timestamp`
- Response error:
  - envelope dari keputusan `D-003`

## 4) Validasi Callback

### Required Fields (minimum)
- `partner_reference`
- `amount`
- `currency` (default `IDR`)
- `status` / `payment_status`
- `paid_at`
- `merchant_id` / `terminal_id` / mapping key lain dari payload partner
- `signature`

### Validasi Data
- `amount > 0`
- transaksi ditemukan: mapping `partner_reference` ke `transactions.partner_reference` (atau lookup `merchant_reference`)
- status yang tidak dikenali -> log warning dan set ke `failed` dengan reason `UNKNOWN_STATUS`
- cek expiry jika ada (`expired_at`) saat status sukses masuk -> jika expired, set `failed` / `expired`

## 5) Idempotency Strategy

### Tabel Idempotency
- gunakan `idempotency_keys` yang sudah didefinisikan di Step 1
- scope: `callback_processing`
- key value: hash dari `(partner_reference + payment_status + partner_txn_id)`
- jika key sudah ada:
  - return hasil callback yang sama (replay safe)

## 6) Transaction Store yang Diperlukan

### `transactions`
- fields yang harus dipopulasi di Step 2:
  - `merchant_id`, `outlet_id`, `terminal_id`, `device_id` (jika static device direct binding)
  - `qr_mode` = `static`
  - `initiation_mode` = `static`
  - `partner_reference`
  - `amount`, `currency`, `status`
  - `created_at`, `paid_at`, `expired_at`, `updated_at`

### `transaction_events`
- event wajib untuk setiap perubahan state:
  - `event_type`: `INITIATED`, `STATE_CHANGED`, `CALLBACK_RECEIVED`, `CALLBACK_REJECTED`, `CALLBACK_DUPLICATE`, `PUSH_QUEUED`
  - `source`: `webhook`, `system`, `admin`
  - `payload_json`: raw payload callback + context
- urutan event dipakai untuk debugging urut transaksi

## 7) Integrasi Ke Step 3 (Notifikasi)
- ketika state transaksi berubah ke `paid`, emit event internal:
  - `transaction.paid`
  - payload ringan: `transaction_id`, `merchant_id`, `device_id`, `amount`, `currency`, `partner_reference`, `paid_at`
- event ini menjadi trigger awal untuk notification orchestrator Step 3
- jika transaction tidak punya binding aktif:
  - event tetap tercatat dengan reason `NO_ACTIVE_BINDING`

## 8) Error Code (saran)
- `WEBHOOK_SIGNATURE_INVALID`
- `TRANSACTION_NOT_FOUND`
- `PAYMENT_STATUS_INVALID`
- `DUPLICATE_WEBHOOK`
- `CALLBACK_PARTNER_DATA_INVALID`
- `IDEMPOTENCY_MISSING_KEY`

## 9) Contoh Pseudocode Alur Handler

1. terima payload
2. validasi signature
3. normalisasi `request_id` dan `event_id`
4. ambil `partner_reference` -> cari transaksi
5. cek idempotency callback
6. jika duplikat: simpan `transaction_events` duplicate dan return success
7. validasi transaksi + status
8. update status + paid_at jika sukses
9. simpan event (`CALLBACK_RECEIVED`, `STATE_CHANGED`)
10. emit `transaction.paid` (hanya saat sukses)
11. commit
12. return response success

## 10) API/Query untuk Operasional (minimal)
- `GET /admin/transactions` tetap support filter `status`, `merchant_id`, `from`, `to`, `partner_reference`
- `GET /admin/transactions/{transactionId}` menampilkan event timeline
- `GET /admin/transactions/{transactionId}/events` opsional di Step 2 untuk debug

## 11) Acceptance Criteria Step 2
- webhook menerima callback valid dan mengubah state transaksi ke `paid`
- callback duplicate tidak menambah perubahan state tambahan
- signature invalid ditolak `401`
- jika partner reference tidak ditemukan, response tetap deterministik dan tidak crash
- setiap perubahan state menghasilkan `transaction_events` minimal satu baris
- setiap perubahan ke `paid` menghasilkan event internal `transaction.paid` untuk Step 3

## 12) Keberhasilan Handoff ke Step 3
- state machine stabil dan bisa dipakai unit/integration smoke
- transaksi berhasil dan gagal terekam lengkap
- callback replay aman
- notifikasi orchestrator dapat subscribe pada event `transaction.paid`