Buy orders

Pay from the wallet or per order, tag the end customer, and follow the order to a holding.

POST /orders with the investment, the amount in the investment’s currency and how to pay:

payment_mode	what happens
wallet	the wallet is debited now; 402 insufficient_funds if it cannot cover the amount
checkout	a funding request is created for this order (payment in the response); the order executes only when that payment covers it, never from your wallet float

Optional fields: client_reference (your own id, unique per environment; 409 duplicate_client_reference), customer (reference, name, email of the end customer the position is for), metadata (free-form, returned unchanged).

Request

{
  "investment_id": "8788a2e2-c071-4a05-8dac-adb40627926a",
  "amount": "10000",
  "currency": "NGN",
  "payment_mode": "wallet",
  "client_reference": "HP-0001",
  "customer": {"reference": "cust-ada-001", "name": "Ada Nwosu", "email": "[e-mail]"},
  "metadata": {"portfolio": "balanced"}
}

Response (sandbox)

{
  "data": {
    "id": "121c40bd-c1df-4fa5-93e2-7a83c45a0585",
    "reference": "LPO_7c44174edc4d460096a41f72dcdd4cab",
    "client_reference": "HP-0001",
    "side": "buy",
    "investment_id": "8788a2e2-c071-4a05-8dac-adb40627926a",
    "investment_name": "ARM NGN Mutual Fund",
    "amount": "10000.0000",
    "currency": "NGN",
    "payment_mode": "wallet",
    "status": "completed",
    "customer": {"reference": "cust-ada-001", "name": "Ada Nwosu", "email": "[e-mail]"},
    "metadata": {"portfolio": "balanced"},
    "failure_reason": "",
    "payment": null,
    "holding_id": "e523bf7b-f7ed-43d5-ba83-c73fcaacfbe6",
    "paid_at": "2026-10-11T19:25:15.258083",
    "completed_at": "2026-10-11T19:25:17.393308",
    "cancelled_at": null,
    "created_at": "2026-10-11T19:25:12.487604"
  }
}

That is a sandbox response, which completes at once. Live, the same request returns status: "pending_fulfilment" with paid_at set and holding_id null; order.completed arrives when Ladder has placed the position.

Lifecycle

                 wallet ──debit──▶ pending_fulfilment ──Ladder places it──▶ completed (holding created)
POST /orders ─┤
                 checkout ──▶ awaiting_payment ──payment covers it──▶ debit ──▶ pending_fulfilment ──▶ completed

awaiting_payment | pending_fulfilment ──POST /orders/{id}/cancel──▶ cancelled   (refund if already paid)
awaiting_payment | pending_fulfilment ──Ladder rejects──▶ failed                (refund if already paid; reason in failure_reason)
awaiting_payment ──its funding request expires──▶ cancelled

Money rules you can rely on

• A buy is debited exactly once and refunded at most once. Both ledger entries carry the order reference.
• A short payment on a checkout order stays in your wallet and the order keeps waiting; an overpayment executes the order and leaves the surplus in the wallet.
• A completed buy always has a holding.

Holdings

GET /holdings lists positions with units, unit_price, principal, current_value, accrued_returns, maturity_date and the customer_reference you tagged the order with. Reconcile per end customer with GET /holdings?customer_reference=… and GET /orders?client_reference=….

{
  "id": "ebc3fba8-7807-4d87-9f60-aeda0ee3f09f",
  "investment_id": "80306ed6-1013-419c-9592-f8adb6041f73",
  "investment_name": "Delta: Delta",
  "order_id": "2d9d726e-fd3c-4cb1-88b0-dc9b487065c4",
  "customer_reference": "cust-kofi-003",
  "currency": "GHS",
  "principal": "78.8000",
  "units": "40.00000000",
  "unit_price": "1.9700",
  "current_value": "78.8000",
  "accrued_returns": "0.0000",
  "status": "active"
}

Validation

Validation errors come back before anything moves: investment_not_found, investment_closed, currency_mismatch (with investment_currency), amount_below_minimum (with minimum), allocation_exceeded (with allocation_remaining).

Listed equities

An order for an NGX-listed instrument (through its ladder.investment_id) is a market order placed through Ladder’s broker at the prevailing price. It is accepted as pending_fulfilment, executed during the trading session, and completed with the executed units and unit_price. Plan for same-day or next-session completion rather than seconds.