Close-ended subscription orders involve a predetermined number of shares or units, with a fixed price per share or unit. Investors can subscribe to the fund during the initial offering, and afterward, trade the shares on a secondary market. Close-ended funds are relatively easy to manage, as the fund manager can plan and allocate resources based on the number of shares issued.

This document provides a comprehensive guide for API integrators on how to manage close-ended subscription orders using our API. The guide covers the complete lifecycle of a subscription order from retrieval to minting or refunding. For more information on managing open-ended subscription orders, please refer to the article: Agent: Managing Open-Ended Subscription Orders.

📘

Prerequisites:

To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

• Make sure to leverage an existing account, e.g. Agent, Owner, etc.
• Sign into your Servicing portal to disable your 2FA.
• Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.
• Add the JWT to the header of your request.

Order Status Flow

The following are possible status transitions for a redemption order:

• INITIATED: The initial state when an order is created but no payment has been initiated.
• PENDING_PAYMENT: The investor has committed to the order, and payment is awaited.
• CANCELED: The order has been canceled by the issuer or the investor before minting.
• CONFIRMED: Payment has been received and confirmed for the order.
• MINTED: Tokens have been successfully minted and assigned to the investor.
• REFUNDED: The payment has been confirmed, but subsequently refunded.

Complete Mint tokens Workflow

 Step 1: Retrieve Investor Orders for a Given Subscription

This endpoint allows you to retrieve all investor orders associated with a specific subscription.

GET /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders

Step 2: Create a Close-Ended Subscription Order

This endpoint allows you to create a new subscription order for a close-ended subscription. Set order to INITIATED status.

POST /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders

Step 3: Confirm Creation of Order on Behalf of an Investor

This endpoint allows you to confirm an order on behalf of an investor, changing its status to PENDING_PAYMENT.

This confirmation step is necessary because, after order creation, the order is initially in a draft state. There may be intermediate steps (such as agreement signing) before the order is ready for payment. As a result, the system does not automatically move the order to PENDING_PAYMENT, you must explicitly call this endpoint to confirm that the investor is ready to proceed.

Note: The orderId used in this step is returned in the response of the previous step, when the order is initially created.

POST /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders/{orderId}/pending-payment

Step 4: Confirm Payment Reception of Orders

Use this endpoint when you need to confirm one or multiple orders simultaneously, typically after a batch payment processing operation has completed successfully.

This endpoint should be used when:

• You need to confirm multiple orders at once for efficiency.
• All orders are in PendingPayment status.
• You have verified that payment has been received for each of the included orders.

POST /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders/confirm

Step 5: Process Confirmed Orders (Mint or Refund)

After orders reach the CONFIRMED status, they must be either minted (tokens issued to investors) or refunded (payment returned). This step presents two mutually exclusive options for processing confirmed orders.

Option A: Mint Orders

Use this endpoint when you want to issue tokens to investors with confirmed orders. This is the final step in a successful subscription process.

Minting is only available when:

• Orders are in CONFIRMED status
• The subscription has reached its minimum cap
• You have appropriate permissions to manage the token and orders

POST /api/subscriptions/{subscriptionId}/orders/actions/mint

Option B: Refund Order

Use this endpoint when you need to return funds to investors for confirmed orders, typically due to subscription cancellation, oversubscription, or other business reasons.

Refunding is only available when:

• Orders are in CONFIRMED status
• You have appropriate permissions to manage the token and orders

POST /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders/refund

 Step 6: Sign and Broadcast the Mint Transaction

Refer to the guide based on the specific sign and broadcast solution your API integration requires by visiting the following link: Blockchain signature flow.

This endpoint includes a taskId that is returned in the response from the mint endpoint while the Sign and Broadcast yourself step is not necessary for Refund Orders. You should include this same taskId when calling the transaction logging endpoint.

Logging the transaction is essential to reconcile on-chain and off-chain flows. Since the user handles blockchain interactions on their own, we use the taskId to:

• Identify the workflow uniquely.
• Maintain a consistent link between off-chain logic and on-chain activity.
• Ensure traceability and reliability in our subscription/order system.

Steps to Complete the Mint:

• Sign the transaction payload with your private key
• Broadcast, on your end, the signed transaction to the blockchain
• Log the transaction hash:

POST /api/subscriptions/{subscriptionId}/orders/actions/{subscriptionOrdersActionId}/transactions

With Payload:

{
  "taskId": "<task_id>",
  "txHash": "<transaction_hash>"
}

Cancellation Flow

This section provides a detailed step-by-step guide for Agents to cancel subscription orders at different stages in their lifecycle. Investors can also cancel orders when they are in PENDING_PAYMENT status.

 Step 1: Determine Order Eligibility for Cancellation

Before proceeding with cancellation, verify that the order is in a cancellable state:

• Orders in INITIATED status: Cannot be cancelled (must be pending payment instead).
• Orders in PENDING_PAYMENT status: Can be cancelled.
• Orders in CONFIRMED status: Cannot be cancelled (must be refunded instead).
• Orders in MINTED or REFUNDED status: Cannot be cancelled.

 Step 2: Retrieve Current Order Information

Use this endpoint to fetch the current order details to confirm its status:

GET /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders/{orderId}

Or use this endpoint to retrieve multiple orders at once:

GET /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders

Step 3: Cancel One or Multiple Orders

Use this endpoint and decide whether to cancel a single order or multiple orders based on your requirements:

POST /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders/cancel

Request body:

{
  "orderIds": ["orderId1", "orderId2", "orderId3"]
}

 Step 4: Verify Cancellation Result

Use this endpoint after sending the cancellation request, verify that the orders have been successfully canceled:

GET /api/subscriptions/{subscriptionId}/tokens/{tokenId}/investor-orders/{orderId}

The response should show the order status as CANCELED.