---
title: "Create Internal Transfer"
method: POST
path: "/v1/internal-transfers"
tags: ["Internal Transfer"]
---

# Create Internal Transfer

`POST /v1/internal-transfers`

Initiates a transfer of funds between two financial accounts within the same ecosystem.

## Headers

- `Idempotency-Key` string, required — This header is used to uniquely identify a logical request, ensuring that it is not processed more than once during retries.
- `Monime-Version` 'caph.2025-08-23' | 'caph.2025-06-20', nullable — Specifies which version of the Monime API will handle this request.
- `Monime-Space-Id` string, required — The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

## Request body

- object — Initiates a transfer of funds between two financial accounts within the same ecosystem.
  - `amount` object, required — Amount to be transferred from the source to the destination financial account.
    - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
    - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
  - `sourceFinancialAccount` object, required — Source financial account from which the funds will be withdrawn.
    - `id` string, required — ID of the source financial account that will be debited.
  - `destinationFinancialAccount` object, required — Destination financial account where the funds will be deposited.
    - `id` string, required — ID of the destination financial account that will be credited.
  - `description` string, nullable — Optional description of the transfer. Useful for developer context, logging, or internal references.
  - `metadata` object, nullable — Custom metadata for attaching structured context or developer-defined identifiers.

## Response `200`

OK

- object
  - `success` boolean — Represents the status of the query operation, confirming if it was successful. This field is always true
  - `messages` unknown[] — Contains a list of messages providing relevant information or feedback related to the query or operation
    - unknown
  - `result` InternalTransfer — An **Internal Transfer** is the movement of funds between financial accounts that exist within the same Space. Unlike payouts or customer payments that cross external networks (banks, card schemes, or mobile money), an Internal Transfer happens entirely within Monime’s ledger. It is the mechanism for shifting balances between accounts you own or manage, and it never leaves your organization’s financial boundary. --- ### Use Cases - **Wallet Top-ups** A customer wallet account can be funded by moving money from your master operational account. *Example*: A user adds **SLE 1,000** to their app wallet. Your backend issues an Internal Transfer from your **Operational Float** to the user’s **Wallet Account**. - **Inter-Account Routing** Businesses often separate funds for accounting clarity (e.g., “Card Collections,” “Mobile Money Collections,” “Bank Transfers”). *Example*: At the end of each day, you route all **Mobile Money collections** into a central **Settlement Account**. - **Internal Settlements** Useful when multiple departments or sub-entities operate under one Space. *Example*: Subsidiary A owes Subsidiary B **SLE 50,000**. Instead of moving money through the banking system, you perform an Internal Transfer inside your Monime ledger. - **Float Management** Fintechs maintain float across accounts to support disbursements. *Example*: If your **Disbursement Account** is running low, you move funds from your **Collection Account** to top it up before processing payouts. ---
    - `id` string — Unique identifier for this transfer object.
    - `status` 'pending' | 'processing' | 'failed' | 'completed' — Current status of the transfer: - 'pending': Created but not yet processed. - 'processing': Currently being processed. - 'failed': Transfer failed. - 'completed': Transfer successfully completed.
    - `amount` object — Amount to be transferred from the source to the destination account.
      - `currency` string — The [3-letter](https://en.wikipedia.org/wiki/ISO_4217) ISO currency code. Currently supported: 'SLE'
      - `value` integer — The value representation in the currency's minor unit. E.g. For 1 Leone (SLE 1), the value should be 100, denoting cents, the minor unit.
    - `sourceFinancialAccount` object — Source financial account from which the funds will be debited.
      - `id` string — Unique identifier for the financial account
    - `destinationFinancialAccount` object — Destination financial account to which the funds will be credited.
      - `id` string — Unique identifier for the financial account
    - `financialTransactionReference` string, nullable — Reference to the resulting financial transaction(s), if the transfer was completed.
    - `description` string, nullable — Human-readable description of the transfer. Useful for developer context, admin UIs, or logs.
    - `failureDetail` object, nullable — Failure details, populated only when the transfer status is 'failed'.
      - `code` 'unknown' | 'fund_insufficient' — **Error code** representing the reason this transfer failed. Possible values include: - **unknown**: Generic or unclassified failure. - **fund_insufficient**: Not enough funds in the source account.
      - `message` string, nullable — **Optional explanation** providing more context about the failure. Useful for developer logs or end-user display.
    - `ownershipGraph` object, nullable — Ownership chain that shows which object or action triggered the transfer — enabling audit traceability.
      - `owner` object — **Immediate object** that owns this entity. This is the direct originator or source object.
        - `id` string — **Unique ID** of the object instance that owns this entity.
        - `type` string — **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'.
        - `metadata` object, nullable — **Arbitrary metadata** describing the owning object.
        - `owner` CoreresourcesParentOwningObject
          - `id` string — **Unique ID** of the object instance that owns this entity.
          - `type` string — **Type of the object** that owns this entity. Examples include: 'internal_transfer', 'checkout_session', 'payment_code'.
          - `metadata` object, nullable — **Arbitrary metadata** describing the owning object.
          - `owner` CoreresourcesParentOwningObject — recursive
    - `createTime` string, date-time — Timestamp indicating when the transfer was created.
    - `updateTime` string, date-time, nullable — Timestamp of the most recent update to the transfer.
    - `metadata` object, nullable — Custom metadata for tagging this transfer with additional context or identifiers.

---

[API](https://skmtc.dev/monime/apis/monime-api.md) · [All operations](https://skmtc.dev/monime/apis/monime-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/monime/monime-api/revisions/bd7f875ea428/schema)