Qris-Soundbox/05-api-contract-draft.md

API Contract Draft - QRIS Soundbox Platform v1

1. Prinsip API

• gunakan HTTPS
• semua endpoint device memakai auth khusus device
• semua endpoint admin/merchant memakai RBAC
• endpoint create yang sensitif wajib support idempotency key
• response harus punya request_id / trace_id

2. Admin / Merchant APIs

Merchant

• POST /admin/merchants
• GET /admin/merchants
• GET /admin/merchants/{merchantId}
• PATCH /admin/merchants/{merchantId}
• POST /admin/merchants/{merchantId}/approve
• POST /admin/merchants/{merchantId}/reject

Create Merchant

• POST /admin/merchants

Request body:

{
  "legal_name": "Toko Indo",
  "brand_name": "Toko Indo",
  "settlement_account_reference": "bank:9876543210",
  "settlement_account_type": "merchant_bank_account",
  "payout_mode": "merchant_direct",
  "fee_profile_id": "fee_basic"
}

payout_mode:

• merchant_direct (default): payout mengikuti rekening/referensi milik merchant.
• manual: payout dilakukan manual/offline oleh tim operasi.

Response:

{
  "data": {
    "id": "m_123",
    "merchant_code": "m_123abc",
    "legal_name": "Toko Indo",
    "brand_name": "Toko Indo",
    "settlement_account_reference": "bank:9876543210",
    "settlement_account_type": "merchant_bank_account",
    "payout_mode": "merchant_direct"
  },
  "request_id": "req_001",
  "timestamp": "2026-05-24T00:00:00Z"
}

Catatan penting:

• Pada fase awal, settlement tidak ditarik ke rekening perusahaan.
• Pencairan merchant dilakukan via payout_account_reference milik merchant.
• Untuk merchant yang belum punya integrasi payout otomatis, gunakan payout_mode: manual.

Outlet

• POST /admin/merchants/{merchantId}/outlets
• GET /admin/outlets
• GET /admin/outlets/{outletId}
• PATCH /admin/outlets/{outletId}

Terminal

• POST /admin/outlets/{outletId}/terminals
• GET /admin/terminals
• GET /admin/terminals/{terminalId}
• PATCH /admin/terminals/{terminalId}

Device / TMS

• POST /admin/devices
• GET /admin/devices
• GET /admin/devices/{deviceId}
• PATCH /admin/devices/{deviceId}
• POST /admin/devices/{deviceId}/bind
• POST /admin/devices/{deviceId}/unbind
• POST /admin/devices/{deviceId}/commands
• GET /admin/devices/{deviceId}/commands
• GET /admin/devices/{deviceId}/commands/{commandId}
• GET /admin/devices/{deviceId}/heartbeats
• GET /admin/devices/{deviceId}/notifications
• POST /admin/seed

Transactions

• GET /admin/transactions
• GET /admin/transactions/{transactionId}
• POST /admin/transactions/{transactionId}/retry-notification

Settlements

• GET /admin/settlements
• GET /admin/settlements/{settlementId}
• POST /admin/settlements/run
• POST /admin/settlements/{settlementId}/retry-payout
• Catatan: endpoint ini dipakai untuk batch/reconciliation status; eksekusi payout dilakukan sesuai konfigurasi payout_mode merchant.

3. Device APIs

Provisioning

• POST /device/provision/activate
• POST /device/provision/refresh-credential

Heartbeat

• POST /device/heartbeat

Sample request:

{
  "device_id": "sbx_001",
  "timestamp": "2026-05-23T10:00:00Z",
  "firmware_version": "1.0.3",
  "network_strength": 78,
  "battery_level": 92,
  "state": "idle"
}

Config

• GET /device/config
• POST /device/config/ack
• POST /device/commands/ack

Device command payload ack

Device mengirim:

{
  "device_id": "sbx_001",
  "command_id": "cmd_123",
  "status": "delivered",
  "reason": "ok",
  "result_payload": {
    "payment_result": "ok"
  }
}

status untuk ACK: delivered | failed | timeout.

Dynamic QR create

• POST /device/transactions/dynamic-qr

Headers:

• Authorization: Bearer <device-token>
• Idempotency-Key: <uuid>

Request:

{
  "device_id": "sbx_001",
  "terminal_id": "term_001",
  "amount": 50000,
  "currency": "IDR",
  "request_id": "req_123"
}

Response:

{
  "request_id": "req_123",
  "transaction_id": "tx_123",
  "qr_type": "dynamic",
  "qr_payload": "000201010212...",
  "expires_at": "2026-05-23T10:05:00Z",
  "status": "awaiting_payment"
}

4. Merchant Portal APIs

• GET /merchant/me
• GET /merchant/dashboard/summary
• GET /merchant/transactions
• GET /merchant/transactions/{transactionId}
• GET /merchant/settlements
• GET /merchant/settlements/{settlementId}
• GET /merchant/devices
• GET /merchant/outlets

5. Webhook Receiver

• POST /integrations/qris/callback
• POST /integrations/bank/payout-callback

6. Catatan Error Model

Gunakan error code yang konsisten, misalnya:

• DEVICE_UNAUTHORIZED
• DEVICE_NOT_BOUND
• DEVICE_CAPABILITY_NOT_SUPPORTED
• INVALID_AMOUNT
• DUPLICATE_REQUEST
• PARTNER_TIMEOUT
• TRANSACTION_NOT_FOUND
• SETTLEMENT_NOT_ELIGIBLE
• MERCHANT_PAYOUT_NOT_CONFIGURED