Seller Onboarding

Once a seller exists in your registry, they need to complete an application, pass identity verification (KYC) and sign your contract before they can receive split payments. You don't build any of that: mint a single onboarding token and either send the seller a hosted portal link, or embed the whole flow into your own page with the marketplace JS SDK — as a ready-made wizard or a fully headless client.

The onboarding token is a JWT scoped to one seller's onboarding (valid ~7 days by default). It is not an API key: it can only drive that seller's application forward. When it expires, mint a new one — progress is resumable.

How it works

Mint an onboarding token

Call POST /marketplace/dealers/{id}/onboarding-token from your server. You get back a token and a ready-to-share hosted portal URL.

Deliver it to the seller

Email the hosted URL, or open your own onboarding page that boots the SDK with the token.

The seller completes the flow

Application details → KYC (handed off to the Lunixi KYC SDK) → contract signature. The dealer stage advances APPLICATION → KYC_PENDING → AWAITING_TERMS → CONTRACT_PENDING.

You set terms and activate

When the stage reaches AWAITING_TERMS, set commission & payout terms (POST /marketplace/dealers/{id}/terms). After the seller signs, activate with POST /marketplace/dealers/{id}/activate — the stage becomes COMPLETED, the seller's status flips to ACTIVE and it is split-payment eligible.

Mint an onboarding token

curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/dealers/d_8f2a.../onboarding-token \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "url": "https://altbayi.lunixi.com/m/eyJhbGciOiJIUzI1NiIsInR5cCI6..."
}

⚠️

Treat the token like a magic link: anyone holding it can act as that seller's applicant until it expires. Deliver it over a trusted channel (the seller's verified email or an authenticated session on your platform).

Two integration modes

Mode A — hosted portal

Send the seller the url as-is. The portal at altbayi.lunixi.com renders the full onboarding wizard — application form, KYC capture, contract review and signature — with zero code on your side. This is the fastest path and the right default for most platforms.

Mode B — embedded SDK

Load the marketplace SDK on your own page and drive the flow under your brand. The SDK ships two levels:

Lunixi.marketplace.mount(target, config) — the same ready-made wizard, rendered inside your DOM node.
Lunixi.marketplace.create({ token }) — a headless client: you build every screen, the SDK gives you data and state transitions.

<div id="onboarding-root"></div>
 
<script src="https://cdn.lunixi.com/lunixi-marketplace.min.js"></script>
<script>
  const handle = Lunixi.marketplace.mount('#onboarding-root', {
    token: 'eyJhbGciOi...',          // from POST .../onboarding-token
    locale: 'en',                    // default 'tr'
    theme: 'auto',                   // 'light' | 'dark' | 'auto'
    onStageChange(stage) {
      console.log('seller is now at', stage);
      // APPLICATION → KYC_PENDING → AWAITING_TERMS → CONTRACT_PENDING → COMPLETED
    },
    onCompleted() {
      window.location.href = '/seller/dashboard?onboarding=done';
    },
    onError(err) {
      console.error(err.code, err.message);
    },
  });
 
  // handle.unmount() when navigating away
</script>

The wizard renders the phase matching the seller's current stage — a seller who closed the tab mid-KYC resumes exactly where they left off. The KYC step composes the Lunixi KYC SDK internally; you don't integrate it separately.

Both modes talk to the same portal API underneath — if the seller starts on the hosted portal and later opens your embedded page (or vice versa), state stays consistent.

The portal API underneath

The SDK authenticates every call with the onboarding token in the X-Marketplace-Token header — never with your secret key, which must not reach the browser. For reference, these are the endpoints the SDK drives:

Method	Path	Called by SDK as
GET	`/marketplace/portal/application`	`getApplicationStatus()`
POST	`/marketplace/portal/submit`	`submitApplication(payload)`
POST	`/marketplace/portal/sign`	`signContract(payload)`
GET	`/marketplace/portal/kyc-handoff`	`getKycHandoff()`

You normally never call these directly — the SDK (or the hosted portal) does. They are listed so you can recognise them in network logs and CSP allow-lists.

The KYC handoff

Identity verification is not re-implemented inside the marketplace flow. When the application reaches the KYC step:

The SDK (or portal) calls getKycHandoff() and receives a reference to an active KYC session for this seller.
That reference boots the Lunixi KYC SDK, which runs document capture, liveness and the rest of the verification flow.
When verification concludes, the dealer's stage advances automatically — in the embedded wizard this is seamless; headless integrators re-poll getApplicationStatus() after the KYC SDK completes.

If you verify sellers outside Lunixi (verificationMode: "EXTERNAL" at dealer creation), record the outcome from your server with POST /marketplace/dealers/{id}/kyc-result instead.

Tracking progress from your server

The onboarding token is the seller's view. On your side, track and drive the same application with your secret key:

Endpoint	Purpose
`GET /marketplace/dealers/{id}/application`	Current stage + next action owner
`POST /marketplace/dealers/{id}/terms`	Set commission & payout terms (stage `AWAITING_TERMS`)
`POST /marketplace/dealers/{id}/submit`	Submit the application on the seller's behalf (assisted onboarding)
`POST /marketplace/dealers/{id}/sign`	Record a contract signature captured out-of-band
`POST /marketplace/dealers/{id}/activate`	Final gate — stage `COMPLETED`, status `ACTIVE`

Every transition is appended to the hash-chained audit log, so the full onboarding history of any seller is reconstructable.

Errors

Status	Meaning	What to do
`401`	Onboarding token missing, invalid or expired (`MARKETPLACE_PORTAL_TOKEN_MISSING` / `MARKETPLACE_PORTAL_TOKEN_INVALID`)	Mint a new token (`POST .../onboarding-token`) and re-deliver; progress is preserved
`400`	`marketplace.sub_dealer.not_found` — dealer not found or not yours	Verify the dealer id used to mint the token
`400`	`marketplace.onboarding.invalid_stage_transition` — action not valid for the current stage (e.g. signing before terms are set)	Read `getApplicationStatus()` and render the stage it reports

Business errors surface as HTTP 400 with the error code in the response body's code field — branch on the code, not the status.

Next steps

Getting Started — dealer registry, stages and commission rules
Split 2D Payment — charge with your newly active sellers
Transactions & Payouts — audit log & payout ledger

Getting Started 2D Payment