Introduction

When a card payment is captured, Djust Pay computes a commission split that distributes the captured amount across up to three balance accounts:

1. The platform commission, routed to the Djust platform balance account.
2. The marketplace commission, routed to the marketplace owner balance account.
3. The supplier share, routed to the supplier balance account.

This page explains the algorithm step-by-step, the validation rules, and the structure of the split sent to the PSP.

📘

Authorization vs capture

No split is sent at the authorization step. The split is computed and applied only at capture, when the captured amount and the current commission rates are known.

Capture Workflow

sequenceDiagram
    autonumber
    participant Backend as Djust Pay Backend
    participant Settings as Tenant Settings
    participant Matrix as Marketplace Matrix
    participant PSP as PSP Capture Endpoint

    Backend->>Settings: Load platform rate<br>defaultRate
    Settings-->>Backend: Platform rate (or none)

    Backend->>Matrix: Load supplier rate<br>by supplierId
    Matrix-->>Backend: Supplier rate (or none)

    Backend->>Backend: Compute platform commission<br>Compute marketplace commission<br>Compute supplier share

    Backend->>Backend: Validate amounts >= 0<br>Validate sum = captured amount<br>Apply cent correction on supplier share

    Backend->>Backend: Build split[] with applicable lines

    Backend->>PSP: Capture call with amount + split[]
    PSP-->>Backend: Capture accepted or refused

    Backend->>Backend: Persist applied commissions

Capture Trigger

The capture step that consumes this calculation can be triggered:

• Manually via ADM-PAY-101, available in the Backoffice.
• Automatically when the related logistic order transitions to SHIPPED.

In both cases, the API contract for ADM-PAY-101 does not change. The split is applied transparently based on the rates configured at capture time.

Calculation Algorithm

Step 1 — Load the Rates

For each transaction, Djust Pay loads two sources of truth:

• Platform rate — set contractually with Djust at the tenant level. Operators do not configure this rate themselves.
• Marketplace rate — supplier-specific rate from the operator-managed matrix (Marketplace Commissions Matrix), looked up by supplier external ID.

A rate may be absent or zero:

• If the platform rate is not set on the tenant, no platform commission is applied.
• If the supplier has no active line in the matrix, no marketplace commission is applied.
• If neither is set, the entire captured amount is credited to the supplier.

Step 2 — Compute Each Component

Given a captured amount A (in minor units, i.e. cents):

The exact stored rates are used for these calculations — no rounding is applied before computing.

Step 3 — Round to Minor Units

The PSP expects every amount in minor units (integer cents). Each commission is rounded according to the rounding rule defined at the tenant level:

Step 4 — Apply Cent Correction

Independent rounding of each commission can introduce a small discrepancy (typically ±1 to ±3 cents) between the sum of the three rounded splits and the captured amount.

This discrepancy is corrected exclusively on the supplier share:

supplierShare = capturedAmount − roundedPlatformCommission − roundedMarketplaceCommission

This guarantees that:

roundedPlatformCommission + roundedMarketplaceCommission + supplierShare = capturedAmount

⚠️

Constraint

The supplier share must remain greater than or equal to zero after the cent correction. If it would be negative, the capture is blocked with a functional error (see Validation).

Worked Example

Assuming a tenant configured for nearest-cent rounding:

Check: 127 + 699 + 9474 = 10300 ✅

Split Structure

The split sent to the PSP is an array of up to three lines. Lines are included only when their corresponding rate exists:

Each line targets one balance account: the Djust platform account, the marketplace owner account, or the supplier account associated with the order.

Validation

Before the capture call is sent, Djust Pay enforces the following invariants:

• No commission amount is negative.
• No commission amount exceeds the captured amount.
• The supplier share is greater than or equal to zero after the cent correction.
• The sum of all split amounts is strictly equal to the captured amount.

If any invariant is violated, the capture is blocked with a functional error and no call is made to the PSP.

Persistence and Audit

When the capture succeeds, Djust Pay records the commissions actually applied alongside the transaction:

• Each split amount, type, account, and reference
• The rates effective at capture time
• The PSP capture reference

This persistence is the source of truth used for accounting reconciliation and reporting. It guarantees that historical transactions remain auditable even if the underlying rates are later updated or removed.

Security

• No commission rate or split information is accepted from clients in capture requests.
• No customer-facing role (OPERATOR, ACCOUNT, SUPPLIER) can influence the split calculation directly.
• Rates are loaded server-side at capture time from the tenant settings and the marketplace matrix only.

Related

• Marketplace Commissions Matrix — supplier-specific marketplace commission rates
• Managing Card Payments — full card payment lifecycle
• Refunds — proportional commission adjustment on partial refunds