Partner Service

Port: 8086 | DB: db_kesles_merchant_partner | Status: LIVE

Overview

Mengelola partner (reseller, bank, lender), API credentials, commercial plans, revenue share, dan device subsidy.

Database Schema

Schema partner, 15 tabel + 2 view:

• partners + partner_users + partner_reps
• api_credentials — HMAC key per partner
• partner_commercial_plans + commercial_plan_service_fee_tiers
• revenue_share_rules
• merchant_access + merchant_consents
• access_scope_changes — forensic audit (NEVER DELETE)
• api_audit_logs — PARTITIONED by quarter
• webhook_deliveries
• partner_settlement_lines — bagi-hasil partner per transaksi
• partner_device_subsidy_orders + partner_device_subsidy_allocations
• View: v_partner_monthly_settlement, v_partner_subsidy_quota

Partner API Endpoints (/api/partner/v1/)

Auth: Bearer JWT (HS256, diterbitkan via POST /api/partner/v1/auth/token).

Auth

Method	Path	Status	Keterangan
POST	/auth/token	✅ LIVE	Exchange credential_key+credential_secret → JWT

Partner-scoped

Method	Path	Status	Keterangan
GET	/partners/{id}/portfolio	✅ LIVE	Merchant counts + settlement bulan ini
GET	/partners/{id}/referral-merchants	✅ LIVE	List merchant yang direferensikan
GET	/partners/{id}/referral-merchants/summary	✅ LIVE	Aggregat referral merchants
GET	/partners/{id}/commission-basis	✅ LIVE	Revenue share rules aktif
GET	/partners/{id}/settlements	✅ LIVE	Settlement lines per periode (?period=YYYY-MM)

Merchant-scoped

Method	Path	Status	Keterangan
GET	/merchants/{id}	✅ LIVE	Detail merchant (scope-checked)
GET	/merchants/{id}/transactions	✅ LIVE	Transaksi merchant via payment-service
GET	/merchants/{id}/scoring-summary	✅ LIVE	Scoring KPI merchant
GET	/merchants/{id}/dashboard	✅ LIVE	PnL snapshot merchant

Merchant Registration

Method	Path	Status	Keterangan
POST	/merchant-registrations	✅ LIVE	Daftarkan merchant baru — referral partner diinject otomatis dari JWT
GET	/merchant-registrations/device-offer	✅ LIVE	Daftar device offer aktif via order-service

Reference Data

Method	Path	Status	Keterangan
GET	/references/provinces	✅ LIVE	Proxy ke core_api
GET	/references/cities?province_id=X	✅ LIVE	Proxy ke core_api
GET	/references/districts?city_id=X	✅ LIVE	Proxy ke core_api
GET	/references/subdistricts?district_id=X	✅ LIVE	Proxy ke core_api
GET	/references/postal-codes?subdistrict_id=X	✅ LIVE	Proxy ke core_api
GET	/references/business-scales	✅ LIVE	Proxy ke core_api
GET	/references/business-types	✅ LIVE	Proxy ke core_api

address-by-nik diblokir — data personal tidak diekspos ke partner.

Internal Endpoints (/internal/)

Auth: X-Internal-API-Key.

Partner & Credentials CRUD

Method	Path	Status
GET/POST	/internal/partners	✅ LIVE
GET/PATCH	/internal/partners/{id}	✅ LIVE
PATCH	/internal/partners/{id}/scope	✅ LIVE
POST	/internal/partners/{id}/credentials	✅ LIVE
DELETE	/internal/partners/{id}/credentials/{cid}	✅ LIVE

Merchant Access & Audit

Method	Path	Status
POST	/internal/merchant-access	✅ LIVE
DELETE	/internal/merchant-access/{id}	✅ LIVE
GET	/internal/access-scope-changes	✅ LIVE
GET	/internal/audit-logs	✅ LIVE

Settlement

Method	Path	Status	Keterangan
GET	/internal/settlements	✅ LIVE	List settlement lines; filter ?partner_id=&period=YYYY-MM
POST	/internal/settlements/run	⬜ STUB	Settlement engine — deferred

Subsidy

Method	Path	Status	Keterangan
POST	/internal/subsidy-orders	⬜ STUB	Deferred — belum ada program aktif
POST	/internal/subsidy-allocations	⬜ STUB	Deferred — belum ada program aktif

Commercial Plans & Revenue Share

Method	Path	Status
GET/POST	/internal/commercial-plans	✅ LIVE
GET/PATCH	/internal/commercial-plans/{id}	✅ LIVE
GET/POST	/internal/plan-tiers	✅ LIVE
GET/PATCH	/internal/plan-tiers/{id}	✅ LIVE
GET/POST	/internal/revenue-share-rules	✅ LIVE
GET/PATCH	/internal/revenue-share-rules/{id}	✅ LIVE

Partner Reps & References

Method	Path	Status
GET/POST	/internal/partner-reps	✅ LIVE
GET/PATCH	/internal/partner-reps/{id}	✅ LIVE
GET	/internal/partner-pricing	✅ LIVE
GET	/internal/referral-resolve	✅ LIVE

Merchant Registration Flow (partner-initiated)

Partner login → POST /api/partner/v1/auth/token → JWT

POST /api/partner/v1/merchant-registrations
  Body: { owner_phone, owner_full_name, merchant_name, business_entity_type,
          contact_phone, bank_name, account_number, ... }

  partner_service:
    1. Extract partner_id dari JWT
    2. GetPartner(partner_id) → dapat partner_code, partner_name
    3. Inject referral_partner_id/code/name otomatis
    4. POST /internal/merchant/registration/manual → core_api
    5. Return 201 { status, user_id, request: { merchant_code, ... } }

Referral code partner tercatat di merchant.merchant_registrations — sama dengan user yang isi referral code manual di step 7 flow registrasi mobile.

Deployment

• Folder VM: merchant_partner/
• Binary: partner-service
• Systemd: partner-service.service
• Port: 127.0.0.1:8086
• Nginx: api-merchant.kesles.com /api/partner/v1/ → :8086