Transaction Model API Reference

The Transaction class is an active model representing a transaction within the Quicksilver Engine. It provides a fluent interface for interacting with and managing transaction data, including execution, cancellation, and event triggering.

Class: Transaction

Constructor

constructor(data: TransactionData, http: HttpClient)

Initializes a new Transaction active model instance.

• data: TransactionData - The raw transaction data from the API.
• http: HttpClient - The HTTP client instance used for API requests.

Properties

id: string

string // The unique identifier of the transaction.

transactionType: string

string // The type of the transaction (e.g., 'Payment', 'Escrow', 'Stream').

amount: number

number // The monetary amount of the transaction.

currency: string

string // The currency of the transaction (e.g., 'USD', 'EUR', 'POINTS').

from: string

string // The ID of the account initiating the transaction.

to: string | null

string | null // The ID of the recipient account for the transaction, or null if not applicable.

state: string

string // The current state of the transaction (e.g., 'Draft', 'Pending', 'Executing', 'Completed', 'Failed', 'Cancelled').

status: string

string // An alias for state, representing the current status of the transaction.

parentId: string | null

string | null // The ID of the parent transaction, if this is a sub-transaction.

meta: Record<string, any>

Record<string, any> // Custom metadata associated with the transaction.

createdAt: string

string // The ISO 8601 timestamp when the transaction was created.

updatedAt: string

string // The ISO 8601 timestamp when the transaction was last updated.

executedAt: string | null

string | null // The ISO 8601 timestamp when the transaction was executed, or null if not yet executed.

children: string[]

string[] // A list of IDs of child transactions related to this transaction.

Methods

execute(gatewayId?: string): Promise<this>

Promise<this> // Executes the transaction, optionally through a specified payment gateway.

• gatewayId: string - (Optional) The ID of the payment gateway to use for execution. If omitted, the default execution path is used.

cancel(): Promise<this>

Promise<this> // Cancels the transaction if it is not in a final state.

triggerEvent(event: string, context?: any): Promise<this>

Promise<this> // Triggers a custom event on the transaction, primarily used for evaluating attached conditional logic.

• event: string - The name of the event to trigger.
• context: any - (Optional) Additional context data to be passed with the event.

getCost(): Promise<number>

Promise<number> // Retrieves the total cost or accumulated amount of the transaction. This is particularly useful for streaming payments.

refresh(): Promise<this>

Promise<this> // Refreshes the transaction's data from the server, updating its local state and properties.

isFinal(): boolean

boolean // Checks if the transaction is in a final, irreversible state (e.g., 'Completed', 'Failed', 'Cancelled').

isPending(): boolean

boolean // Checks if the transaction is currently pending execution or in a draft state.

getChildren(): Promise<Transaction[]>

Promise<Transaction[]> // Retrieves all child transactions associated with this transaction, typically for complex workflows.

withConditions(conditionBuilder: ConditionBuilder): this

this // Attaches conditional logic to the transaction using a ConditionBuilder.

• conditionBuilder: ConditionBuilder - An instance of ConditionBuilder defining the conditional logic.

getMeta(): Record<string, any>

Record<string, any> // Retrieves the custom metadata associated with the transaction.

updateMeta(meta: Record<string, any>): Promise<this>

Promise<this> // Updates the custom metadata for the transaction.

• meta: Record<string, any> - The new metadata to merge or replace.

subscribe(): StreamConnection

StreamConnection // Subscribes to real-time events for this specific transaction via Server-Sent Events (SSE).

getStatus(): string

string // Returns the current status of the transaction. (Alias for the state getter).

getMetadata(): Record<string, any>

Record<string, any> // Returns the custom metadata associated with the transaction. (Alias for getMeta getter).

withMetadata(metadata: Record<string, any>): this

this // Adds or updates metadata for the transaction using a fluent interface.

• metadata: Record<string, any> - The metadata to add or update.

withCondition(condition: ConditionBuilder): this

this // Adds conditional logic to the transaction using a fluent interface. (Alias for withConditions).

• condition: ConditionBuilder - An instance of ConditionBuilder defining the conditional logic.

toStream(options: { rate: number; rate_unit: string }): Promise<any>

Promise<any> // Converts a base transaction into a streaming transaction with specified rate and unit.

• options: { rate: number; rate_unit: string } - Configuration for the streaming transaction, including the payment rate and unit (e.g., 'per_second', 'per_word').

startStreaming(rate: number, unit: string): Promise<any>

Promise<any> // Starts streaming this transaction with a given rate and unit. (Alias for toStream).

• rate: number - The rate of the stream.
• unit: string - The unit for the stream rate (e.g., 'per_second', 'per_word').

update(updates: Partial<TransactionData>): Promise<this>

Promise<this> // Updates the transaction with partial data.

• updates: Partial<TransactionData> - A partial object containing the fields to update.

delete(): Promise<void>

Promise<void> // Deletes the transaction from the system. Note: This action may not be allowed for all transaction states.

executeGateway(gatewayId: string): Promise<this>

Promise<this> // Executes the transaction through a specific payment gateway. (Functionally similar to execute(gatewayId)).

• gatewayId: string - The ID of the payment gateway to use.

stream(options: { rate?: number; rateUnit?: string; rate_unit?: string; endTime?: string }): Promise<any>

Promise<any> // Creates or manages a streaming transaction with flexible options for rate, unit, and end time.

• options: { rate?: number; rateUnit?: string; rate_unit?: string; endTime?: string } - Streaming configuration options, including rate, unit, and optional end time.

refund(amount?: number): Promise<this>

Promise<this> // Refunds a transaction, either partially or in full.

• amount: number - (Optional) The specific amount to refund. If omitted, the full transaction amount is refunded.

getStreams(): Promise<any[]>

Promise<any[]> // Retrieves all streaming components associated with this transaction.

toJSON(): TransactionData

TransactionData // Returns the raw transaction data object, useful for serialization.

isCompleted(): boolean

boolean // Checks if the transaction has completed successfully.

isFailed(): boolean

boolean // Checks if the transaction has failed.

getConditions(): any

any // Retrieves the conditional logic attached to the transaction.

toString(): string

string // Returns a string representation of the transaction, useful for logging and debugging.