Skip to main content

Partner Onboarding Flow

⚠️ Path versioning update (post-2026-05-07): this document refers to /partner/v1/... throughout as a historical placeholder. The live partner API in code is now mounted at /api/partner/v1/... (renamed per api-versioning-v1-migration-plan Phase 2b). When following the steps below, prefix every /partner/v1/... path with /api/. The rest of the document (auth model, scope, integration models) is still accurate.

Status (2026-06-23): shipped. The dedicated partner API described as future work in this plan now exists as partner_service (port 8086, served at /api/partner/v1/...); the design narrative below is preserved for historical reference.

This document describes the partner onboarding flow for integrating with Kesles Merchant using the APIs that are currently available.

Goal​

Partner onboarding must ensure three things:

  1. the partner understands the authentication model in use
  2. the partner only accesses endpoints that are actually allowed
  3. the partner has realistic expectations about the current API limitations

Currently Available Integration Models​

There are two realistic integration models today:

1. Partner acting on behalf of a merchant/user​

This pattern uses:

  • OTP login
  • bearer token
  • access to merchant endpoints

Suitable for:

  • partner apps
  • embedded merchant portals
  • partner analytics that requires data on a specific merchant

2. Partner as a server-to-server operational integration​

This pattern does not currently have a dedicated partner contract. If absolutely needed, it usually goes via:

  • X-Internal-API-Key
  • a whitelist of specific endpoints
  • additional safeguards

Only suitable for:

  • strategic partners
  • internal group integrations
  • services that have been operationally approved

Stage 1. Kickoff and Scope​

The partner and the Kesles team must agree on:

  • the integration's goal
  • what data will be accessed
  • access frequency
  • whether access is per-user or server-to-server
  • who the operational owner and the technical owner are on each side

Checklist:

  • partner name
  • business use case
  • product PIC
  • technical PIC
  • environment to use
  • initial endpoint scope

Stage 2. Partner Type Classification​

Classify the partner into one of these types:

Type A. Merchant delegated access​

The partner reads merchant data with the merchant's consent.

Primary endpoints:

  • /auth/resolve-phone
  • /auth/request-otp
  • /auth/verify-otp
  • /auth/profile
  • /merchant/home-dashboard
  • /merchant/transactions

Type A1. Referral / Sales Partner​

This is a special derivative of delegated access.

Recommended rules:

  • the partner may only see merchants that came from this referral partner
  • merchant access is determined by the referral_code or an official partner-merchant mapping
  • there must be no global access to all merchants

Data typically required:

  • referral merchant list
  • referral merchant onboarding status
  • referral merchant transaction summary
  • aggregate referral partner performance

Type B. Reference data access​

The partner only needs onboarding master data.

Primary endpoints:

  • /references/provinces
  • /references/cities
  • /references/districts
  • /references/subdistricts
  • /references/postal-codes
  • /references/business-scales
  • /references/business-types

Type C. Internal strategic integration​

The partner needs deeper operational processes.

Current status:

  • requires special approval
  • no official partner API yet
  • internal endpoints are not used directly without additional controls

Type D. Banking / Finance / Scoring Partner​

This partner type usually needs transaction data access for:

  • underwriting
  • credit scoring
  • business scoring
  • merchant performance monitoring

Recommended rules:

  • data access must be limited to approved merchants
  • payloads must be more minimal than the internal dashboard
  • sensitive fields must be masked or removed
  • it is safer to use a scoring dataset than raw internal endpoints

Stage 3. Technical Preparation​

What the Kesles team must prepare:

  • environment base URL
  • list of allowed endpoints
  • request/response samples
  • retry and timeout policy
  • list of important error codes

What the partner must prepare:

  • environment config
  • request/response logging
  • secure token storage
  • refresh/relogin mechanism
  • operational contact email

Stage 4. Basic Integration Test​

Flow A. OTP Auth​

  1. Partner calls POST /auth/resolve-phone
  2. If OTP is needed, partner calls POST /auth/request-otp
  3. User inputs OTP
  4. Partner calls POST /auth/verify-otp
  5. Partner stores the access_token

Pass criteria:

  • token successfully obtained
  • token usable on bearer endpoints
  • invalid-OTP error handled

Flow B. Read Profile​

  1. Partner calls GET /auth/profile
  2. Validate user and merchant context

Pass criteria:

  • merchant user data is read
  • merchant status is consistent

Flow C. Read Dashboard​

  1. Partner calls GET /merchant/home-dashboard
  2. Partner displays the summary

Pass criteria:

  • today_summary is read
  • recent_transactions is read
  • weekly_gross_points is read

Flow D. Read Transactions​

  1. Partner calls GET /merchant/transactions
  2. Test with several period values

Pass criteria:

  • transaction summary matches
  • transaction items appear
  • empty state is handled
  • merchant scope does not leak to other merchants

Stage 5. UAT​

UAT must minimally verify:

  • OTP login succeeds
  • invalid token returns 401
  • transactions are read for the correct merchant
  • partner cannot access other merchants
  • partner cannot access terminals, pairings, or device control
  • partner retries do not cause excessive request spam
  • referral partners cannot read merchants outside their referral
  • finance partners only receive datasets that match the scoring scope

Stage 6. Go Live Checklist​

  • final list of endpoints used
  • partner logging is active
  • support SLA agreed
  • timeouts agreed
  • retry policy agreed
  • rate limit agreed
  • escalation contacts available

Current API Limitations​

Partners need to know the current limitations:

  • there is no /partner/v1/... yet
  • no partner OAuth yet
  • no scoped partner API keys yet
  • no partner transaction webhook yet
  • pagination is uneven
  • filter/sorting is not formalized on all endpoints
  • there is no referral_code-based scope enforcement yet
  • there is no dedicated finance scoring dataset endpoint yet

Operational Recommendations​

For partners starting now, I recommend:

  1. start with a read-only integration
  2. use stable bearer endpoints
  3. limit scope to profile, dashboard, transactions, and references
  4. defer partner write operations until the official /partner/v1 contract is built
  5. do not open "all merchants" access to sales partners
  6. prepare a separate scoring payload for finance partners

Supporting Artifacts​

Documents that should be provided to the partner:

  • Partner API Reference
  • Partner API OpenAPI
  • sample Postman collection
  • error code mapping
  • environment access note

Once basic onboarding is stable, continue with:

  1. designing /partner/v1/...
  2. partner credential model
  3. webhook event model
  4. per-partner audit log
  5. per-partner rate limit