Getting Started

Before you can split a payment, you need two things: sellers (sub-dealers) registered in your marketplace, and commission rules that tell Lunixi how much of each seller's leg belongs to you. This page walks through both, plus the dealer lifecycle you'll manage day to day.

All endpoints here use your server-side access token (Authorization: Bearer at_live_…) — see Authentication. Base URL: https://api-gateway.lunixi.com/api/v1.

How it works

Register a seller

Create a sub-dealer with its legal profile. The seller starts at the APPLICATION onboarding stage (coarse status DRAFT).

curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/dealers \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "dealerType": "LEGAL_ENTITY",
    "verificationMode": "LUNIXI_KYC",
    "country": "TR",
    "externalRef": "seller-1042",
    "profile": {
      "legalName": "Aksoy Elektronik Ticaret A.Ş.",
      "displayName": "Aksoy Elektronik",
      "taxIdType": "VKN",
      "taxId": "1234567890",
      "categoryCode": "electronics",
      "email": "[email protected]",
      "phone": "+905550001122"
    },
    "authorizedPersons": [
      { "fullName": "Ayşe Aksoy", "email": "[email protected]", "hasSignatureAuthority": true, "isPrimary": true }
    ]
  }'

Key fields:

Bulk import (CSV rows)

Migrating an existing seller base? Send parsed CSV rows in one request:

curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/dealers/bulk \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "firmaAdi": "Aksoy Elektronik A.Ş.", "vkn": "1234567890", "kategori": "electronics", "email": "[email protected]", "komisyon": "8.5" },
      { "firmaAdi": "Yıldız Moda Ltd.",      "vkn": "9876543210", "kategori": "fashion",     "email": "[email protected]" }
    ]
  }'

Each row takes firmaAdi (company name) and vkn (tax number) as required, plus optional kategori, email and komisyon (a per-seller commission rate applied at import).

The dealer lifecycle

Every seller carries an onboarding stage — a fine-grained, resumable position in the onboarding flow:

A failed KYC moves the seller to the terminal REJECTED stage. The onboarding stage is distinct from the coarse lifecycle status (DRAFT → PENDING_KYC → ACTIVE, plus SUSPENDED / HOLD / CLOSED) used for day-to-day eligibility.

Track any seller's position with GET /marketplace/dealers/{id}/application, and list your registry with GET /marketplace/dealers (filters: status, search, limit, offset).

Suspending and reactivating

PUT /marketplace/dealers/{id}/status changes the seller's coarse lifecycle status — for example suspending a seller so new split payments to them are rejected:

curl -X PUT https://api-gateway.lunixi.com/api/v1/marketplace/dealers/d_8f2a.../status \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "SUSPENDED" }'

A suspended seller fails split-payment eligibility with SELLER_SUSPENDED — see Split 2D Payment.

Commission rules

Commission decides how much of each seller leg you keep. Rules are resolved most-specific-first: per-seller → category → default. Creating a new rule for the same scope supersedes the currently active one (effective-dated).

Create a rule

# Default rule: 10% on everything
curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/commission-rules \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "scope": "DEFAULT", "basis": "PERCENT", "ratePercent": "10" }'
 
# Category override: 8.5% for electronics
curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/commission-rules \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "CATEGORY",
    "categoryCode": "electronics",
    "basis": "PERCENT",
    "ratePercent": "8.5",
    "reasonNote": "Electronics campaign Q3"
  }'
 
# Per-seller override: fixed ₺5.00 per transaction
curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/commission-rules \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "SUB_DEALER",
    "subDealerId": "d_8f2a...",
    "basis": "FIXED",
    "fixedAmountMinor": "500"
  }'

List active rules with GET /marketplace/commission-rules.

Preview before committing

POST /marketplace/commission-rules/preview accepts the same body as rule creation and returns what the rule would do — without persisting anything. Use it to sanity-check a change against real amounts before rolling it out.

Resolve the effective rate

To see exactly which rule applies to a seller right now:

curl "https://api-gateway.lunixi.com/api/v1/marketplace/commission/resolve?subDealerId=d_8f2a...&categoryCode=electronics&mtdVolumeMinor=125000000" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Errors

Next steps

• Seller Onboarding — mint onboarding links, hosted portal & embedded SDK
• Split 2D Payment — your first split charge
• Transactions & Payouts — the ledger side of the loop