> ## Documentation Index
> Fetch the complete documentation index at: https://partners.ladder.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# 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).

```json Request theme={null}
{
  "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": "ada@example.com"},
  "metadata": {"portfolio": "balanced"}
}
```

```json Response (sandbox) theme={null}
{
  "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": "ada@example.com"},
    "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=…`.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.