API Partner

Kesles Merchant Partner API menyediakan akses read-only ke data merchant yang masuk scope partner (referral / consent / assignment), dengan autentikasi khusus partner credential.

Base URL:

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

Base path: /api/partner/v1

Auth: Partner credential (credential_key + credential_secret) yang di-issue oleh tim Kesles saat partner onboarding. Lihat Onboarding Partner.

Autentikasi

Tukar Credential

POST /api/partner/v1/auth/token

Tukar credential jadi access token berumur pendek (default 900 detik / 15 menit).

Request

POST /api/partner/v1/auth/token
Content-Type: application/json

{
  "credential_key": "<partner-key>",
  "credential_secret": "<partner-secret>"
}

Response 200

{
  "token_type": "Bearer",
  "access_token": "eyJhbGc...",
  "expires_in_secs": 900,
  "scope": ["merchant.read", "transaction.read"],
  "partner_id": "uuid",
  "partner_code": "PTR-DEMO-001",
  "partner_name": "Partner Demo",
  "credential_name": "Referral Demo Credential"
}

Pakai access_token sebagai Authorization: Bearer <token> untuk semua request berikutnya. Token expires sesuai expires_in_secs; ambil token baru sebelum expired.

Scope yang umum di-issue:

Scope	Akses
merchant.read	List + summary merchant referral
transaction.read	Transaksi merchant dalam scope partner
scoring.read / risk-summary.read	Scoring summary merchant (partner finance)

Endpoint Merchant

Daftar Merchant Referral

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

List merchant yang masuk scope partner ini (referral, mapping, atau consent).

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

Ringkasan Referral

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

Ringkasan agregat referral merchant + performa transaksi-nya.

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 yang merchant_status = 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 yang masuk 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 untuk window periode

Backend saat ini hard-cap 50 item per response (tanpa pagination cursor publik). Kalau partner butuh dataset bulan utuh, pakai window harian/mingguan + iterasi 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 untuk transaksi belum settle

Field internal yang tidak di-return: customer_id, qris_payload, device_id mentah, identifier gateway-side merchant/terminal, payer_reference, semua breakdown fee/MDR/service-fee, dan komponen fee-share internal. Mata uang saat ini default IDR; untuk QRIS Cross-border field currency akan ditambah di item ketika fitur live.

Ringkasan Scoring Merchant

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

Ringkasan scoring usaha berbasis transaksi — ditujukan untuk partner finance / scoring underwriting, bukan akses bebas data merchant.

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
}

Field	Format	Catatan
average_monthly_gross_amount	integer	Rata-rata omzet bulanan (12 bulan terakhir)
average_monthly_transaction_count	integer	Rata-rata jumlah transaksi bulanan
avg_ticket_size	integer	Ticket size rata-rata
growth_30d / growth_90d	decimal	Pertumbuhan vs window sebelumnya (0.082 = +8.2%)
settlement_consistency_score	decimal 0–1	Konsistensi settlement (1 = settle tepat waktu)
transaction_stability_score	decimal 0–1	Stabilitas volume transaksi

Field internal yang tidak di-return: NIK user, account_number, payer_reference mentah, detail identitas personal.

Error Codes

Status	Code	Meaning
400	bad_request	Payload / query param invalid
401	unauthorized	Credential atau access token invalid / expired
403	forbidden	Partner tidak punya scope atau merchant di luar scope partner
404	(none)	Endpoint tidak dikenal
429	rate_limit_exceeded	Rate limit per credential terlampaui
500	internal_error	Server error — coba lagi dengan exponential backoff

Format error body:

{
  "error": "human readable message",
  "code": "machine_readable_code",
  "retry_after_secs": 60
}

retry_after_secs hanya muncul untuk 429 atau error retryable.

Rate Limit

• Default 60 requests / minute / credential
• Header response: X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds)
• 429 response include retry_after_secs di body + header Retry-After

Scope Akses Data

Partner hanya bisa melihat merchant yang:

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

Partner tidak bisa:

• Akses data merchant di luar scope di atas → 403 forbidden
• Create / update / delete data merchant
• Akses endpoint admin / internal Kesles
• Akses endpoint terminal, pairing, atau kontrol perangkat

Data Masking Policy

Untuk melindungi data transaksi merchant, field sensitif di-filter sebelum di-return:

Field internal	Status di Partner API	Alasan
customer_id	Tidak di-return	Privacy buyer
qris_payload	Tidak di-return	Payment payload sensitif
Identifier gateway-side merchant/terminal	Tidak di-return	Internal routing
payer_reference mentah	Tidak di-return	Privacy buyer
NIK user / account_number	Tidak di-return di scoring summary	PII / data perbankan
Breakdown fee / MDR / service fee per transaksi	Tidak di-return	Rahasia komersial Kesles–merchant
Fee-share / commission Kesles–merchant–partner	Tidak di-return	Rahasia komersial; rekonsiliasi via channel partner agreement

HMAC-Signed Endpoints

Endpoint API Partner standar (di atas) memakai Bearer JWT atau HMAC sign per request, tergantung konfigurasi credential yang di-issue saat onboarding. Untuk integrasi server-to-server tertentu (di luar scope endpoint publik di atas), Kesles menyediakan kontrak API tersendiri yang tidak di-publish di dokumen publik dan dibagikan per partner via Perjanjian Partner + channel onboarding terenkripsi. Pattern signature & header lihat Autentikasi HMAC.

Changelog

Breaking changes di Partner API akan di-bumpkan versi (/api/partner/v1 → /api/partner/v2) dengan grace period minimum 90 hari. Subscribe mailing list partner untuk notifikasi perubahan.