Capital - Nuvion

Capital lets an entity invest idle balances in Fixed Return or Share Offering products. An order holds an immutable quote for 15 minutes; confirming it debits the entity’s funding account and creates the capital account, which is tracked through accrual to payout. All monetary values are in the smallest currency unit.

The Capital Product object

string

The ULID of the capital product.

string

The product type. One of FIXED_RETURN, SHARE_OFFERING.

boolean

Whether the product is managed by an external partner rather than Nuvion directly.

string

The display name of the product.

string

Description of what the product offers, as HTML.

string

ISO 4217 currency code. The funding account used to order must match this currency.

number

Unix-ms start of the sale window. null when not configured.

number

Unix-ms end of the sale window. null when not configured.

object

Commercial terms for the product. Detail responses additionally include documents; list responses never do.

Show config fields

object

The accepted investment sizes: min, max, and a bands array of { name, value } exact-value bands.

object

Fixed Return only. tenor_days is one of 7, 30, 60, 90, 180. earliest_withdrawal_days is the number of days before an early withdrawal may be requested.

object

interest.primary is the annual decimal rate, e.g. 0.18 for 18%. interest.bands carries principal-tiered rates. deductibles lists each { name, value, value_type, applicable_to }, where value_type is flat or percentage and applicable_to is principal or interest. Fixed Return exposes interest rates and deductibles; Share Offering exposes deductibles only.

object

Fixed Return only. orders.liquidation.allow_early_withdrawal states explicitly whether early withdrawal is permitted on this product.

Share Offering only. issuer_name, offer_price (whole-share price in minor units), lock_period_days (180 or greater), and prospectus_url.

array

Detail responses only. Each document carries name and url. Every document must be affirmed when creating an order.

object

Present only for SHARE_OFFERING. status is available or sold_out; quantity is the current sellable inventory in whole shares.

Example Capital Product Object

{
  "id": "01HXYZ0085ABCDEFGHJKMNPQRS",
  "capital_product_type": "FIXED_RETURN",
  "name": "Nuvion Fixed Return 90",
  "description": "Earn a locked-in return over 90 days.",
  "currency": "NGN",
  "start_date": 1784419200000,
  "end_date": 1795737600000,
  "config": {
    "principal": {
      "min": 10000000,
      "max": 500000000,
      "bands": []
    },
    "tenor": {
      "tenor_days": 90,
      "earliest_withdrawal_days": 30
    },
    "rates": {
      "interest": {
        "primary": 0.16,
        "bands": [
          {
            "name": "Tier 1",
            "rate": 0.16,
            "min_principal_amount": 10000000,
            "max_principal_amount": 49999999
          },
          {
            "name": "Tier 2",
            "rate": 0.18,
            "min_principal_amount": 50000000,
            "max_principal_amount": 500000000
          }
        ]
      },
      "deductibles": [
        {
          "name": "Withholding Tax",
          "value": 0.1,
          "value_type": "percentage",
          "applicable_to": "interest"
        },
        {
          "name": "Early Withdrawal Penalty",
          "value": 0.25,
          "value_type": "percentage",
          "applicable_to": "interest"
        }
      ]
    },
    "orders": {
      "liquidation": {
        "allow_early_withdrawal": true
      }
    }
  }
}

Capital product types

Type	Description
`FIXED_RETURN`	A fixed principal at a rate locked in at purchase, over a set tenor. Interest accrues daily
`SHARE_OFFERING`	Whole shares bought at a fixed offer price and held for a lock period before becoming transferable

Day count conventions

Currency	Day count
`NGN`	365
`USD`, `GBP`, `EUR`, `CAD`	360

The Capital Order object

string

The ULID of the product order.

string

The ID of the entity that placed the order.

string

The order reference. Distinct from id.

string

The ULID of the capital product ordered.

string

The ULID of the funding wallet account debited for this order. Matches the account_id submitted at creation.

string

One of FIXED_RETURN, SHARE_OFFERING.

string

ISO 4217 currency code.

number

The reserved debit amount. The principal for Fixed Return; total_debit for Share Offering.

number

Share Offering reserved shares. null for Fixed Return.

string

One of RESERVED, CONFIRMING, APPROVED, EXPIRED, REJECTED, RECOVERY_REQUIRED.

string

A human-readable reason accompanying the current status.

number

Unix-ms reservation expiry, 15 minutes from creation.

number

Unix-ms confirmation timestamp.

number

Unix-ms rejection timestamp.

number

Unix-ms expiry timestamp.

object

A summary of the capital account created by the order. null until the order is approved.

array

Detail responses only. Each entry pairs the document with the requesting entity’s affirmations, each carrying action_type and actioned_at. Only the requesting entity’s affirmations are exposed.

Capital order statuses

Status	Terminal	Description
`RESERVED`	No	Quote reserved, awaiting confirmation. Expires after 15 minutes
`CONFIRMING`	No	Confirmation in progress; the funding wallet debit is being applied
`APPROVED`	Yes	Debit settled and the capital account created
`EXPIRED`	Yes	The reservation expired before it was confirmed
`REJECTED`	Yes	Confirmation failed eligibility, product, or sale window re-checks
`RECOVERY_REQUIRED`	No	The debit succeeded but post-debit persistence failed. Under review

The Capital Account object

The capital account is created on confirmation and holds the immutable terms of the investment.

string

The ULID of the capital account.

string

The ULID of the order that created the account.

string

The ULID of the capital product this account was opened against.

string

One of FIXED_RETURN, SHARE_OFFERING.

string

ISO 4217 currency code.

string

The account number issued for this capital holding.

number

Fixed Return only. The invested principal in minor units.

number

Fixed Return only. The annual decimal rate locked at purchase.

number

Fixed Return only. 365 or 360, resolved from the currency.

number

Fixed Return only. One of 7, 30, 60, 90, 180.

number

Fixed Return only. The Unix-ms confirmation timestamp from which interest accrues.

number

Fixed Return only. The business-day maturity in UTC. A contractual end falling on a Saturday or Sunday shifts to the following Monday.

number

Fixed Return only. The earliest Unix-ms at which an early withdrawal may be requested. null when the investment is locked or early withdrawal is disabled.

number

Fixed Return only. Computed on read from the account terms and the elapsed days, bounded by the tenor. It is not a stored balance.

number

Fixed Return only. The projected net interest at maturity: gross_interest minus total_deductions. Fixed at confirmation; does not reflect elapsed time. See accrued_interest for the current accrued amount.

number

Fixed Return only. The projected payout at maturity: principal plus due_interest.

number

Fixed Return only. Interest-based deductibles, such as withholding tax, projected at maturity.

number

Fixed Return only. The projected total interest at maturity, before deductibles. Fixed at confirmation; does not reflect elapsed time.

number

Fixed Return only. principal plus gross_interest, before deductibles.

number

Fixed Return only. null until a payout is initiated. Persisted by the withdrawal action and used by the settlement workers.

number

Fixed Return only. Unix-ms date the payout is scheduled to settle. null until settlement is scheduled, which can be after the payout is initiated.

number

Share Offering only. The originally allocated quantity. Never rewritten by allotment adjustments.

number

Share Offering only. Adjusted by allotment; initially equal to shares_purchased.

number

Share Offering only. allocated_shares multiplied by offer_price.

number

Share Offering only. The brokerage fee charged at purchase.

number

Share Offering only. The cross-deal fee charged at purchase.

number

Share Offering only. The full amount debited from the funding wallet.

number

Share Offering only. The immutable lock expiry computed from the confirmed purchase date.

number

Share Offering only. The cost basis of the units held.

number

Share Offering only. The cost basis divided by the units held.

number

Share Offering only. null rather than zero before a valid price update exists.

number

Share Offering only. The unallocated value awaiting refund.

object

status carries the account state. payout_status (or refund_status for Share Offering) is one of pending, completed, failed and is present once a payout exists.

Capital account lifecycle statuses

Fixed Return:

Status	Terminal	Description
`ACTIVE`	No	Accruing interest daily, before maturity
`MATURED`	No	Tenor complete and awaiting the maturity payout
`EARLY_LIQUIDATING`	No	Early withdrawal initiated; payout being settled
`WITHDRAWN`	Yes	Early liquidation payout settled
`CLOSING`	No	Maturity payout initiated; payment being settled
`CLOSED`	Yes	Maturity payout settled and the account closed

Share Offering:

Status	Terminal	Description
`LOCKED`	No	Shares held within the lock period
`ALLOTMENT_ADJUSTED`	No	Units held adjusted by the issuer’s allotment
`ALLOTMENT_CONFIRMED`	No	All units requested were allotted by the issuer
`TRANSFERABLE`	No	Lock period expired; units are transferable
`REFUNDED`	Yes	Unallocated value refunded to the funding wallet

The Capital Transaction object

string

The ULID of the capital transaction.

string

The ID of the entity that owns the capital transaction.

string

The event the transaction records. See the table below.

number

The amount in minor units. Its meaning depends on event_type.

number

Unix-ms accrual date. Present only on DAILY_ACCRUAL events.

number

The amount funded through an investment vehicle, in minor units. null when not applicable.

number

The placement fee charged for this transaction, in minor units. null when not applicable.

number

Expenses charged by the investment vehicle for this transaction, in minor units. null when not applicable.

number

Unix-ms event creation timestamp.

Capital transaction event types

Event type	Description
`PURCHASE`	The confirmed debit that opened the capital account
`DAILY_ACCRUAL`	A day’s interest accrued on a Fixed Return account
`EARLY_WITHDRAWAL_PENALTY`	The penalty applied to accrued interest on early exit
`WITHHOLDING_TAX`	Tax withheld from interest
`WITHDRAWAL`	The instruction that initiates a payout
`MATURITY_PAYOUT`	The payout raised at maturity
`MATURITY_SETTLEMENT`	The settlement of the maturity payout
`EARLY_LIQUIDATION_PAYOUT`	The payout raised on early liquidation
`ALLOTMENT_ADJUSTED`	Units held adjusted by the issuer’s allotment
`REFUND`	Unallocated value returned to the funding wallet
`LOCK_EXPIRY`	The share lock period ended
`PRICE_UPDATE`	A market price update applied to the holding
`DIVIDEND_ACCRUED`	A dividend accrued on the holding
`DIVIDEND_DISTRIBUTED`	An accrued dividend paid out

Retrieve capital products

GET /products Lists the capital products visible to the authenticated entity. Hidden products, ineligible products, products whose owner is inactive, and share offerings with zero inventory are excluded. Sold-out share offerings are returned as not orderable.

Query parameters

string

Filter by product type. One of FIXED_RETURN, SHARE_OFFERING.

string

Filter by ISO 4217 currency code.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

number

Page size. Between 1 and 100. Defaults to 25.

string

Next-page cursor.

string

Previous-page cursor. Mutually exclusive with cursor.

curl "https://api.nuvion.dev/products?capital_product_type=FIXED_RETURN&currency=NGN&limit=25" \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital products retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ0080ABCDEFGHJKMNPQRS",
        "capital_product_type": "FIXED_RETURN",
        "is_external": false,
        "name": "Nuvion Prime 30",
        "description": "<p><strong>Nuvion Prime 30</strong> is a short-term, fixed-income deposit product for clients seeking high-yield returns with minimal lock-in duration.</p>",
        "currency": "NGN",
        "start_date": null,
        "end_date": null,
        "config": {
          "principal": {
            "min": 10000000,
            "max": 500000000,
            "bands": []
          },
          "tenor": {
            "tenor_days": 30,
            "earliest_withdrawal_days": 30
          },
          "rates": {
            "interest": {
              "primary": 0.12,
              "bands": [
                {
                  "name": "Tier 2",
                  "rate": 0.18,
                  "min_principal_amount": 50000000,
                  "max_principal_amount": 500000000
                }
              ]
            },
            "deductibles": [
              {
                "name": "Withholding Tax",
                "value": 0.1,
                "value_type": "percentage",
                "applicable_to": "interest"
              }
            ]
          },
          "orders": {
            "liquidation": {
              "allow_early_withdrawal": true
            }
          }
        }
      },
      {
        "id": "01HXYZ0081ABCDEFGHJKMNPQRS",
        "capital_product_type": "SHARE_OFFERING",
        "is_external": false,
        "name": "Meridian Holdings Series A",
        "description": "<p>Private placement in Meridian Holdings Plc.</p>",
        "currency": "USD",
        "start_date": 1786752000000,
        "end_date": 1789344000000,
        "config": {
          "principal": {
            "min": 100000,
            "bands": []
          },
          "rates": {
            "deductibles": [
              {
                "name": "Brokerage Fee",
                "value": 0.015,
                "value_type": "percentage",
                "applicable_to": "principal"
              },
              {
                "name": "Cross-Deal Fee",
                "value": 0.005,
                "value_type": "percentage",
                "applicable_to": "principal"
              }
            ]
          },
          "share_offering": {
            "issuer_name": "Meridian Holdings Plc",
            "offer_price": 25000,
            "lock_period_days": 180,
            "prospectus_url": "https://cdn.nuvion.dev/capital/meridian-prospectus.pdf"
          }
        },
        "availability": {
          "status": "available",
          "quantity": 12500
        }
      }
    ],
    "meta": {
      "pagination": {
        "order": "asc",
        "has_next": true,
        "limit": 25,
        "has_previous": false,
        "next_cursor": "01HXYZ0081ABCDEFGHJKMNPQRS",
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "created",
          "order": "desc"
        }
      }
    }
  }
}

Product documents are never included in list responses. Call GET /products/{id} to retrieve the documents to affirm before ordering.

Retrieve a capital product

GET /products/{id} Retrieves the detail view of a single capital product, including its displayable documents.

Path parameters

string

required

The ULID of the capital product.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl https://api.nuvion.dev/products/01HXYZ0080ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital product retrieved successfully",
  "data": {
    "id": "01HXYZ0080ABCDEFGHJKMNPQRS",
    "capital_product_type": "FIXED_RETURN",
    "is_external": false,
    "name": "Nuvion Prime 30",
    "description": "<p><strong>Nuvion Prime 30</strong> is a short-term, fixed-income deposit product for clients seeking high-yield returns with minimal lock-in duration.</p>",
    "currency": "NGN",
    "start_date": null,
    "end_date": null,
    "config": {
      "principal": {
        "min": 10000000,
        "max": 500000000,
        "bands": []
      },
      "documents": [
        {
          "name": "Fixed Return Terms and Conditions.pdf",
          "url": "https://cdn.nuvion.dev/capital/fixed-return-terms.pdf"
        }
      ],
      "tenor": {
        "tenor_days": 30,
        "earliest_withdrawal_days": 30
      },
      "rates": {
        "interest": {
          "primary": 0.12,
          "bands": [
            {
              "name": "Tier 2",
              "rate": 0.18,
              "min_principal_amount": 50000000,
              "max_principal_amount": 500000000
            }
          ]
        },
        "deductibles": [
          {
            "name": "Withholding Tax",
            "value": 0.1,
            "value_type": "percentage",
            "applicable_to": "interest"
          },
          {
            "name": "Early Withdrawal Penalty",
            "value": 0.25,
            "value_type": "percentage",
            "applicable_to": "interest"
          }
        ]
      },
      "orders": {
        "liquidation": {
          "allow_early_withdrawal": true
        }
      }
    }
  }
}

A 404 is returned rather than disclosing existence when the product is inactive, ineligible, misconfigured, or holds an unsupported Share Offering quantity.

Create a capital order

POST /product-orders Creates a 15-minute reservation holding an immutable commercial quote and the entity’s agreement evidence. No funds move. The product type is resolved from product_id and determines whether principal or amount is permitted. Share Offering inventory is conditionally reserved in the same transaction; where inventory is insufficient the order is allocated down to the remaining shares and the adjusted quote must be confirmed.

Request parameters

string

required

The ULID of the capital product being ordered.

string

required

The ULID of the funding wallet account to debit. Must match the product currency.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

number

Required for FIXED_RETURN, rejected for SHARE_OFFERING. Positive minor units. Must match an exact configured band, or fall within the configured minimum and maximum.

boolean

Required for FIXED_RETURN, rejected for SHARE_OFFERING. Set to true to waive early withdrawal for the full tenor. Write-once; it cannot be changed after the order is created.

number

Required for SHARE_OFFERING, rejected for FIXED_RETURN. The desired spend in minor units, from which whole shares are derived.

array

required

One affirmation per configured product document. Unknown, duplicate, stale, or missing entries are rejected.

Show agreement_acceptances fields

string

required

Must match a configured product document name.

string

required

affirmation. Click-through affirmation is the only supported action type.

curl -X POST https://api.nuvion.dev/product-orders \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
    "principal": 50000000,
    "lock_investment": false,
    "agreement_acceptances": [
      {
        "document_name": "Fixed Return Terms and Conditions",
        "action_type": "affirmation"
      }
    ]
  }'

curl -X POST https://api.nuvion.dev/product-orders \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "01HXYZ0081ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ0109ABCDEFGHJKMNPQRS",
    "amount": 10060000,
    "agreement_acceptances": [
      {
        "document_name": "Offer Prospectus",
        "action_type": "affirmation"
      }
    ]
  }'

Response

{
  "status": "success",
  "message": "Capital order reserved successfully",
  "data": {
    "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "status": "RESERVED",
    "expires_at": 1787098500000,
    "currency": "NGN",
    "quote": {
      "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
      "product_owner_id": "01HXYZ0087ABCDEFGHJKMNPQRS",
      "product_type": "FIXED_RETURN",
      "currency": "NGN",
      "principal": 50000000,
      "total_debit": 50000000,
      "tenor_days": 90,
      "locked_rate": 0.18,
      "rate_source": "band:Tier 2",
      "day_count": 365,
      "is_locked": false,
      "allow_early_withdrawal": true,
      "earliest_withdrawal_days": 30,
      "penalty": {
        "primary": 0.25
      },
      "deductibles": [
        {
          "name": "Withholding Tax",
          "value": 0.1,
          "value_type": "percentage",
          "applicable_to": "interest"
        }
      ]
    }
  }
}

{
  "status": "success",
  "message": "Capital order reserved successfully",
  "data": {
    "id": "01HXYZ0108ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "status": "RESERVED",
    "expires_at": 1787098500000,
    "currency": "USD",
    "quote": {
      "product_id": "01HXYZ0081ABCDEFGHJKMNPQRS",
      "product_owner_id": "01HXYZ0087ABCDEFGHJKMNPQRS",
      "product_type": "SHARE_OFFERING",
      "currency": "USD",
      "requested_amount": 10060000,
      "requested_shares": 402,
      "allocated_shares": 402,
      "unallocated_amount": 10000,
      "offer_price": 25000,
      "base_cost": 10050000,
      "brokerage_fee": 150750,
      "cross_deal_fee": 50250,
      "total_debit": 10251000,
      "deductibles": [
        {
          "name": "Brokerage Fee",
          "value": 0.015,
          "value_type": "percentage",
          "applicable_to": "principal",
          "amount": 150750
        },
        {
          "name": "Cross-Deal Fee",
          "value": 0.005,
          "value_type": "percentage",
          "applicable_to": "principal",
          "amount": 50250
        }
      ],
      "lock_period_days": 180
    }
  }
}

Where the requested shares exceed the remaining inventory, allocated_shares and total_debit reflect the adjusted amounts.

Confirm a capital order

POST /product-orders/{id}/confirm Confirms an unexpired reservation. Eligibility, product and owner status, and the sale window are re-evaluated before any debit; the stored quote is authoritative. Nuvion debits the funding wallet once using a deterministic transfer reference, then creates the approved capital account and a PURCHASE capital transaction.

Path parameters

string

required

The ULID of the capital order to confirm.

Request parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl -X POST https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS/confirm \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital order confirmed successfully",
  "data": {
    "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "status": "APPROVED",
    "capital_account_id": "01HXYZ0089ABCDEFGHJKMNPQRS",
    "user_capital_account_id": "01HXYZ0090ABCDEFGHJKMNPQRS",
    "transfer_reference": "capital-fixed-return:01HXYZ0088ABCDEFGHJKMNPQRS"
  }
}

string

A secondary identifier for the capital account, in addition to capital_account_id.

This endpoint does not require a request body. Nuvion never accepts client-supplied amounts, rates, inventory, or agreements. A retry resumes from the persisted transfer and order state and never issues a second debit. Where post-debit persistence fails, the order transitions to RECOVERY_REQUIRED for reconciliation rather than being retried as a new debit, and subsequent calls return 409 error_transfer_already_processing.

Retrieve capital orders

GET /product-orders Lists the capital orders belonging to the authenticated entity. Each item includes a linked capital account summary where one exists.

Query parameters

string

Filter by order status. One of RESERVED, CONFIRMING, APPROVED, EXPIRED, REJECTED, RECOVERY_REQUIRED.

string

Filter by product type. One of FIXED_RETURN, SHARE_OFFERING.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

number

Page size. Between 1 and 100. Defaults to 25.

string

Next-page cursor.

string

Previous-page cursor. Mutually exclusive with cursor.

curl "https://api.nuvion.dev/product-orders?status=APPROVED&product_type=FIXED_RETURN&limit=25" \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital orders retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "reference": "01HXYZ0091ABCDEFGHJKMNPQRS",
        "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
        "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
        "product_type": "FIXED_RETURN",
        "currency": "NGN",
        "amount": 50000000,
        "reserved_quantity": null,
        "status": "APPROVED",
        "status_reason": null,
        "expires_at": 1787098500000,
        "confirmed_at": 1787097640000,
        "rejected_at": null,
        "expired_at": null,
        "created": 1787097600000,
        "updated": 1787097640000,
        "capital_account": {
          "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
          "product_order_id": "01HXYZ0088ABCDEFGHJKMNPQRS",
          "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
          "product_type": "FIXED_RETURN",
          "currency": "NGN",
          "account_number": "0019876543",
          "principal": 50000000,
          "locked_rate": 0.18,
          "day_count": 365,
          "tenor_days": 90,
          "start_date": 1787097640000,
          "maturity_date": 1794873600000,
          "early_action_date": 1789689600000,
          "accrued_interest": 739726,
          "due_interest": 1997261,
          "expected_net_payout": 51997261,
          "total_deductions": 221917,
          "gross_interest": 2219178,
          "expected_gross_payout": 52219178,
          "net_payout": null,
          "settlement_date": null,
          "lifecycle": {
            "status": "ACTIVE",
            "payout_status": null
          },
          "created": 1787097640000,
          "updated": 1789689600000
        }
      },
      {
        "id": "01HXYZ0108ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "reference": "01HXYZ0110ABCDEFGHJKMNPQRS",
        "product_id": "01HXYZ0081ABCDEFGHJKMNPQRS",
        "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
        "product_type": "SHARE_OFFERING",
        "currency": "USD",
        "amount": 10251000,
        "reserved_quantity": 402,
        "status": "EXPIRED",
        "status_reason": "The reservation expired before it was confirmed.",
        "expires_at": 1787012100000,
        "confirmed_at": null,
        "rejected_at": null,
        "expired_at": 1787012100000,
        "created": 1787011200000,
        "updated": 1787012100000,
        "capital_account": null
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": false,
        "limit": 25,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "created",
          "order": "desc"
        }
      }
    }
  }
}

Retrieve a capital order

GET /product-orders/{id} Retrieves a capital order with its linked account summary and agreement snapshots. Agreements expose only the requesting entity’s affirmations and never internal signatory metadata.

Path parameters

string

required

The ULID of the capital order.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital order retrieved successfully",
  "data": {
    "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "reference": "01HXYZ0091ABCDEFGHJKMNPQRS",
    "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
    "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
    "product_type": "FIXED_RETURN",
    "currency": "NGN",
    "amount": 50000000,
    "reserved_quantity": null,
    "status": "APPROVED",
    "status_reason": null,
    "expires_at": 1787098500000,
    "confirmed_at": 1787097640000,
    "rejected_at": null,
    "expired_at": null,
    "created": 1787097600000,
    "updated": 1787097640000,
    "capital_account": {
      "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
      "product_order_id": "01HXYZ0088ABCDEFGHJKMNPQRS",
      "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
      "product_type": "FIXED_RETURN",
      "currency": "NGN",
      "account_number": "0019876543",
      "principal": 50000000,
      "locked_rate": 0.18,
      "day_count": 365,
      "tenor_days": 90,
      "start_date": 1787097640000,
      "maturity_date": 1794873600000,
      "early_action_date": 1789689600000,
      "accrued_interest": 739726,
      "due_interest": 1997261,
      "expected_net_payout": 51997261,
      "total_deductions": 221917,
      "gross_interest": 2219178,
      "expected_gross_payout": 52219178,
      "net_payout": null,
      "settlement_date": null,
      "lifecycle": {
        "status": "ACTIVE",
        "payout_status": null
      },
      "created": 1787097640000,
      "updated": 1789689600000
    },
    "agreements": [
      {
        "document": {
          "name": "Fixed Return Terms and Conditions",
          "url": "https://cdn.nuvion.dev/capital/fixed-return-terms.pdf"
        },
        "affirmations": [
          {
            "action_type": "affirmation",
            "actioned_at": 1787097600000
          }
        ]
      }
    ]
  }
}

Preview a withdrawal

GET /product-orders/{id}/withdrawal/preview Returns a read-only payout preview for a Fixed Return capital order. Nuvion resolves the order and its linked capital account, then selects one path from the account snapshot and the current time: before maturity, the early-liquidation preview applies where the account is active, unlocked, and eligible; from MATURED, the contractual maturity payout applies with no early penalty. The preview has no side effects. It never opens a session, writes a record, or schedules a settlement job.

Path parameters

string

required

The ULID of the capital order.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS/withdrawal/preview \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital withdrawal preview generated successfully",
  "data": {
    "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "gross_interest": 739726,
    "penalty_rate": 0.25,
    "penalty_amount": 184931,
    "total_deductions": 55479,
    "net_payout": 50499316,
    "days_elapsed": 30
  }
}

{
  "status": "success",
  "message": "Capital withdrawal preview generated successfully",
  "data": {
    "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "gross_interest": 2219178,
    "penalty_rate": 0,
    "penalty_amount": 0,
    "total_deductions": 221917,
    "net_payout": 51997261,
    "days_elapsed": 90
  }
}

string

The ULID of the capital account being previewed.

string

The ID of the entity that owns the capital account.

number

Accrued interest for an early preview, or the contractual interest at maturity.

number

The decimal penalty rate applied to gross interest. 0 for a maturity withdrawal.

number

gross_interest multiplied by penalty_rate, rounded down. 0 for a maturity withdrawal.

number

Interest-based deductibles such as withholding tax. Applied to the penalty-excluded base for an early withdrawal, and to the full interest base at maturity.

number

principal + gross_interest - penalty_amount - total_deductions.

number

Whole days elapsed since the start date for an early preview, or the account tenor at maturity.

Initiate a withdrawal

POST /product-orders/{id}/withdrawal Initiates the payout for a Fixed Return capital order. Nuvion resolves the order and its linked capital account, then selects one guarded path from the account snapshot:

An ACTIVE account before maturity follows the early withdrawal rules: ACTIVE moves to EARLY_LIQUIDATING, with the penalty and interest-based deductibles applied. Nuvion writes the penalty, withholding, and payout capital transactions and schedules the early-liquidation settlement job.
A MATURED account follows the contractual maturity payout: MATURED moves to CLOSING, with no early penalty. Nuvion creates a pending payment backed by the order’s funding account and schedules the maturity settlement job.
A CLOSING or terminal account returns its current state rather than starting a second payout.

Path parameters

string

required

The ULID of the capital order.

Request parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl -X POST https://api.nuvion.dev/product-orders/01HXYZ0088ABCDEFGHJKMNPQRS/withdrawal \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital withdrawal initiated successfully",
  "data": {
    "id": "01HXYZ0088ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "reference": "01HXYZ0091ABCDEFGHJKMNPQRS",
    "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
    "funding_account_id": "01HXYZ0086ABCDEFGHJKMNPQRS",
    "product_type": "FIXED_RETURN",
    "currency": "NGN",
    "amount": 50000000,
    "reserved_quantity": null,
    "status": "APPROVED",
    "status_reason": null,
    "expires_at": 1787098500000,
    "confirmed_at": 1787097640000,
    "rejected_at": null,
    "expired_at": null,
    "created": 1787097600000,
    "updated": 1789689600000,
    "capital_account": {
      "id": "01HXYZ0089ABCDEFGHJKMNPQRS",
      "product_order_id": "01HXYZ0088ABCDEFGHJKMNPQRS",
      "product_id": "01HXYZ0085ABCDEFGHJKMNPQRS",
      "product_type": "FIXED_RETURN",
      "currency": "NGN",
      "account_number": "0019876543",
      "principal": 50000000,
      "locked_rate": 0.18,
      "day_count": 365,
      "tenor_days": 90,
      "start_date": 1787097640000,
      "maturity_date": 1794873600000,
      "early_action_date": 1789689600000,
      "accrued_interest": 739726,
      "due_interest": 1997261,
      "expected_net_payout": 51997261,
      "total_deductions": 221917,
      "gross_interest": 2219178,
      "expected_gross_payout": 52219178,
      "net_payout": 50499316,
      "settlement_date": null,
      "lifecycle": {
        "status": "EARLY_LIQUIDATING",
        "payout_status": "pending"
      },
      "created": 1787097640000,
      "updated": 1789689600000
    },
    "agreements": [
      {
        "document": {
          "name": "Fixed Return Terms and Conditions",
          "url": "https://cdn.nuvion.dev/capital/fixed-return-terms.pdf"
        },
        "affirmations": [
          {
            "action_type": "affirmation",
            "actioned_at": 1787097600000
          }
        ]
      }
    ]
  }
}

This endpoint does not require a request body. The stored account snapshot is authoritative; Nuvion never accepts client-supplied amounts, rates, or settlement accounts.

A 400 error_operation_invalid_for_state covers locked accounts, non-Fixed-Return accounts, accounts already EARLY_LIQUIDATING, CLOSING, or CLOSED, accounts at or after maturity that are still ACTIVE, products with early withdrawal disabled, and requests made before the earliest action day.

Retrieve the capital portfolio

GET /capital-portfolio Returns the authenticated entity’s current capital investment totals grouped by currency. Nuvion accrues Fixed Return interest from the account terms at request time; Share Offering value uses the units held and the latest market price. Fixed Return holdings in ACTIVE, MATURED, EARLY_LIQUIDATING, and CLOSING, and Share Offering holdings in LOCKED, ALLOTMENT_ADJUSTED, ALLOTMENT_CONFIRMED, and TRANSFERABLE, are included.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl https://api.nuvion.dev/capital-portfolio \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "message": "Capital portfolio retrieved successfully",
  "status": "success",
  "data": {
    "currencies": [
      {
        "currency": "NGN",
        "totals": {
          "investment": {
            "amount_invested": 50000000,
            "total_return": 739726,
            "current_value": 50739726
          }
        }
      },
      {
        "currency": "USD",
        "totals": {
          "investment": {
            "amount_invested": 10251000,
            "total_return": null,
            "current_value": null
          }
        }
      }
    ]
  }
}

string

ISO 4217 currency code. Currencies are sorted ascending.

number

The total invested amount in minor units.

number

The total accrued or unrealized return in minor units. null when valuation is unavailable.

number

The invested amount plus the return in minor units. null when valuation is unavailable.

Valuation fields are null for a currency when any included holding lacks a valid valuation, rather than being reported as zero.

Retrieve capital transactions

GET /capital-transactions Lists the immutable capital transaction records belonging to the authenticated entity for a single capital account. Transaction metadata is redacted from the entity’s view.

Query parameters

string

required

The ULID of the capital account that owns the transactions.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

number

Page size. Between 1 and 100. Defaults to 25.

string

Next-page cursor.

string

Previous-page cursor. Mutually exclusive with cursor.

curl "https://api.nuvion.dev/capital-transactions?capital_id=01HXYZ0089ABCDEFGHJKMNPQRS&limit=25" \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital transactions retrieved successfully",
  "data": {
    "data": [
      {
        "id": "01HXYZ0107ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "event_type": "DAILY_ACCRUAL",
        "amount": 24657,
        "accrual_date": 1787184000000,
        "created": 1787184032118,
        "funded_amount": null,
        "placement_fee_charged": null,
        "vehicle_expense_charged": null
      },
      {
        "id": "01HXYZ0106ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "event_type": "PURCHASE",
        "amount": 50000000,
        "accrual_date": null,
        "created": 1787097640000,
        "funded_amount": null,
        "placement_fee_charged": null,
        "vehicle_expense_charged": null
      }
    ],
    "meta": {
      "pagination": {
        "order": "desc",
        "has_next": false,
        "limit": 25,
        "has_previous": false,
        "next_cursor": null,
        "previous_cursor": null
      },
      "filters_applied": {
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "capital_account_id": "01HXYZ0089ABCDEFGHJKMNPQRS",
        "sort": {
          "field": "created",
          "order": "desc"
        }
      }
    }
  }
}

Retrieve a capital transaction

GET /capital-transactions/{id} Retrieves a capital transaction. Transaction metadata is redacted from the entity’s view.

Path parameters

string

required

The ULID of the capital transaction.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

curl https://api.nuvion.dev/capital-transactions/01HXYZ0106ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json"

{
  "status": "success",
  "message": "Capital transaction retrieved successfully",
  "data": {
    "id": "01HXYZ0106ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
    "event_type": "PURCHASE",
    "amount": 50000000,
    "accrual_date": null,
    "created": 1787097640000,
    "funded_amount": null,
    "placement_fee_charged": null,
    "vehicle_expense_charged": null
  }
}

Error Response

Validation errors: triggered if the payload or query parameters do not meet the endpoint specification
State errors: triggered where the order or capital account is in a state that does not permit the requested action
Transfer errors: triggered where the funding wallet cannot be debited, or a debit is already being reconciled

Type	HTTP	Description
`error_operation_invalid_for_state`	400	Terminal or invalid order or account transition
`error_transfer_insufficient_funds`	400	The funding wallet does not hold enough funds for the debit
`error_auth_permission_denied`	403	The authenticated entity is not permitted to perform the action
`error_resource_not_found`	404	The product, order, capital account, or transaction could not be found
`error_concurrent_modification_detected`	409	A concurrent reservation or confirmation claim was lost
`error_transfer_already_processing`	409	Transfer recovery or reconciliation is pending. No additional debit is attempted
`error_resource_expired`	410	The reservation expired before it was confirmed
`error_validation_error`	422	One or more fields failed validation
`error_system_internal_error`	500	Malformed live product configuration or an invalid capital account valuation
`error_system_dependency_unavailable`	503	A required ledger mapping, AUM account, fee account, or payout account is missing

{
  "status": "error",
  "message": "This capital order can no longer be confirmed.",
  "type": "error_operation_invalid_for_state"
}

{
  "status": "error",
  "message": "The funding account does not have enough funds to complete this transfer.",
  "type": "error_transfer_insufficient_funds"
}

{
  "status": "error",
  "message": "We couldn't authenticate this request. Please check your credentials and try again.",
  "type": "error_auth_credentials_invalid"
}

{
  "status": "error",
  "message": "You do not have permission to perform this action.",
  "type": "error_auth_permission_denied"
}

{
  "status": "error",
  "message": "We couldn't find that {resource}. It may have been deleted or the ID might be incorrect.",
  "type": "error_resource_not_found"
}

{
  "status": "error",
  "message": "This order is already being processed. Please check back shortly before retrying.",
  "type": "error_transfer_already_processing"
}

{
  "status": "error",
  "message": "This reservation has expired. Please create a new order.",
  "type": "error_resource_expired"
}

{
  "status": "error",
  "message": "Validation failed for one or more fields",
  "type": "error_validation_error",
  "validations": [
    {
      "fieldName": "principal",
      "type": "error_validation_value_out_of_range",
      "message": "The value for 'principal' should be between 10000000 and 500000000."
    },
    {
      "fieldName": "lock_investment",
      "type": "error_validation_required_field_missing",
      "message": "The field 'lock_investment' is required for FIXED_RETURN orders."
    }
  ]
}

{
  "status": "error",
  "message": "We couldn't complete this request due to an internal processing failure. Please try again.",
  "type": "error_system_internal_error"
}

​The Capital Product object

​Capital product types

​Day count conventions

​The Capital Order object

​Capital order statuses

​The Capital Account object

​Capital account lifecycle statuses

​The Capital Transaction object

​Capital transaction event types

​Retrieve capital products

​Query parameters

​Retrieve a capital product

​Path parameters

​Query parameters

​Create a capital order

​Request parameters

​Response

​Confirm a capital order

​Path parameters

​Request parameters

​Retrieve capital orders

​Query parameters

​Retrieve a capital order

​Path parameters

​Query parameters

​Preview a withdrawal

​Path parameters

​Query parameters

​Initiate a withdrawal

​Path parameters

​Request parameters

​Retrieve the capital portfolio

​Query parameters

​Retrieve capital transactions

​Query parameters

​Retrieve a capital transaction

​Path parameters

​Query parameters

​Error Response

The Capital Product object

Capital product types

Day count conventions

The Capital Order object

Capital order statuses

The Capital Account object

Capital account lifecycle statuses

The Capital Transaction object

Capital transaction event types

Retrieve capital products

Query parameters

Retrieve a capital product

Path parameters

Query parameters

Create a capital order

Request parameters

Response

Confirm a capital order

Path parameters

Request parameters

Retrieve capital orders

Query parameters

Retrieve a capital order

Path parameters

Query parameters

Preview a withdrawal

Path parameters

Query parameters

Initiate a withdrawal

Path parameters

Request parameters

Retrieve the capital portfolio

Query parameters

Retrieve capital transactions

Query parameters

Retrieve a capital transaction

Path parameters

Query parameters

Error Response