API Merchant

Endpoint untuk lookup data merchant yang masuk scope partner. Hanya merchant dalam scope partner (referral / consent / assignment) yang di-return.

Base URL:

Environment	Host
Production	https://api-merchant.kesles.com
Staging	https://api-merchant-staging.kesles.com

Base path: /api/partner/v1

Auth: Bearer token hasil POST /api/partner/v1/auth/token. Lihat Onboarding Partner untuk cara dapat credential.

Daftar Merchant Referral

GET /api/partner/v1/partners/{partner_id}/referral-merchants

List merchant yang masuk scope partner ini (referral / consent / assignment).

Scope: merchant.read

Request

GET /api/partner/v1/partners/{partner_id}/referral-merchants
Authorization: Bearer {access_token}
X-Request-ID: {uuid}

Response 200

{
  "partner_id": "uuid",
  "partner_code": "PTR-DEMO-001",
  "items": [
    {
      "merchant_id": "uuid",
      "merchant_code": "MRC-000123",
      "merchant_name": "Toko Contoh",
      "merchant_status": "active",
      "referral_code": "KESLES-PARTNER-XXX",
      "access_type": "referral",
      "granted_at": "2026-01-15T08:30:00Z"
    }
  ]
}

Field	Format	Catatan
merchant_id	UUID	Identifier merchant
merchant_code	string	Kode merchant internal Kesles
merchant_name	string	Nama dagang merchant
merchant_status	enum	active, pending_review, inactive, suspended
referral_code	string | null	Kode referral yang dipakai saat onboarding
access_type	enum	referral, consent, assignment
granted_at	RFC3339	Saat akses partner ke merchant ini ter-grant

Error

Status	Code	Meaning
401	unauthorized	Access token invalid / expired
403	forbidden	Partner tidak punya scope merchant.read atau partner_id mismatch
429	rate_limit_exceeded	Lebih dari 60 req/min

Ringkasan Referral

GET /api/partner/v1/partners/{partner_id}/referral-merchants/summary

Ringkasan agregat referral merchant + performa transaksi.

Scope: merchant.read

Response 200

{
  "partner_id": "uuid",
  "partner_code": "PTR-DEMO-001",
  "merchant_count": 142,
  "active_count": 98,
  "gross_amount": 12500000000,
  "transaction_count": 18450
}

Field	Format	Catatan
merchant_count	integer	Total merchant dalam scope partner
active_count	integer	Merchant berstatus active
gross_amount	integer	Akumulasi gross transaksi (unit terkecil mata uang, IDR = rupiah utuh)
transaction_count	integer	Jumlah transaksi merchant scope partner

Transaksi Merchant

GET /api/partner/v1/merchants/{merchant_id}/transactions

List transaksi merchant (hanya merchant dalam scope partner).

Scope: transaction.read

Request

GET /api/partner/v1/merchants/{merchant_id}/transactions?period=monthly&anchor_date=2026-04-15
Authorization: Bearer {access_token}
X-Request-ID: {uuid}

Query params:

Param	Type	Default	Catatan
period	enum	monthly	daily, weekly, monthly
anchor_date	ISO date	hari ini	Tanggal acuan window periode

Backend saat ini hard-cap 50 item per response (tanpa pagination cursor publik). Untuk dataset volume tinggi, iterate dengan window harian/mingguan via anchor_date.

Response 200

{
  "merchant_id": "uuid",
  "merchant_name": "Toko Contoh",
  "merchant_status": "active",
  "period": "monthly",
  "period_start_at": "2026-04-01T00:00:00+07:00",
  "period_end_at": "2026-04-30T23:59:59+07:00",
  "summary": {
    "gross_amount": 78500000,
    "transaction_count": 412
  },
  "items": [
    {
      "id": "uuid",
      "transaction_code": "TRX-2026-04-000412",
      "external_reference": "BI20260424101528XXXX",
      "transaction_status": "success",
      "payment_method": "qris",
      "payment_channel": "bca",
      "gross_amount": 75000,
      "transaction_at": "2026-04-24T10:15:28+07:00",
      "settled_at": "2026-04-25T08:00:00+07:00"
    }
  ]
}

Field per item:

Field	Format	Catatan
id	UUID	Identifier transaksi
transaction_code	string	Kode internal Kesles
external_reference	string	Reference dari payment gateway / bank
transaction_status	enum	success, pending, failed, refunded
payment_method	string	qris, card, cash, dll.
payment_channel	string	Channel/issuer (mis. bca, mandiri)
gross_amount	integer	Nominal kotor (unit terkecil mata uang)
transaction_at	RFC3339	Waktu transaksi (zona Asia/Jakarta +07:00)
settled_at	RFC3339 | null	Waktu settlement; null kalau belum settle

Field internal yang tidak di-return ke partner: customer_id, qris_payload, identifier gateway-side merchant/terminal, device_id mentah, payer_reference, semua breakdown fee/MDR/service-fee, dan komponen fee-share internal. Mata uang default IDR (unit terkecil = rupiah utuh, no decimal); QRIS Cross-border akan menambah field currency ISO 4217 saat live.

Ringkasan Scoring Merchant

GET /api/partner/v1/merchants/{merchant_id}/scoring-summary

Ringkasan scoring berbasis transaksi — untuk partner finance / scoring underwriting.

Scope: scoring.read atau risk-summary.read

Response 200

{
  "merchant_id": "uuid",
  "merchant_name": "Toko Contoh",
  "merchant_status": "active",
  "average_monthly_gross_amount": 78500000,
  "average_monthly_transaction_count": 412,
  "avg_ticket_size": 190534,
  "growth_30d": 0.082,
  "growth_90d": 0.214,
  "settlement_consistency_score": 0.96,
  "transaction_stability_score": 0.88
}

Scope Partner

Partner hanya bisa akses merchant yang:

1. Di-refer partner (via referral_code matching)
2. Ter-grant consent eksplisit oleh merchant
3. Di-assign manual oleh operator Kesles

Di luar scope ini → 403 forbidden.

catatan

Untuk integrasi server-to-server tertentu (di luar scope Partner API publik di atas), Kesles menyediakan kontrak API tersendiri yang di-share langsung ke PIC integrasi via Perjanjian Partner + channel onboarding terenkripsi. Pattern signature umum (HMAC-SHA256) ada di Autentikasi HMAC.