Transactions & Payouts

This is the ledger side of the marketplace loop: every split payment lands in the transactions list with its seller legs; what each seller is owed accumulates in the payout ledger; you record payouts and mark them paid; and every mutation is appended to a hash-chained audit log you can verify cryptographically. All endpoints use your access token (Authorization: Bearer at_live_…) at base URL https://api-gateway.lunixi.com/api/v1.

⚠️

All amounts are minor-unit (kuruş) strings on ledger surfaces: "netMinor": "13725" = ₺137.25.

How it works

Split payments accrue

Each successful split payment writes per-seller legs — amount, commission, hold, net — to the transaction record.

The payout ledger tracks what's owed

Ledger entries carry each seller's gross → commission → tax → hold → net, a valor date and a status (PLANNED → PAID).

You pay and mark paid

Send the money over your own rail (bank transfer etc.), then record it: create a payout entry and mark it PAID — individually or in bulk — with the payment reference for the paper trail.

Everything is auditable

Every dealer change, commission rule, payout and mark-paid is appended to the tamper-evident audit log; GET /marketplace/audit-log/verify proves chain integrity for compliance reporting.

Listing split transactions

GET /marketplace/transactions lists split payments with their seller breakdown. Filters: status, subDealerId, limit.

curl "https://api-gateway.lunixi.com/api/v1/marketplace/transactions?subDealerId=d_8f2a...&limit=20" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

The response is an array of transactions, each carrying its seller legs:

{
  "id": "b7e2c9d4-...",
  "orderId": "ORD-2026-1042",
  "createdAt": "2026-07-04T09:41:22.000Z",
  "currency": "TRY",
  "grossMinor": "25000",
  "status": "CAPTURED",
  "is3D": false,
  "disputeState": "NONE",
  "sellers": [
    {
      "subDealerId": "d_8f2a...",
      "netMinor": "13725",
      "commissionMinor": "1275",
      "holdMinor": "0",
      "legStatus": "SETTLED"
    },
    {
      "subDealerId": "d_c41b...",
      "netMinor": "9000",
      "commissionMinor": "1000",
      "holdMinor": "0",
      "legStatus": "SETTLED"
    }
  ]
}

grossMinor is the transaction's total charged amount; status is the core payment status (CAPTURED, REFUNDED, …) and disputeState the chargeback state. Per leg:

Leg field	Meaning
`netMinor`	The seller's payout share of this transaction — what the seller is owed
`commissionMinor`	Your commission on this leg (resolved from commission rules)
`holdMinor`	Amount held back from this leg
`legStatus`	`PENDING` · `HELD` (a hold is in place) · `SETTLED` (payment captured) · `REVERSED` (payment refunded or voided)

The payout ledger

GET /marketplace/payout-ledger is the per-seller settlement view. Filters: status, subDealerId, days, limit.

curl "https://api-gateway.lunixi.com/api/v1/marketplace/payout-ledger?status=PLANNED&days=30" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Each entry breaks a payout down as gross − commission − tax − hold = net, with a valorDate (value date), the payout rail, and a status of PLANNED (recorded, money not yet sent) or PAID (confirmed with payment metadata).

Recording payouts

Lunixi does not move the payout money itself — you transfer on your own rail and record the fact. POST /marketplace/payouts creates a payout entry:

curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/payouts \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "subDealerId": "d_8f2a...",
    "grossMinor": "150000",
    "commissionMinor": "12750",
    "netMinor": "137250",
    "currency": "TRY",
    "valorDate": "2026-07-10",
    "note": "June settlement",
    "markPaid": true,
    "paymentMethod": "BANK_WIRE",
    "paymentReference": "TRF-2026-0709-114"
  }'

Field	Notes
`subDealerId`	Required — the seller being paid
`netMinor`	Required — the amount the seller receives (minor-unit string, > 0)
`grossMinor` / `commissionMinor` / `taxMinor` / `holdMinor`	Optional breakdown; defaults derive from `netMinor`
`currency`	Defaults to `TRY`
`valorDate`	`YYYY-MM-DD`; defaults to today
`markPaid`	`true` if the money was already sent — the entry is created directly as `PAID`
`paymentMethod`	`BANK_WIRE` · `EFT` · `HAVALE` · `CRYPTO` · `CLOSED_WALLET` · `OPEN_WALLET` · `CASH` · `OTHER`
`paymentReference` / `paidAt`	Transfer reference and actual transfer time (ISO); `paidAt` defaults to now

Marking paid

When a PLANNED payout's transfer completes:

# Single
curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/payouts/po_3f9c.../mark-paid \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethod": "EFT", "paymentReference": "TRF-2026-0710-201" }'
 
# Bulk — e.g. after a batch bank run
curl -X POST https://api-gateway.lunixi.com/api/v1/marketplace/payouts/bulk-mark-paid \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["po_3f9c...", "po_71ab...", "po_c02d..."], "paymentMethod": "BANK_WIRE" }'

The bulk call returns a per-batch summary:

{ "marked": 3, "failed": 0, "ids": ["po_3f9c...", "po_71ab...", "po_c02d..."] }

Who marked a payout paid, when, and with which reference is stored on the entry and mirrored into the audit log.

Audit log

Every marketplace mutation — dealer lifecycle changes, commission rules, manual payouts, mark-paid events — is appended to an append-only, hash-chained audit log: each record carries a hash linking it to the previous one, so any tampering or deletion breaks the chain detectably.

# Query the log
curl "https://api-gateway.lunixi.com/api/v1/marketplace/audit-log?days=30&actionType=PAYOUT_DONE&limit=50" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Filters: days, actor, actionType, dealerName, limit.

Verifying chain integrity

curl https://api-gateway.lunixi.com/api/v1/marketplace/audit-log/verify \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

The response tells you whether the chain is intact (valid) and, if not, the sequence number where it breaks (brokenAtSeq).

Compliance note: the verify endpoint makes the audit log usable as regulator-grade evidence — you can demonstrate, on demand, that the recorded payout and onboarding history has not been altered since it was written. Run it as part of your periodic compliance reporting.

Errors

Status	Meaning	What to do
`400`	`marketplace.payout.sub_dealer_required` / `marketplace.payout.amount_required` — missing seller or non-positive `netMinor`	Fix the payout body
`400`	`marketplace.payout.not_found` — payout not found (or not yours)	Verify the payout id
`400`	`marketplace.payout.held_cannot_pay` — the payout is `HELD`	Release the hold before marking paid
`401`	Missing or invalid API key	Check the `Authorization` header

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

Webhooks

Transaction-level events are the core payment.* webhooks. Payout recording and mark-paid are merchant-initiated actions — track them through the payout ledger and the audit log rather than events.

Next steps

Split 2D Payment — how seller legs get written in the first place
Refunds & Cancellations — reversals against the seller breakdown
Getting Started — commission rules that drive the ledger numbers

Refunds & Cancellations Overview