Payment Events

Payment events track the financial side of Siren’s pipeline, from the creation of a transaction through obligation issuance to the final payout. These events span three domains: transactions (Siren\Transactions\Core\Events), obligations (Siren\Obligations\Core\Events), and fulfillments (Siren\Fulfillments\Core\Events). Together they form the chain that turns a conversion into money owed, and money owed into money paid.

Transaction creation

Transaction events fire when financial records are created. The flow begins with a mutable request event that lets listeners shape transaction data before it is persisted, followed by a read-only notification once the record is committed.

TransactionCreateRequested fires before a transaction is written to the database. Because it is mutable, listeners can add, remove, or transform transaction details before the record is created. This is the primary extension point for customizing how transaction data is assembled.

TransactionCreated fires after the transaction has been persisted. Listeners use it for side effects that depend on a committed record, such as logging, syncing to external systems, or updating analytics.

Obligation lifecycle

An obligation represents a debt the business owes a collaborator as a result of a conversion. Obligation events track these commitments from creation through settlement.

ObligationIssued fires when an obligation is created for a conversion. It carries an optional conversion ID that links the obligation back to the conversion that caused it, since some creation paths like manual adjustments may not originate from a conversion.

ObligationCompleted fires when an obligation has been fulfilled through a payout. At this point the obligation’s status has been set to fulfilled and the payout ID has been written to the obligation record.

Fulfillment and payout processing

Fulfillment events fire during the payout generation process, when accumulated obligations are compiled into concrete payment records.

FulfillmentCreated fires when a new fulfillment batch is created. A fulfillment represents a single payout run that groups obligations together for disbursement.

FulfillmentStatusChanged fires when a fulfillment transitions between statuses. This event is useful for triggering notifications or external integrations as a fulfillment moves through its lifecycle.

PayoutCreated fires when an individual payout record is created within a fulfillment. A payout is a single disbursement line item specifying an amount, currency, and collaborator. A fulfillment that pays three collaborators will produce three separate events.

PayoutPaid fires when a payout is marked as disbursed. This is the terminal event in the payment flow. Listeners use it to trigger payment gateway confirmations, send receipt emails, or update external accounting systems.