Marketplace Payout Lifecycle

Introduction

In the DJUST PAY marketplace model, marketplace payouts allow the marketplace operator to collect the commissions earned on supplier transactions. When orders are captured, the marketplace commission is computed and consolidated. The marketplace payout mechanism then transfers these accumulated commissions from the marketplace balance account to the marketplace's own bank account.

This guide explains how marketplace payouts work, from computation to settlement.

Key Concepts

Balance Accounts

Each merchant in DJUST PAY has isolated balance accounts managed by the underlying payment provider:

MARKETPLACE (BA_MKP) — holds collected funds including marketplace commissions, before distribution
SUPPLIER — holds funds allocated to a specific supplier

Marketplace payouts are issued from the MARKETPLACE balance account to the marketplace's external bank account.

Payout Statuses

Status	Meaning
`COMPUTED`	Payout calculated from eligible captured orders, awaiting execution
`PENDING`	Payout execution triggered, awaiting PSP confirmation
`SETTLED`	PSP confirmed successful transfer to the marketplace bank account
`FAILED`	PSP reported a transfer failure; associated orders remain eligible for a future payout
`INSUFFICIENT_FUNDS`	Marketplace balance account does not have enough funds; no PSP call made

Typical Workflow

Step 1 — Computation

DJUST PAY consolidates marketplace commissions from captured orders into a single marketplace payout at status COMPUTED. The covered period is determined automatically — from the last successful payout execution to the current date.

Step 2 — Execution

Execution can be triggered in two ways:

Manually — by an operator from the back-office dashboard or via the API.
Automatically — DJUST PAY includes a built-in scheduling mechanism that triggers marketplace payouts on a regular cadence (weekly by default, every Monday morning). This runs per tenant with no manual intervention required.

When execution is triggered (manually or automatically), the system performs the following checks:

Status check — only payouts at status COMPUTED can be executed.
Balance check — DJUST PAY verifies that the marketplace balance account (BA_MKP) holds sufficient funds.
If funds are sufficient — a payout is triggered via the underlying payment provider, and the status transitions to PENDING.
If funds are insufficient — the status transitions to INSUFFICIENT_FUNDS. No payment provider call is made. The payout can be retried later once funds are available.

Step 3 — PSP Confirmation (Webhook)

Final confirmation is handled asynchronously via PSP webhooks:

Success — payout transitions to SETTLED. Associated orders are marked as having their marketplace commission paid out and will not be included in future payouts.
Failure — payout transitions to FAILED. Associated orders remain eligible for a future payout cycle.

Payout Flow

flowchart LR
  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef add      fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef remove   fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;
  classDef ok       fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef stop     fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;

  A["📘 Commissions<br>consolidated"]:::create
  B["✅ COMPUTED"]:::place
  C["🔄 Execute payout"]:::update
  D{{"💳 Funds sufficient<br>on BA_MKP?"}}:::decision
  E["⏳ PENDING<br>PSP payout triggered"]:::update
  F["⚠️ INSUFFICIENT_FUNDS"]:::stop
  G{{"📩 Webhook result"}}:::decision
  H["✅ SETTLED<br>Orders marked paid out"]:::place
  I["❌ FAILED<br>Orders remain eligible"]:::stop

  A --> B --> C --> D
  D -->|Yes| E
  D -->|No| F
  E --> G
  G -->|Success| H
  G -->|Failure| I

  style A rx:8,ry:8
  style B rx:8,ry:8
  style C rx:8,ry:8
  style E rx:8,ry:8
  style F rx:8,ry:8
  style H rx:8,ry:8
  style I rx:8,ry:8

Sequence Diagram

sequenceDiagram
    participant Operator
    participant DJUST PAY
    participant PSP

    Note over Operator,PSP: Step 1 - Marketplace commissions consolidated
    DJUST PAY->>DJUST PAY: Consolidate commissions from captured orders
    DJUST PAY-->>Operator: Marketplace payout created (COMPUTED)

    Note over Operator,PSP: Step 2 - Execution (manual or automatic)
    Operator->>DJUST PAY: Execute marketplace payout (back-office, API, or scheduled)
    DJUST PAY->>DJUST PAY: Check BA_MKP balance
    alt Sufficient funds
        DJUST PAY->>PSP: Trigger payout from BA_MKP
        DJUST PAY-->>Operator: Payout status = PENDING
        PSP-->>DJUST PAY: Webhook: payout confirmed
        DJUST PAY->>DJUST PAY: Status = SETTLED, orders marked as paid out
    else Insufficient funds
        DJUST PAY-->>Operator: Payout status = INSUFFICIENT_FUNDS
    end

Best Practices

Keep the marketplace balance funded — ensure the marketplace balance account (BA_MKP) holds sufficient funds before execution, otherwise the payout transitions to INSUFFICIENT_FUNDS.
Review computed payouts before manual execution — inspect payout details (amount, covered period, associated orders) on the back-office marketplace payouts dashboard to validate correctness before triggering execution.
Monitor INSUFFICIENT_FUNDS — this status indicates the marketplace balance account needs more funds before the payout can proceed. The operator can retry execution once funds are available.
Track via PSP identifiers — each executed payout carries a reference from the payment provider for reconciliation.
Leverage automatic scheduling — the built-in weekly schedule (Monday morning) ensures payouts are triggered regularly without manual intervention. Keep the marketplace balance funded to avoid INSUFFICIENT_FUNDS on scheduled runs.

Common Mistakes

Mistake	Consequence	How to avoid
Expecting instant settlement	Payout stays `PENDING` until PSP confirms	Settlement is asynchronous — monitor via webhooks or status polling
Ignoring `INSUFFICIENT_FUNDS` payouts	Marketplace commissions are not paid out	Monitor payout statuses, fund the marketplace BA, then retry execution

Error Reference

For the complete list of DJUST error and warning codes, refer to the dedicated page: Error / Warning codes