Wallets and funding

One balance per currency, funded by bank transfer, hosted checkout, direct debit or mobile money, and a ledger you can reconcile.

GET /wallets shows one balance per currency:

{
  "data": [
    {"currency": "NGN", "balance": "40000.0000", "updated_at": "2026-10-12T03:07:05.037370"},
    {"currency": "GHS", "balance": "439.4000",   "updated_at": "2026-10-12T03:08:08.839787"},
    {"currency": "USD", "balance": "0.0000",     "updated_at": "2026-10-11T19:32:12.312473"}
  ]
}

A wallet can never go negative, and every change is a ledger entry at GET /transactions?currency=NGN with an entry_type (funding, order_debit, order_refund, sell_proceeds, adjustment), a direction and balance_after. Sum the statement and it equals the balance; that is a check you can run every day.

Creating a funding request

POST /wallets/{currency}/fund with an amount and, optionally, a method. Each currency has a default; the response carries instructions for that method and a reference to quote.

currency	method	you do	the wallet is credited when
NGN	korapay_bank_transfer (default)	transfer the exact amount to the one-time account in instructions.account before expires_at	the transfer is confirmed
NGN	korapay_checkout	open instructions.checkout_url and pay by card, bank transfer or USSD	the payment is confirmed
NGN	flutterwave_direct_debit	nothing per request; Ladder debits the account under your active mandate	the bank confirms the debit
GHS	hubtel_momo (default)	open instructions.checkout_url and approve the mobile-money prompt	the payment is confirmed
USD	manual_bank_transfer (default)	wire the amount quoting the LPF_ reference as narration	Ladder’s operations team confirms receipt

Asking for a method the currency does not offer returns 400 funding_method_unavailable with details.available.

Hosted checkout (NGN)

Request

{"amount": "15000", "method": "korapay_checkout"}

Response

{
  "data": {
    "id": "8cd5dc6b-fe0f-44b5-b784-d2008cce95b0",
    "reference": "LPF_192db1367a284ef4be40",
    "currency": "NGN",
    "amount": "15000.0000",
    "amount_received": null,
    "method": "korapay_checkout",
    "status": "pending",
    "instructions": {
      "type": "checkout",
      "checkout_url": "https://checkout.korapay.com/KPY-PI-…/pay",
      "narration": "LPF_192db1367a284ef4be40",
      "note": "Open the checkout page to pay by card, bank transfer or USSD. The wallet is credited when the payment is confirmed."
    },
    "expires_at": "2026-10-13T03:03:20.619235",
    "settled_at": null,
    "order_id": null,
    "mandate_id": null,
    "created_at": "2026-10-12T03:03:20.620629"
  }
}

Mobile money (GHS)

Request

{"amount": "20"}

Response

{
  "data": {
    "reference": "LPF_6c874a9a559149d880f7",
    "currency": "GHS",
    "amount": "20.0000",
    "method": "hubtel_momo",
    "status": "pending",
    "instructions": {
      "type": "mobile_money",
      "checkout_url": "https://pay.hubtel.com/f6723c017d914d118e75d864a06507af",
      "provider_reference": "f6723c017d914d118e75d864a06507af",
      "narration": "LPF_6c874a9a559149d880f7",
      "note": "Open the Hubtel checkout and approve the mobile money prompt. The wallet is credited when Hubtel confirms the payment."
    },
    "expires_at": "2026-10-13T03:08:08.118628"
  }
}

Sandbox

Response

{
  "data": {
    "reference": "LPF_b15388916cae460bb61deb5a0aec1f9c",
    "currency": "NGN",
    "amount": "50000.0000",
    "method": "korapay_bank_transfer",
    "status": "pending",
    "instructions": {
      "type": "sandbox",
      "method": "korapay_bank_transfer",
      "narration": "LPF_b15388916cae460bb61deb5a0aec1f9c",
      "note": "Sandbox: settle with POST /partner/v1/sandbox/funding-requests/{id}/simulate."
    }
  }
}

Settle it with POST /sandbox/funding-requests/{id}/simulate, optionally with a different amount to rehearse short and over-payments.

Funding lifecycle

pending ──paid and confirmed──▶ succeeded     wallet.funded   (amount_received may differ from amount)
pending ──provider reports failure──▶ failed  funding.failed
pending ──expires_at passes──▶ expired        funding.expired

• The wallet is credited with what actually arrives, so amount_received can be below or above amount.
• A transfer that lands after expiry is still credited once Ladder has verified it. Nothing is lost; it is just late.
• Act on wallet.funded rather than polling GET /funding-requests/{id}.

A funding request created by a checkout order (see buy orders) carries the order_id; its settlement executes that order and never touches your wallet float.