Transaction Management

Comprehensive guide for creating, updating, and managing transactions throughout their lifecycle.

Quick Reference

Key Operations

• Create - Initialize new transactions → Creating a Simple Transaction
• Update - Modify existing transaction properties
• Close - Terminate transactions programmatically (admin action)
• Cancel - End transactions via participant action (user-initiated)

Required Permissions

Most transaction management operations require administrative privileges or transaction ownership.

Transaction Updates

Modify existing transaction properties such as description, participants, documents, or workflow settings.

Update Process Overview

1. Retrieve an updateable transaction model
2. Modify the desired properties
3. Commit changes via the update API

Implementation

// Step 1: Get updateable transaction
var req = new TransactionUpdateableRequestModel()
{
    IDs = new List<object> { 1234567890 }
};

var updateableApi = new TransactionsUpdateableApi(myRestEndpointUrl);
var results = updateableApi.GetTransactionsUpdateable(req, apiKey, apiSecret, apiUsername, apiPassword);

if (results.IsSuccessful.Value)
{
    // Step 2: Modify properties
    results.UpdateableTransactions[0].Description = "Updated Transaction Description";

    // Step 3: Commit changes
    var updateModel = new TransactionUpdateRequestModel()
    {
        Transactions = results.UpdateableTransactions
    };

    var transactionApi = new TransactionsApi(myRestEndpointUrl);
    var updateResults = transactionApi.UpdateTransactions(updateModel, apiKey, apiSecret, apiUsername, apiPassword);

    if (updateResults.IsSuccessful.Value)
    {
        // Update successful - transaction modified
        var updatedTransactionId = updateResults.TransactionIDs[0];
    }
    else
    {
        // Handle update error
        var error = updateResults.Message;
    }
}
else
{
    // Handle retrieval error
    var error = results.Message;
}

Updateable Properties

Common properties you can modify on existing transactions:

• Description - Transaction display name
• Participants - Add/remove signers and recipients
• Documents - Add/remove document attachments
• Workflow Settings - Signing order, authentication requirements
• Expiration Date - Transaction timeout settings
• Custom Fields - Metadata and tracking information

Transaction Termination

Closing vs Cancelling

Closing Transactions

Programmatically terminate transactions that are no longer needed:

var req = new TransactionCloseRequestModel()
{
    IDs = new List<object> { 1234567890, 1234567891 }  // Can close multiple
};

var api = new TransactionsApi(myRestEndpointUrl);
var results = api.CloseTransactions(req, apiKey, apiSecret, apiUsername, apiPassword);

if (results.IsSuccessful.Value)
{
    // Transactions closed successfully
    foreach (var closedId in results.ClosedTransactionIDs)
    {
        Console.WriteLine($"Transaction {closedId} has been closed");
    }
}
else
{
    // Handle close error
    var error = results.Message;
}

When to Close Transactions

• Expired transactions that won't be completed
• Test transactions in development environments
• Duplicate transactions created by mistake
• Process errors requiring cleanup
• Business requirement changes making transactions obsolete

Best Practices

Update Guidelines

• Validate permissions before attempting updates
• Check transaction status to ensure it's updateable
• Test changes in development environment first
• Batch multiple changes in a single update call when possible
• Log all modifications for audit trail

Error Handling

// Robust error handling example
try
{
    var results = api.UpdateTransactions(updateModel, apiKey, apiSecret, apiUsername, apiPassword);

    if (!results.IsSuccessful.Value)
    {
        // Log specific error details
        var errorMessage = results.Message;

        // Common issues to handle:
        // - Transaction already completed
        // - Insufficient permissions
        // - Invalid property values
        // - Concurrent modification conflicts

        throw new TransactionUpdateException(errorMessage);
    }
}
catch (Exception ex)
{
    // Handle network, authentication, or other system errors
    Console.WriteLine($"Transaction update failed: {ex.Message}");
}

Performance Optimization

• Retrieve minimal data when getting updateable transactions
• Batch operations when working with multiple transactions
• Cache transaction models for multiple property updates
• Use async patterns for non-blocking operations