API Reference: Transaction Model

The Transaction model in the Quicksilver SDK is an active record object that encapsulates the data and behavior of a financial transaction within the Quicksilver Engine. Unlike a passive data structure, a Transaction object provides fluent methods to interact with and manage the transaction's lifecycle, execute conditional logic, handle streaming payments, and integrate with real-time events.

Each Transaction instance is created either by the QuicksilverClient directly (e.g., via client.transactions.create() or client.createTransaction()) or fluently from an Account object (e.g., account.transaction()).

Transaction Class

Constructor

`new Transaction(data, http)`

data: TransactionData - The raw data representing a transaction as returned by the API.
http: HttpClient - An instance of HttpClient used for making API requests.

Description: Initializes a new instance of the Transaction active record model. This constructor is typically called internally by the SDK when creating a transaction via client.transactions.create() or account.transaction(), or when retrieving existing transaction data.

Properties (Getters)

These properties provide direct access to the transaction's underlying data.

id: string
Description: The unique identifier of the transaction.
transactionType: string
Description: The type of the transaction (e.g., 'Payment', 'Escrow', 'Stream', 'Scheduled').
amount: number
Description: The total amount of the transaction.
currency: string
Description: The currency of the transaction (e.g., 'USD', 'EUR').
from: string
Description: The ID of the originating account for the transaction.
to: string | null
Description: The ID of the recipient account for the transaction, or null if not applicable (e.g., for some internal fund movements).
state: string
Description: The current state of the transaction (e.g., 'Draft', 'Pending', 'Executing', 'Completed', 'Failed', 'Cancelled').
status: string
Description: An alias for the state property, providing consistency.
parentId: string | null
Description: The ID of the parent transaction, if this is a sub-transaction, or null.
meta: Record<string, any>
Description: A key-value store for custom metadata associated with the transaction.
createdAt: string
Description: The ISO 8601 timestamp when the transaction was created.
updatedAt: string
Description: The ISO 8601 timestamp when the transaction was last updated.
executedAt: string | null
Description: The ISO 8601 timestamp when the transaction was executed, or null if not yet executed.
children: string[]
Description: A list of IDs of any child transactions associated with this transaction.

Methods

The Transaction object provides a rich set of methods that encapsulate transactional behavior, allowing for a more object-oriented approach to programmable money.

Execution & Lifecycle Methods

execute(gatewayId?: string): Promise<this>
Description: Initiates the execution of the transaction. If gatewayId is provided, it attempts to execute through a specific payment gateway. Parameters:
- gatewayId?: string (optional) - The ID of the payment gateway to use for execution. Returns: Promise<this> - A promise that resolves with the updated Transaction object after execution. Behavior: Updates the transaction's state and may trigger fund movements. Usage:
cancel(): Promise<this>
Description: Cancels the transaction if it is in a cancellable state. Parameters: None Returns: Promise<this> - A promise that resolves with the updated Transaction object after cancellation. Behavior: Marks the transaction as 'Cancelled' and prevents further processing.
triggerEvent(event: string, context?: any): Promise<this>
Description: Triggers a custom event on the transaction. This is crucial for transactions with conditional logic (e.g., escrow, milestone payments) to advance their state based on external occurrences. Parameters:
- event: string - The name of the event to trigger (e.g., QuickSilverEvent.MilestoneApproved).
- context?: any (optional) - Additional data related to the event, which can be used by conditional predicates. Returns: Promise<this> - A promise that resolves with the updated Transaction object after the event is processed. Behavior: Evaluates any linked conditions and executes corresponding actions. Usage:
refund(amount?: number): Promise<this>
Description: Refunds all or a partial amount of the transaction. Parameters:
- amount?: number (optional) - The specific amount to refund. If not provided, the full transaction amount will be refunded. Returns: Promise<this> - A promise that resolves with the updated Transaction object after the refund. Behavior: Creates a refund transaction and updates the status of the original transaction.

Information & Status Methods

getCost(): Promise<number>
Description: Retrieves the cost associated with the transaction. For streaming transactions, this represents the accumulated amount. Parameters: None Returns: Promise<number> - A promise that resolves with the numerical cost. Behavior: For simple payments, it's the amount. For streams, it might query accumulated charges.
refresh(): Promise<this>
Description: Fetches the latest data for this transaction from the API and updates the current object. Parameters: None Returns: Promise<this> - A promise that resolves with the updated Transaction object. Behavior: Ensures the local Transaction object reflects the most current state on the server.
isFinal(): boolean
Description: Checks if the transaction is in a final, immutable state (e.g., 'Completed', 'Failed', 'Cancelled'). Parameters: None Returns: boolean - true if final, false otherwise. Behavior: Provides a quick way to determine if further lifecycle actions are possible.
isPending(): boolean
Description: Checks if the transaction is currently in a pending or draft state. Parameters: None Returns: boolean - true if pending/draft, false otherwise.
isCompleted(): boolean
Description: Checks if the transaction has successfully completed. Parameters: None Returns: boolean - true if completed, false otherwise.
isFailed(): boolean
Description: Checks if the transaction has failed. Parameters: None Returns: boolean - true if failed, false otherwise.
getStatus(): string
Description: Returns the current state or status of the transaction. Parameters: None Returns: string - The transaction's status.
getMeta(): Record<string, any>
Description: Retrieves the custom metadata associated with the transaction. Parameters: None Returns: Record<string, any> - An object containing the transaction's metadata.
getMetadata(): Record<string, any>
Description: An alias for getMeta(). Parameters: None Returns: Record<string, any> - An object containing the transaction's metadata.
getChildren(): Promise<Transaction[]>
Description: Fetches any child transactions associated with this parent transaction. Parameters: None Returns: Promise<Transaction[]> - A promise that resolves with an array of Transaction objects representing the children.
getStreams(): Promise<any[]>
Description: Retrieves any streaming transactions associated with this transaction. Parameters: None Returns: Promise<any[]> - A promise that resolves with an array of streaming transaction objects.
getConditions(): any
Description: Retrieves the conditional logic currently set on the transaction. Parameters: None Returns: any - The conditions object or array configured for the transaction.
toJSON(): TransactionData
Description: Serializes the internal data of the Transaction object into a plain JavaScript object, suitable for API submission or logging. Parameters: None Returns: TransactionData - The raw transaction data.
toString(): string
Description: Returns a string representation of the transaction, useful for debugging. Parameters: None Returns: string - A string like Transaction(txn_123, 100 USD, pending).

Management & Configuration Methods

update(updates: Partial<TransactionData>): Promise<this>
Description: Updates one or more fields of the transaction's data. Parameters:
- updates: Partial<TransactionData> - An object containing the fields to update. Returns: Promise<this> - A promise that resolves with the updated Transaction object.
delete(): Promise<void>
Description: Deletes the transaction from the system. Note that not all transaction types or states can be deleted. Parameters: None Returns: Promise<void> - A promise that resolves when the deletion is successful.
withConditions(conditionBuilder: ConditionBuilder): this
Description: Attaches conditional logic to the transaction using a ConditionBuilder instance. This enables sophisticated smart contract-like behavior. Parameters:
- conditionBuilder: ConditionBuilder - An instance of ConditionBuilder containing the desired conditional logic. Returns: this - The Transaction object itself, allowing for method chaining. Behavior: Populates the conditions field of the transaction's meta data.
withCondition(condition: ConditionBuilder): this
Description: An alias for withConditions(). Parameters:
- condition: ConditionBuilder - An instance of ConditionBuilder. Returns: this - The Transaction object itself.
updateMeta(meta: Record<string, any>): Promise<this>
Description: Updates specific fields within the transaction's custom metadata. Parameters:
- meta: Record<string, any> - An object containing metadata fields to update. Returns: Promise<this> - A promise that resolves with the updated Transaction object.
withMetadata(metadata: Record<string, any>): this
Description: Adds or merges custom metadata to the transaction (fluent interface). Parameters:
- metadata: Record<string, any> - An object containing metadata fields to add or update. Returns: this - The Transaction object itself.
executeGateway(gatewayId: string): Promise<this>
Description: Executes the transaction through a specific payment gateway. Similar to execute() but explicitly specifies the gateway. Parameters:
- gatewayId: string - The ID of the payment gateway. Returns: Promise<this> - A promise that resolves with the updated Transaction object.
toStream(options: { rate: number; rate_unit: string }): Promise<any>
Description: Converts a base transaction into a streaming transaction with specified rate and unit. Parameters:
- options: object - Configuration for the stream.
  - rate: number - The rate of the stream.
  - rate_unit: string - The unit for the rate (e.g., 'per_second', 'per_word'). Returns: Promise<any> - A promise that resolves with the streaming transaction data.
startStreaming(rate: number, unit: string): Promise<any>
Description: A wrapper method to initiate streaming payments. Parameters:
- rate: number - The rate of the stream.
- unit: string - The unit for the rate (e.g., 'per_second', 'per_word'). Returns: Promise<any> - A promise that resolves with the streaming transaction data. Usage:
stream(options: { rate?: number; rateUnit?: string; rate_unit?: string; endTime?: string }): Promise<any>
Description: Creates or configures a streaming transaction with more flexible options, including endTime. Parameters:
- options: object - Configuration for the stream.
  - rate?: number (optional) - The rate of the stream.
  - rateUnit?: string (optional) - The unit for the rate (e.g., 'per_second', 'per_minute').
  - rate_unit?: string (optional) - Alias for rateUnit.
  - endTime?: string (optional) - The ISO 8601 timestamp when the stream should automatically end. Returns: Promise<any> - A promise that resolves with the streaming transaction data.
subscribe(): StreamConnection
Description: Establishes a real-time Server-Sent Events (SSE) connection to receive updates for this specific transaction (e.g., for streaming payment events, conditional logic triggers). Parameters: None Returns: StreamConnection - An EventEmitter-like object that emits events such as 'stream_event' and 'batch_created'. Behavior: Allows building responsive, event-driven interfaces. Usage:

API Reference: Transaction Model

API Reference: Transaction Model

Transaction Class

Constructor

new Transaction(data, http)

Properties (Getters)

id: string

transactionType: string

amount: number

currency: string

from: string

to: string | null

state: string

status: string

parentId: string | null

meta: Record<string, any>

createdAt: string

updatedAt: string

executedAt: string | null

children: string[]

Methods

Execution & Lifecycle Methods

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

cancel(): Promise<this>

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

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

Information & Status Methods

getCost(): Promise<number>

refresh(): Promise<this>

isFinal(): boolean

isPending(): boolean

isCompleted(): boolean

isFailed(): boolean

getStatus(): string

getMeta(): Record<string, any>

getMetadata(): Record<string, any>

getChildren(): Promise<Transaction[]>

getStreams(): Promise<any[]>

getConditions(): any

toJSON(): TransactionData

toString(): string

Management & Configuration Methods

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

delete(): Promise<void>

withConditions(conditionBuilder: ConditionBuilder): this

withCondition(condition: ConditionBuilder): this

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

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

executeGateway(gatewayId: string): Promise<this>

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

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

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

subscribe(): StreamConnection

`new Transaction(data, http)`

`id: string`

`transactionType: string`

`amount: number`

`currency: string`

`from: string`

`to: string | null`

`state: string`

`status: string`

`parentId: string | null`

`meta: Record<string, any>`

`createdAt: string`

`updatedAt: string`

`executedAt: string | null`

`children: string[]`

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

`cancel(): Promise<this>`

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

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

`getCost(): Promise<number>`

`refresh(): Promise<this>`

`isFinal(): boolean`

`isPending(): boolean`

`isCompleted(): boolean`

`isFailed(): boolean`

`getStatus(): string`

`getMeta(): Record<string, any>`

`getMetadata(): Record<string, any>`

`getChildren(): Promise<Transaction[]>`

`getStreams(): Promise<any[]>`

`getConditions(): any`

`toJSON(): TransactionData`

`toString(): string`

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

`delete(): Promise<void>`

`withConditions(conditionBuilder: ConditionBuilder): this`

`withCondition(condition: ConditionBuilder): this`

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

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

`executeGateway(gatewayId: string): Promise<this>`

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

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

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

`subscribe(): StreamConnection`