Integration API

Port: 8092 | DB: db_kesles_merchant (schema integration + sandbox) | Status: ✅ ALL PHASES DONE 2026-06-16

Overview

integration_api adalah backend eksklusif untuk apps/merchant_integration (Flutter Web) — platform integrasi dan sandbox testing untuk tiga jenis pengguna:

Pengguna	Kebutuhan
Super Admin	PSP tester, PSP External tester, Partner tester, manage sandbox access
Partner	Testing Partner API dengan credential sendiri (Phase 2 done)
Merchant Tertentu	Simulasi transaksi sandbox QRIS + webhook trigger

Service ini tidak share handler dengan dashboard_api — semua endpoint ditulis ulang di integration_api dengan auth 3-tier.

Auth — 3 Tier

Tier 1: Super Admin JWT  (iss: kesles-merchant-auth)
         → Login via proxy ke auth_service
         → Role check: superAdmin
         → Akses: semua endpoint

Tier 2: Partner Bearer   (iss: kesles-merchant-auth, role: partner)
         → Login via proxy ke partner_service /api/partner/v1/auth/token
         → Akses: /partner/execute endpoint saja

Tier 3: Merchant JWT     (iss: kesles-integration, type: integration_merchant)
         → Login via integration_api sendiri (bcrypt verify)
         → Credential: email + password dibuat khusus oleh super admin
         → Akses: /sandbox/* endpoint merchant sendiri

Database Schema

Schema integration dan sandbox di db_kesles_merchant:

Tabel	Deskripsi
`integration.merchant_accounts`	Akun merchant untuk login ke integration_api (Phase 1, mig 107)
`integration.merchant_sandbox_access`	Whitelist merchant yang boleh akses sandbox (Phase 3, mig 108)
`sandbox.transactions`	Riwayat simulasi transaksi QRIS sandbox (Phase 4, mig 108)
`sandbox.webhook_logs`	Log delivery webhook per transaksi sandbox (Phase 5, mig 108)

Endpoint Lengkap

Auth

POST /api/integration/v1/auth/login            → proxy ke auth_service (Super Admin)
POST /api/integration/v1/auth/verify-otp       → proxy ke auth_service
GET  /api/integration/v1/auth/me               → proxy ke auth_service
POST /api/integration/v1/merchant/auth/login   → Tier 3 merchant login (bcrypt + JWT)

Merchant Accounts (Super Admin)

GET    /api/integration/v1/merchant-accounts
POST   /api/integration/v1/merchant-accounts
PATCH  /api/integration/v1/merchant-accounts/{id}
DELETE /api/integration/v1/merchant-accounts/{id}

Picker Data (Super Admin)

GET /api/integration/v1/merchants   → list merchant (picker)
GET /api/integration/v1/partners    → list partner (picker)

PSP Tester (Super Admin) — Phase 2

GET  /api/integration/v1/psp/keys         → list active PSP HMAC keys
POST /api/integration/v1/psp/execute      → sign + forward ke payment_service/core_api
POST /api/integration/v1/psp-external/execute → sign + forward ke payment.kesles.com

Partner Tester (Super Admin) — Phase 2

POST /api/integration/v1/partner/execute  → exchange credential → forward ke partner_service

Sandbox Access Admin (Super Admin) — Phase 3

GET    /api/integration/v1/sandbox/merchants              → list merchant enabled sandbox
POST   /api/integration/v1/sandbox/merchants/{id}/enable  → enable sandbox
DELETE /api/integration/v1/sandbox/merchants/{id}/disable → disable sandbox
GET    /api/integration/v1/sandbox/status                 → status sandbox (merchant | superAdmin)

Sandbox QRIS Simulation (Merchant | Super Admin) — Phase 4

POST /api/integration/v1/sandbox/qris/generate    → buat transaksi + QRIS content
POST /api/integration/v1/sandbox/qris/pay         → simulasi pembayaran (mark paid)
GET  /api/integration/v1/sandbox/transactions     → list transaksi sandbox
GET  /api/integration/v1/sandbox/transactions/{id} → detail transaksi

Sandbox Webhook Trigger (Merchant | Super Admin) — Phase 5

POST /api/integration/v1/sandbox/webhook/trigger  → kirim simulasi webhook ke URL merchant
GET  /api/integration/v1/sandbox/webhook/logs     → log delivery per transaction_id

Upstream Dependencies

Upstream	Keperluan	Auth
`auth_service` :8081	Proxy login/OTP/me + role lookup	`X-Service-Token`
`core_api` :8080	Merchant picker list + partner auth/token	`X-Internal-API-Key`
`payment_service` :8085	PSP key list + forward payment-event	`PAYMENT_SERVICE_API_KEY`
`partner_service` :8086	(via core_api proxy) partner token exchange	Bearer
`dashboard_api` :8082	Partner list picker	forwarded Bearer JWT

QRIS Sandbox

QRIS content yang dihasilkan berformat sintetis (bukan live/scannable PSP):

SANDBOX.KESLES.{merchantID[0:8]}.{txID[0:8]}.IDR{amount}

String ini dapat di-render menjadi QR code di Flutter (qr_flutter). Simulasi pembayaran dilakukan via API (/sandbox/qris/pay), bukan scan terminal nyata.

Webhook Sandbox

Payload webhook sandbox mirror format PSP real:

{
  "event_type": "transaction.success",
  "external_event_id": "SANDBOX-{txID}",
  "merchant_id": "...",
  "amount": 10000,
  "currency": "IDR",
  "status": "success",
  "payment_method": "qris",
  "is_sandbox": true
}

Header opsional: X-Sandbox-Signature: sha256=<hmac> jika secret diisi — untuk testing signature verification di sisi merchant.

PSP Outbound Credentials

PSP External Tester (POST /api/integration/v1/psp-external/execute) sign request ke payment.kesles.com menggunakan HMAC SHA-256 terpisah dari inbound:

Var	Keterangan
`PSP_OUTBOUND_HMAC_KEY_ID`	Key ID yang didaftarkan di payment.kesles.com
`PSP_OUTBOUND_HMAC_SECRET`	64-char hex secret (256-bit)

Signing format: METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + BODY → hex(hmac_sha256(secret, canonical)).

Credential test terdokumentasi di secrets/psp-credential-integration-api-outbound.md — wajib didaftarkan di payment.kesles.com sebelum external tester berfungsi.

Deployment

Folder VM: merchant_integration_api/
Systemd: integration-api.service
Port: 8092
Nginx: /merchant/integration-api/ → :8092

Fase Implementasi

Phase	Status	Deskripsi
Phase 1	✅ DONE	Scaffold + 3-tier auth + merchant accounts CRUD + mig 107
Phase 2	✅ DONE	PSP tester + PSP External tester + Partner tester
Phase 3	✅ DONE	Sandbox infrastructure (mig 108 schema + enable/disable/status)
Phase 4	✅ DONE	Sandbox QRIS generate + pay + transaction list/detail
Phase 5	✅ DONE	Sandbox webhook trigger + log delivery
Phase 6	✅ DONE 2026-06-16	Flutter: Merchant Accounts panel (CRUD) + sidebar Admin section + default view
Phase 7	✅ DONE 2026-06-16	Cutover: PSP tester handlers dihapus dari dashboard_api; PSP outbound credential terdokumentasi

Overview​

Auth — 3 Tier​

Database Schema​

Endpoint Lengkap​

Auth​

Merchant Accounts (Super Admin)​

Picker Data (Super Admin)​

PSP Tester (Super Admin) — Phase 2​

Partner Tester (Super Admin) — Phase 2​

Sandbox Access Admin (Super Admin) — Phase 3​

Sandbox QRIS Simulation (Merchant | Super Admin) — Phase 4​

Sandbox Webhook Trigger (Merchant | Super Admin) — Phase 5​

Upstream Dependencies​

QRIS Sandbox​

Webhook Sandbox​

PSP Outbound Credentials​

Deployment​

Fase Implementasi​