# 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 ```typescript class Transaction { constructor(data: TransactionData, http: HttpClient); // Properties (Getters) readonly id: string; readonly transactionType: string; readonly amount: number; readonly currency: string; readonly from: string; readonly to: string | null; readonly state: string; readonly status: string; // Alias of state readonly parentId: string | null; readonly meta: Record; readonly createdAt: string; readonly updatedAt: string; readonly executedAt: string | null; readonly children: string[]; // Execution & Lifecycle Methods execute(gatewayId?: string): Promise; cancel(): Promise; triggerEvent(event: string, context?: any): Promise; refund(amount?: number): Promise; // Information & Status Methods getCost(): Promise; refresh(): Promise; isFinal(): boolean; isPending(): boolean; isCompleted(): boolean; isFailed(): boolean; getStatus(): string; // Alias of state getMeta(): Record; getMetadata(): Record; // Alias of getMeta getChildren(): Promise; getStreams(): Promise; getConditions(): any; toJSON(): TransactionData; toString(): string; // Management & Configuration Methods update(updates: Partial): Promise; delete(): Promise; withConditions(conditionBuilder: ConditionBuilder): this; withCondition(condition: ConditionBuilder): this; // Alias of withConditions updateMeta(meta: Record): Promise; withMetadata(metadata: Record): this; executeGateway(gatewayId: string): Promise; toStream(options: { rate: number; rate_unit: string }): Promise; startStreaming(rate: number, unit: string): Promise; // Wrapper for toStream stream(options: { rate?: number; rateUnit?: string; rate_unit?: string; endTime?: string }): Promise; // More flexible stream creation subscribe(): StreamConnection; } ``` ## 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` **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` **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` - A promise that resolves with the updated `Transaction` object after execution. **Behavior**: Updates the transaction's state and may trigger fund movements. **Usage**: ```typescript await escrowTx.execute(); ``` * ### `cancel(): Promise` **Description**: Cancels the transaction if it is in a cancellable state. **Parameters**: None **Returns**: `Promise` - 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` **Description**: Triggers a custom event on the transaction. This is crucial for transactions with [conditional logic](/wiki/lantos1618/quicksilver-sdk/api-condition-builder) (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` - A promise that resolves with the updated `Transaction` object after the event is processed. **Behavior**: Evaluates any linked conditions and executes corresponding actions. **Usage**: ```typescript await escrowTx.triggerEvent(QuickSilverEvent.MilestoneApproved, { milestone: 'design' }); ``` * ### `refund(amount?: number): Promise` **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` - 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` **Description**: Retrieves the cost associated with the transaction. For streaming transactions, this represents the accumulated amount. **Parameters**: None **Returns**: `Promise` - 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` **Description**: Fetches the latest data for this transaction from the API and updates the current object. **Parameters**: None **Returns**: `Promise` - 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` **Description**: Retrieves the custom metadata associated with the transaction. **Parameters**: None **Returns**: `Record` - An object containing the transaction's metadata. * ### `getMetadata(): Record` **Description**: An alias for `getMeta()`. **Parameters**: None **Returns**: `Record` - An object containing the transaction's metadata. * ### `getChildren(): Promise` **Description**: Fetches any child transactions associated with this parent transaction. **Parameters**: None **Returns**: `Promise` - A promise that resolves with an array of `Transaction` objects representing the children. * ### `getStreams(): Promise` **Description**: Retrieves any streaming transactions associated with this transaction. **Parameters**: None **Returns**: `Promise` - 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): Promise` **Description**: Updates one or more fields of the transaction's data. **Parameters**: * `updates`: `Partial` - An object containing the fields to update. **Returns**: `Promise` - A promise that resolves with the updated `Transaction` object. * ### `delete(): Promise` **Description**: Deletes the transaction from the system. Note that not all transaction types or states can be deleted. **Parameters**: None **Returns**: `Promise` - A promise that resolves when the deletion is successful. * ### `withConditions(conditionBuilder: ConditionBuilder): this` **Description**: Attaches conditional logic to the transaction using a [ConditionBuilder](/wiki/lantos1618/quicksilver-sdk/api-condition-builder) 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): Promise` **Description**: Updates specific fields within the transaction's custom metadata. **Parameters**: * `meta`: `Record` - An object containing metadata fields to update. **Returns**: `Promise` - A promise that resolves with the updated `Transaction` object. * ### `withMetadata(metadata: Record): this` **Description**: Adds or merges custom metadata to the transaction (fluent interface). **Parameters**: * `metadata`: `Record` - An object containing metadata fields to add or update. **Returns**: `this` - The `Transaction` object itself. * ### `executeGateway(gatewayId: string): Promise` **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` - A promise that resolves with the updated `Transaction` object. * ### `toStream(options: { rate: number; rate_unit: string }): Promise` **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` - A promise that resolves with the streaming transaction data. * ### `startStreaming(rate: number, unit: string): Promise` **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` - A promise that resolves with the streaming transaction data. **Usage**: ```typescript const streamingTx = platform.transaction({ /* ... */ }); await streamingTx.execute(); // Later, if it's a configurable stream: await streamingTx.startStreaming(0.01, 'per_second'); ``` * ### `stream(options: { rate?: number; rateUnit?: string; rate_unit?: string; endTime?: string }): Promise` **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` - 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**: ```typescript const txConnection = myTransaction.subscribe(); txConnection.on('stream_event', (data) => console.log('Transaction event:', data)); txConnection.on('error', (err) => console.error('SSE Error:', err)); ```

API Reference: Transaction Model

Page Viewers

Guest Views