📈 Mutual Funds – Integration Guide

Introduction

The Mutual Funds (FCI) module allows you to offer your users the ability to invest, query, and manage Adcap Asset Management funds directly from your platform, without having to build the operational infrastructure from scratch.

Through API Broker's APIs, your team can integrate in a single connection: the list of available funds, real-time net asset values, subscription and redemption operations, and the portfolio query for each user. The integration is 100% via API and webhooks, and API Broker's support team accompanies the entire process, from development to go-live.

Intended for product, technology, and business teams who want to incorporate mutual funds as a feature within their app, wallet, or financial platform.

Module Features

Available funds query

Complete list of funds with their characteristics: name, type (Fixed Income, Money Market, etc.), currency, strategy, and investment horizon.

Prices and net asset values (NAV)

Real-time or end-of-day values. Also allows retrieving historical data to display performance or calculate annualized rates.

Subscriptions

Your users can invest in a fund by submitting a request from their brokerage account. The operation is executed using the available balance or, in certain cases, from a bank account.

Redemptions

Allows requesting total or partial redemptions of a fund. The order status can be queried in real time or received via webhook.

Portfolio query

Your users can view which funds they are subscribed to, the number of shares, and the current valuation of their portfolio.

Placement Methods: ACDI and SIMPLE

To understand how the module operates, it is key to distinguish the two available placement methods. The method determines who executes the subscription and from/to where the funds move.

ACDI Method

Under this scheme, Adcap Securities acts as an Integral Placement and Distribution Agent (ACDI) and subscribes to the fund on behalf of the account holders. This is the standard method for individuals.

• Subscriptions: funds are deducted from the available balance in the user's brokerage account.
• Redemptions: funds are credited to the user's brokerage account.
• Direct bank transfers are not allowed under this method.
• Does not require a shareholder number from the fund manager.

SIMPLE Method

The account holder subscribes directly to the fund, without ACDI intermediation. This is the method used for legal entities.

• Subscriptions: can be made from the brokerage account balance or via a bank transfer from a same-name account of the user.
• Redemptions: funds can be credited to the brokerage account or transferred to a same-name bank account.
• Requires the user to have a shareholder number assigned by the fund manager.

General rule: individuals operate via ACDI; legal entities operate via SIMPLE. For accounts that have a shareholder number, both methods are optional in the request. If method_type is not provided, API Broker assigns the default method according to operational rules.

Integration Flow

a. User and Account Onboarding

Onboarding is a prerequisite for operating mutual funds. The user must have an active brokerage account before they can subscribe to or redeem funds.

Expected result: person_id, investment_account_id, bank_account_id.

Important: for legal entities, the system automatically generates a shareholder account in addition to the brokerage account. This enables the SIMPLE method.

API Broker notifies asynchronously when the brokerage account and/or the shareholder account have been created:

• Webhook: investment_account_update

b. Fund Deposit (Cash In)

The user transfers funds to an Adcap Securities collection account (CBU available in ARS and USD). Through the banking integration, API Broker identifies the deposit and credits the balance to the brokerage account.

API Broker notifies the partner with the details of the received transfer:

• Webhook: deposit_create
• Includes: investment_account_id, currency, amount, and credit date.

{
  "topic": "deposit_create",
  "items": [{
    "investment_account_id": 43101,
    "currency_id": "ARS",
    "amount": 10.0,
    "trade_date": "2024-09-03",
    "status_id": "COMPLETED",
    "deposit_id": 631184,
    "tax_identification_value": "20415653825"
  }]
}

c. Fund and Price Query

Before subscribing, the user can explore the available funds and their current values.

d. Subscriptions

The user selects a fund and instructs the subscription:

POST /market/fund-requests

Required fields:

{
  "investment_account_id": 12345,
  "mutual_fund_id": 10,
  "fund_operation_type": "subscription",
  "currency_id": "ARS",
  "amount": 150000,
  "external_id": "client-op-0001"
}

Optional fields (for accounts with a shareholder number):

e. Redemptions

Same endpoint as subscription, changing the operation type:

POST /market/fund-requests
fund_operation_type = "redemption"

The redemption can be instructed by amount (amount) or by number of shares (share_quantity). To redeem by shares, send "by_share_quantity": true.

Use cases by method:

Default logic when the account has a shareholder number:

f. Request Status Query

Beyond webhooks, it is possible to query the status and details of a mutual fund request at any time directly by its request_id.

GET /market/fund-requests/{request_id}

Possible responses:

When to use it: this endpoint is useful for reconciliation, user support, or when the webhook was not received correctly. It allows verifying the exact status of the operation at any time.

g. Tickets / Settlement Confirmations Query

Once a subscription or redemption request has been processed, the fund manager generates a ticket (settlement confirmation). These tickets can be queried to obtain the operational details of the settlement: shares, price, settlement date, and amounts.

GET /markets/mutual-fund-confirmations

Recommended query parameters:

Use cases: show the user their operation receipt, perform accounting reconciliation, or verify the price and number of settled shares. Tickets are available once the operation reaches SETTLED status.

h. Account Statement Query

Allows obtaining the complete account statement of a brokerage account: monetary position (available balances) and fund holdings.

GET /portfolio/account-statements/{investment_account_id}

Path parameters:

Optional query parameters:

Responses:

When to use it: to show the user their available balance before subscribing, or to display the details of their mutual fund portfolio with updated valuation.

i. Withdrawal (Cash Out)

Once the redemption has been settled (status = SETTLED), the partner can instruct the withdrawal of funds to a user's bank account.

POST /withdraw-requests

Withdrawals are asynchronous. API Broker notifies status changes via webhook:

• Webhook: withdraw_request_update
• States: IN_PROGRESS → COMPLETED / REJECTED

{
  "topic": "withdraw_request_update",
  "items": [{
    "amount": 100,
    "status_id": "COMPLETED",
    "currency_id": "ARS",
    "bank_account_id": 121535,
    "withdraw_request_id": 984479,
    "investment_account_id": 74659
  }]
}

Main Endpoints

Webhooks to Implement

Your platform must expose a URL to receive the following events:

deposit_create

Triggered when API Broker credits a deposit to a user's brokerage account. Includes investment_account_id, currency, amount, and credit date.

investment_account_update

Triggered when the brokerage account and/or the shareholder account are created in the broker-dealer or the fund management company. Allows knowing when the user is enabled to operate.

withdraw_request_update

Triggered on each status change of a withdrawal. Includes the updated status (IN_PROGRESS, COMPLETED, REJECTED), amount, and destination account.

Key Points to Remember

1. Onboarding is a prerequisite: the user needs an active investment_account_id to operate mutual funds.
2. Legal entities automatically get a shareholder account: this enables the SIMPLE method and operations to/from a bank account.
3. ACDI and SIMPLE are not freely interchangeable: if the user does not have a shareholder number, they can only operate via ACDI.
4. method_type is optional but important: if not provided, API Broker assigns the default according to operational rules. Understanding those rules avoids unexpected behavior.
5. bank_account_id only works with SIMPLE: it is not compatible with the ACDI method.
6. Withdrawals require settled funds: a withdrawal cannot be instructed until the redemption has status = SETTLED.
7. Webhooks are mandatory: deposit_create and withdraw_request_update are critical events in the flow. Your platform must have a URL available to receive them.
8. external_id prevents duplicates: always send a unique identifier per operation to avoid double processing.