entities

func CreateAccount ¶

func CreateAccount(
	ctx context.Context,
	orgID, ledgerID, name, accountType, assetCode, alias string,
	service entities.AccountsService,
) (*models.Account, error)

CreateAccount creates a new account within a ledger.

This function simplifies account creation by handling the construction of the CreateAccountInput model and setting up appropriate metadata. It demonstrates how to properly structure account creation requests.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the account will be created. Must be a valid UUID.
• name: Human-readable name for the account (e.g., "Customer Account").
• accountType: Type of account (e.g., "deposit", "marketplace", "external").
• assetCode: The asset code for the account (e.g., "USD").
• alias: Optional alias for the account, stored in metadata.
• service: The AccountsService instance to use for the API call.

Returns:

• *models.Account: The created account if successful.
• error: Any error encountered during account creation.

Example:

account, err := entities.CreateAccount(
    ctx,
    "org-123",
    "ledger-456",
    "Customer Account",
    "deposit",
    "USD",
    "customer-123",
    sdkEntity.Accounts,
)

func CreateAsset ¶

func CreateAsset(
	ctx context.Context,
	orgID, ledgerID, name, assetType, code string,
	service entities.AssetsService,
) (*models.Asset, error)

CreateAsset creates a new asset within a ledger.

This function simplifies asset creation by handling the construction of the CreateAssetInput model and setting up appropriate metadata. It demonstrates how to properly structure asset creation requests using the builder pattern.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the asset will be created. Must be a valid UUID.
• name: Human-readable name for the asset (e.g., "US Dollar").
• assetType: Type of asset (e.g., "currency", "security", "commodity").
• code: The asset code, typically a standard currency code (e.g., "USD", "EUR").
• service: The AssetsService instance to use for the API call.

Returns:

• *models.Asset: The created asset if successful.
• error: Any error encountered during asset creation.

Example:

asset, err := entities.CreateAsset(
    ctx,
    "org-123",
    "ledger-456",
    "US Dollar",
    "currency",
    "USD",
    sdkEntity.Assets,
)

func CreateLedger ¶

func CreateLedger(ctx context.Context, orgID string, service entities.LedgersService) (*models.Ledger, error)

CreateLedger creates a new ledger within an organization.

This function simplifies ledger creation by handling the construction of the CreateLedgerInput model and setting up appropriate metadata. It demonstrates how to properly structure ledger creation requests using the builder pattern.

A ledger is a financial record-keeping system that contains accounts and transactions. In the Midaz system, ledgers are owned by organizations and can contain multiple accounts, assets, and transactions.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that will own the ledger. Must be a valid UUID.
• service: The LedgersService instance to use for the API call.

Returns:

• *models.Ledger: The created ledger if successful.
• error: Any error encountered during ledger creation.

Example:

ledger, err := entities.CreateLedger(
    ctx,
    "org-123",
    sdkEntity.Ledgers,
)

func CreateOperationRoute ¶

func CreateOperationRoute(
	ctx context.Context,
	orgID, ledgerID, title, description, routeType string,
	service entities.OperationRoutesService,
) (*models.OperationRoute, error)

CreateOperationRoute creates a new operation route within a ledger.

This function simplifies operation route creation by handling the construction of the CreateOperationRouteInput model and setting up appropriate metadata. It demonstrates how to properly structure operation route creation requests.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the operation route will be created. Must be a valid UUID.
• title: Human-readable title for the operation route (e.g., "Cash-in Route").
• description: Description of the operation route's purpose.
• routeType: Type of operation route (e.g., "source", "destination").
• service: The OperationRoutesService instance to use for the API call.

Returns:

• *models.OperationRoute: The created operation route if successful.
• error: Any error encountered during operation route creation.

Example:

operationRoute, err := entities.CreateOperationRoute(
    ctx,
    "org-123",
    "ledger-456",
    "Cash-in Route",
    "Handles cash-in operations",
    "source",
    sdkEntity.OperationRoutes,
)

func CreateOrganization ¶

func CreateOrganization(ctx context.Context, service entities.OrganizationsService) (*models.Organization, error)

CreateOrganization creates a new organization in the Midaz system.

This function simplifies organization creation by handling the construction of the CreateOrganizationInput model and setting up appropriate fields and metadata. It demonstrates how to properly structure organization creation requests, including handling of optional pointer fields.

Organizations are the top-level entities in the Midaz system and contain ledgers, which in turn contain accounts, assets, and transactions.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• service: The OrganizationsService instance to use for the API call.

Returns:

• *models.Organization: The created organization if successful.
• error: Any error encountered during organization creation.

Example:

organization, err := entities.CreateOrganization(
    ctx,
    sdkEntity.Organizations,
)

func CreatePortfolio ¶

func CreatePortfolio(
	ctx context.Context,
	orgID, ledgerID, name, description string,
	service entities.PortfoliosService,
) (*models.Portfolio, error)

CreatePortfolio creates a new portfolio within a ledger.

This function simplifies portfolio creation by handling the construction of the CreatePortfolioInput model and setting up appropriate metadata. It demonstrates how to properly structure portfolio creation requests using the builder pattern.

Portfolios in the Midaz system are collections of accounts that can be managed together. They can be used to group accounts by purpose, owner, or any other organizational criteria.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the portfolio will be created. Must be a valid UUID.
• name: Human-readable name for the portfolio (e.g., "Investment Portfolio").
• description: A description of the portfolio's purpose.
• service: The PortfoliosService instance to use for the API call.

Returns:

• *models.Portfolio: The created portfolio if successful.
• error: Any error encountered during portfolio creation.

Example:

portfolio, err := entities.CreatePortfolio(
    ctx,
    "org-123",
    "ledger-456",
    "Main Portfolio",
    "Portfolio for managing customer accounts",
    sdkEntity.Portfolios,
)

func CreateSegment ¶

func CreateSegment(
	ctx context.Context,
	orgID, ledgerID, name string,
	service entities.SegmentsService,
) (*models.Segment, error)

CreateSegment creates a new segment within a portfolio.

This function simplifies segment creation by handling the construction of the CreateSegmentInput model and setting up appropriate metadata. It demonstrates how to properly structure segment creation requests using the builder pattern.

Segments in the Midaz system are subdivisions of portfolios that can be used to further categorize accounts. They provide an additional level of organization beyond portfolios, allowing for more granular management of accounts.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the portfolio exists. Must be a valid UUID.
• name: Human-readable name for the segment (e.g., "Retail Customers").
• service: The SegmentsService instance to use for the API call.

Returns:

• *models.Segment: The created segment if successful.
• error: Any error encountered during segment creation.

Example:

segment, err := entities.CreateSegment(
    ctx,
    "org-123",
    "ledger-456",
    "Premium Customers",
    sdkEntity.Segments,
)

func CreateTransactionRoute ¶

func CreateTransactionRoute(
	ctx context.Context,
	orgID, ledgerID, title, description string,
	operationRoutes []string,
	service entities.TransactionRoutesService,
) (*models.TransactionRoute, error)

CreateTransactionRoute creates a new transaction route within a ledger.

This function simplifies transaction route creation by handling the construction of the CreateTransactionRouteInput model and setting up appropriate metadata. It demonstrates how to properly structure transaction route creation requests.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the transaction route will be created. Must be a valid UUID.
• title: Human-readable title for the transaction route (e.g., "Payment Route").
• description: Description of the transaction route's purpose.
• operationRoutes: List of operation route IDs that belong to this transaction route.
• service: The TransactionRoutesService instance to use for the API call.

Returns:

• *models.TransactionRoute: The created transaction route if successful.
• error: Any error encountered during transaction route creation.

Example:

transactionRoute, err := entities.CreateTransactionRoute(
    ctx,
    "org-123",
    "ledger-456",
    "Payment Route",
    "Handles payment transactions",
    []string{"route-123", "route-456"},
    sdkEntity.TransactionRoutes,
)

func ExecuteDepositWithHelper ¶

func ExecuteDepositWithHelper(
	ctx context.Context,
	midazClient *client.Client,
	orgID, ledgerID string,
	accountID string,
	amount string,
	assetCode string,
) (*models.Transaction, error)

ExecuteDepositWithHelper deposits funds from an external source to an account

Parameters:

• ctx: The context for the operation, which can be used for cancellation
• entity: The initialized Midaz SDK entity client
• orgID: The ID of the organization
• ledgerID: The ID of the ledger
• accountID: The destination account ID
• amount: The amount to deposit (as decimal string)
• assetCode: The asset code for the deposit

Returns:

• *models.Transaction: The created transaction
• error: Any error encountered during the operation

func ExecuteMultiAccountTransferWithHelper ¶

func ExecuteMultiAccountTransferWithHelper(
	ctx context.Context,
	midazClient *client.Client,
	orgID, ledgerID string,
	sourceAccounts map[string]string,
	destAccounts map[string]string,
	totalAmount string,
	assetCode string,
) (*models.Transaction, error)

ExecuteMultiAccountTransferWithHelper performs a transfer with multiple source and/or destination accounts

Parameters:

• ctx: The context for the operation, which can be used for cancellation
• entity: The initialized Midaz SDK entity client
• orgID: The ID of the organization
• ledgerID: The ID of the ledger
• sourceAccounts: Map of source account IDs to their amounts (as decimal strings)
• destAccounts: Map of destination account IDs to their amounts (as decimal strings)
• totalAmount: The total amount of the transaction (as decimal string)
• assetCode: The asset code for the transfer

Returns:

• *models.Transaction: The created transaction
• error: Any error encountered during the operation

func ExecuteTransferWithHelper ¶

func ExecuteTransferWithHelper(
	ctx context.Context,
	midazClient *client.Client,
	orgID, ledgerID string,
	sourceAccountID, destAccountID string,
	amount string,
	assetCode string,
) (*models.Transaction, error)

ExecuteTransferWithHelper transfers funds from one account to another using the transaction helpers

Parameters:

• ctx: The context for the operation, which can be used for cancellation
• entity: The initialized Midaz SDK entity client
• orgID: The ID of the organization
• ledgerID: The ledger ID
• sourceAccountID: The source account ID
• destAccountID: The destination account ID
• amount: The amount to transfer (as decimal string)
• assetCode: The asset code for the transfer

Returns:

• *models.Transaction: The created transaction
• error: Any error encountered during the operation

func ExecuteWithdrawalWithHelper ¶

func ExecuteWithdrawalWithHelper(
	ctx context.Context,
	midazClient *client.Client,
	orgID, ledgerID string,
	accountID string,
	amount string,
	assetCode string,
) (*models.Transaction, error)

ExecuteWithdrawalWithHelper withdraws funds from an account to an external destination

Parameters:

• ctx: The context for the operation, which can be used for cancellation
• entity: The initialized Midaz SDK entity client
• orgID: The ID of the organization
• ledgerID: The ID of the ledger
• accountID: The source account ID
• amount: The amount to withdraw (as decimal string)
• assetCode: The asset code for the withdrawal

Returns:

• *models.Transaction: The created transaction
• error: Any error encountered during the operation

func GetOrganization ¶

func GetOrganization(
	ctx context.Context,
	orgID string,
	service entities.OrganizationsService,
) (*models.Organization, error)

GetOrganization retrieves an organization by its ID.

This function demonstrates how to retrieve an organization's details using its unique identifier. It shows proper error handling and service interaction.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID to retrieve. Must be a valid UUID.
• service: The OrganizationsService instance to use for the API call.

Returns:

• *models.Organization: The retrieved organization if successful.
• error: Any error encountered during the retrieval operation.

Example:

org, err := entities.GetOrganization(
    ctx,
    "org-123",
    sdkEntity.Organizations,
)

func ListAccounts ¶

func ListAccounts(
	ctx context.Context,
	orgID, ledgerID string,
	service entities.AccountsService,
) ([]*models.Account, error)

ListAccounts lists all accounts for a ledger.

This function retrieves all accounts in the specified ledger and returns them as a slice of account pointers for easier manipulation. It handles pagination internally and converts the API response to a more convenient format.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID to list accounts from. Must be a valid UUID.
• service: The AccountsService instance to use for the API call.

Returns:

• []*models.Account: A slice of account pointers if successful.
• error: Any error encountered during the listing operation.

Example:

accounts, err := entities.ListAccounts(
    ctx,
    "org-123",
    "ledger-456",
    sdkEntity.Accounts,
)

func ListOperationRoutes ¶

func ListOperationRoutes(
	ctx context.Context,
	orgID, ledgerID string,
	service entities.OperationRoutesService,
) ([]*models.OperationRoute, error)

ListOperationRoutes lists all operation routes for a ledger with consistent pattern.

This function retrieves all operation routes from the specified ledger and converts the response to a slice of pointers for easier manipulation in workflow examples.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID to query for operation routes. Must be a valid UUID.
• service: The OperationRoutesService instance to use for the API call.

Returns:

• []*models.OperationRoute: A slice of pointers to operation routes.
• error: Any error encountered during the list operation.

Example:

operationRoutes, err := entities.ListOperationRoutes(
    ctx,
    "org-123",
    "ledger-456",
    sdkEntity.OperationRoutes,
)

func ListTransactionRoutes ¶

func ListTransactionRoutes(
	ctx context.Context,
	orgID, ledgerID string,
	service entities.TransactionRoutesService,
) ([]*models.TransactionRoute, error)

ListTransactionRoutes lists all transaction routes for a ledger with consistent pattern.

This function retrieves all transaction routes from the specified ledger and converts the response to a slice of pointers for easier manipulation in workflow examples.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID to query for transaction routes. Must be a valid UUID.
• service: The TransactionRoutesService instance to use for the API call.

Returns:

• []*models.TransactionRoute: A slice of pointers to transaction routes.
• error: Any error encountered during the list operation.

Example:

transactionRoutes, err := entities.ListTransactionRoutes(
    ctx,
    "org-123",
    "ledger-456",
    sdkEntity.TransactionRoutes,
)

func TransferFunds ¶

func TransferFunds(
	ctx context.Context,
	entity *entities.Entity,
	orgID,
	ledgerID,
	sourceAccountID,
	destAccountID,
	assetCode string,
	amount string,
	description string,
) (*models.Transaction, error)

TransferFunds transfers funds between two accounts within a ledger.

This function simplifies the process of creating a transaction that transfers funds from one account to another. It handles the complexities of working with account aliases and external accounts, and constructs the appropriate transaction input structure expected by the Midaz API.

The function supports both internal and external source accounts. For external accounts, use the format "@external/ASSET_CODE" as the sourceAccountID. For internal accounts, you can use either the account ID or alias.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• entity: The Entity instance containing all service references.
• orgID: The organization ID that owns the ledger. Must be a valid UUID.
• ledgerID: The ledger ID where the accounts exist. Must be a valid UUID.
• sourceAccountID: The source account ID or alias, or "@external/ASSET_CODE" for external accounts.
• destAccountID: The destination account ID or alias.
• assetCode: The asset code for the transfer (e.g., "USD", "EUR").
• amount: The amount to transfer, expressed as an integer.
• scale: The scale factor for the amount (e.g., 2 for cents, making amount 100 = $1.00).
• description: A human-readable description of the transaction.

Returns:

• *models.Transaction: The created transaction if successful.
• error: Any error encountered during the transaction creation.

Example:

transaction, err := entities.TransferFunds(
    ctx,
    sdkEntity,
    "org-123",
    "ledger-456",
    "account-789",
    "account-012",
    "USD",
    1000,
    2,
    "Payment for services",
)

func UpdateOrganization ¶

func UpdateOrganization(
	ctx context.Context,
	orgID, newName string,
	service entities.OrganizationsService,
) (*models.Organization, error)

UpdateOrganization updates an existing organization.

This function demonstrates how to update an organization's properties, specifically focusing on updating the legal name and metadata. It shows proper error handling and validation practices.

Parameters:

• ctx: Context for the request, which can be used for cancellation and timeout.
• orgID: The organization ID to update. Must be a valid UUID.
• newName: The new legal name for the organization.
• service: The OrganizationsService instance to use for the API call.

Returns:

• *models.Organization: The updated organization if successful.
• error: Any error encountered during the update operation.

Example:

updatedOrg, err := entities.UpdateOrganization(
    ctx,
    "org-123",
    "New Company Name",
    sdkEntity.Organizations,
)