Payout Workflow¶
A Commission Payout tracks the process of paying an approved Commission Statement.
A payout can only be created from a Posted Commission Statement and follows a controlled workflow from Pending through payment processing to Paid.
Workflow Overview¶
The normal payout lifecycle is:
Pending
↓
Processing
↓
Paid
The workflow also supports payment failures and cancellation:
Pending
├──→ Processing
└──→ Cancelled
Processing
├──→ Paid
└──→ Failed
Failed
├──→ Processing
└──→ Cancelled
Creating a Payout¶
A Commission Payout is created from a Posted Commission Statement.
For example:
Commission Statement
Status: Posted
Net Commission: ₹5,000
Creating the payout produces:
Commission Payout
Amount: ₹5,000
Status: Pending
The payout receives its key information from the statement:
- Commission Statement
- Commission Payee
- Company
- Currency
- Amount
These fields are controlled by the application.
Pending¶
A newly created payout starts in:
Pending
Pending means the payout exists but payment processing has not yet started.
The payout is associated with a Posted Commission Statement.
The next normal transition is:
Pending
↓
Processing
A Pending payout can also be cancelled when the payment should no longer proceed.
Pending
↓
Cancelled
Processing¶
Processing indicates that payment processing has begun.
The transition is:
Pending
↓
Processing
While the payout is Processing, the payment has not yet been confirmed as completed.
The next possible outcomes are:
Processing
├──→ Paid
└──→ Failed
Failed¶
A payout enters Failed when payment processing does not succeed.
A Failed payout can be retried:
Failed
↓
Processing
This allows the payment process to be attempted again without changing the original Commission Statement.
If the payout should no longer proceed, it can instead be cancelled:
Failed
↓
Cancelled
Payment Details¶
A payout must contain payment information before it can be marked Paid.
The required fields are:
- Payment Date
- Payment Reference
Payment Date¶
Payment Date records when the payment was made.
Example:
Payment Date: 2026-10-05
Payment Reference¶
Payment Reference identifies the actual payment transaction.
Example:
Payment Reference: UTR-TEST-0001
The reference can be a bank transaction identifier or another payment reference used by the organization.
Marking a Payout as Paid¶
A payout can be marked Paid only after the required payment information has been entered.
The application validates:
Payment Date
Payment Reference
If Payment Date is missing, the payout cannot be marked Paid.
If Payment Reference is missing, the payout cannot be marked Paid.
Once both are provided, the payout can move from:
Processing
↓
Paid
The payment fields provide a basic audit trail for the completed payment.
Statement Synchronization¶
When a Commission Payout is successfully marked Paid, the associated Commission Statement is also marked Paid.
The relationship is:
Commission Payout
│
│ Mark Paid
▼
Commission Statement
│
▼
Paid
This ensures that the statement reflects the payment state of its associated payout.
The payout is responsible for the payment event; the statement records that its approved commission has been paid.
Payout Amount¶
The payout amount is taken from the Commission Statement's Net Commission.
For example:
Gross Commission = ₹5,500
Adjustments = -₹500
Net Commission = ₹5,000
The payout amount is:
₹5,000
The payout does not recalculate the commission.
The calculation has already been captured in the Commission Ledger and grouped into the Commission Statement.
One Active Payout per Statement¶
The application prevents multiple active payouts from being created for the same Commission Statement.
This helps prevent the same approved commission from being paid more than once.
Conceptually:
Posted Statement
│
└── Active Payout
A second active payout for the same statement is not allowed.
Cancellation¶
A payout can be cancelled from the workflow states where cancellation is allowed.
The supported paths are:
Pending
↓
Cancelled
and:
Failed
↓
Cancelled
A cancelled payout does not continue through payment processing.
The Commission Statement remains a record of the approved commission.
Complete State Machine¶
The payout workflow can be represented as:
┌────────────┐
│ Pending │
└─────┬──────┘
┌───┴───┐
Process Cancel
│ │
▼ ▼
┌────────────┐ Cancelled
│ Processing │
└─────┬──────┘
┌──┴──┐
Paid Failed
│ │
▼ ┌──┴──┐
Paid Retry Cancel
│ │
▼ ▼
Processing Cancelled
The important normal path is:
Pending
↓
Processing
↓
Paid
Workflow Transitions¶
The payout workflow supports:
| Current Status | Allowed Next Status |
|---|---|
| Pending | Processing, Cancelled |
| Processing | Paid, Failed |
| Failed | Processing, Cancelled |
| Paid | None |
| Cancelled | None |
Paid and Cancelled are terminal states.
Why Payment Is Separate From Commission Approval¶
Commission calculation and payment are intentionally separate.
The statement represents the approved commission:
Commission Statement
↓
Posted
The payout represents the payment process:
Posted Statement
↓
Commission Payout
↓
Processing
↓
Paid
This allows an organization to distinguish between:
Commission approved
and:
Commission actually paid
For example, a statement can remain Posted for several days before its payout is processed.
Example¶
Suppose a Posted statement contains:
Commission Payee: Test Salesperson
Net Commission: ₹500
Create the payout:
Amount: ₹500
Status: Pending
Begin processing:
Pending
↓
Processing
Enter:
Payment Date: 2026-10-05
Payment Reference: UTR-TEST-0001
Mark the payout Paid:
Processing
↓
Paid
The associated statement then becomes:
Paid
The complete payment portion of the lifecycle is:
Posted Statement
↓
Pending Payout
↓
Processing
↓
Payment Date + Reference
↓
Paid
↓
Statement Paid
Failed Payment Example¶
Suppose a payout starts processing but the payment fails.
The state becomes:
Processing
↓
Failed
The payment can then be retried:
Failed
↓
Processing
If the retry succeeds:
Processing
↓
Paid
If the payout should no longer be processed:
Failed
↓
Cancelled
The original Commission Statement and Commission Ledger remain historical records of the approved and calculated commission.
Best Practices¶
Process Only Posted Statements¶
Create payouts only after the Commission Statement has completed review and approval and reached Posted.
Verify Payment Details¶
Before marking a payout Paid, make sure the Payment Date and Payment Reference correspond to the actual payment.
Use Failed for Unsuccessful Payments¶
If a payment attempt fails, use the Failed state rather than changing the payout amount or statement.
This preserves the distinction between the approved commission and the payment attempt.
Do Not Duplicate Payouts¶
Use the existing payout for the statement rather than creating another active payout for the same statement.
Treat Paid Payouts as Historical Records¶
Once a payout is Paid, it represents a completed payment event.
The payment details provide the historical record of that event.
Related Workflows¶
Next Step¶
The next workflow explains what happens when a commission-generating Sales Invoice is cancelled and how the application records the resulting reversal.
Continue with Reversals.