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

# 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:

```json theme={null}
{
  "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](/guides/direct-debit-mandates) | 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`.

<Tabs>
  <Tab title="Hosted checkout (NGN)">
    ```json Request theme={null}
    {"amount": "15000", "method": "korapay_checkout"}
    ```

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

  <Tab title="Mobile money (GHS)">
    ```json Request theme={null}
    {"amount": "20"}
    ```

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

  <Tab title="Sandbox">
    ```json Response theme={null}
    {
      "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.
  </Tab>
</Tabs>

## 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}`.

<Note>
  A funding request created by a checkout order (see [buy orders](/guides/buy-orders)) carries the `order_id`; its settlement executes that order and never touches your wallet float.
</Note>


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