Getting Started

Initial steps for partners that want to integrate with Kesles Merchant.

1. Register as a Partner

Contact the Kesles Merchant team at partner@kesles.com to receive:

• partner_id (UUID)
• credential_key (public identifier — safe to log)
• credential_secret (delivered via an encrypted channel — not email)

Full onboarding flow → Partner Onboarding.

2. Base URL

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

All public partner endpoints live under the /api/partner/v1 prefix. Internal / administrative endpoints are not hosted on this domain and are not exposed to partners.

3. Exchange Credentials for an Access Token

curl -X POST "https://api-merchant-staging.kesles.com/api/partner/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_key": "'$KESLES_CREDENTIAL_KEY'",
    "credential_secret": "'$KESLES_CREDENTIAL_SECRET'"
  }'

Response:

{
  "token_type": "Bearer",
  "access_token": "eyJhbGc...",
  "expires_in": 3600,
  "scopes": ["merchant.read", "transaction.read"],
  "partner_id": "uuid",
  "partner_code": "PTR-DEMO-001",
  "partner_name": "Demo Partner"
}

The scopes (array) determine which endpoints can be called — referral partners typically have merchant.read + transaction.read; finance/scoring partners may additionally have scoring.read or risk-summary.read. The token is valid for expires_in seconds (default 3600).

4. First Request

Sample request to list referral merchants:

curl -X GET "https://api-merchant-staging.kesles.com/api/partner/v1/partners/{partner_id}/referral-merchants" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Request-ID: $(uuidgen)"

Successful response:

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

5. Next Steps

• Partner Onboarding — full kickoff → go-live flow
• Partner API Reference — full endpoint spec
• HMAC Authentication — signature pattern for signed endpoints (partner-specific flows that require HMAC)