Skip to main content
POST
/
v1
/
internal-transfers
Create Internal Transfer
curl --request POST \
  --url https://api.monime.io/v1/internal-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Monime-Space-Id: <monime-space-id>' \
  --data '{
  "amount": {
    "currency": "<string>",
    "value": 123
  },
  "sourceFinancialAccount": {
    "id": "<string>"
  },
  "destinationFinancialAccount": {
    "id": "<string>"
  },
  "description": "<string>",
  "metadata": {}
}'
{
  "success": true,
  "messages": [
    "<any>"
  ],
  "result": {
    "id": "<string>",
    "status": "pending",
    "amount": {
      "currency": "<string>",
      "value": 123
    },
    "sourceFinancialAccount": {
      "id": "<string>"
    },
    "destinationFinancialAccount": {
      "id": "<string>"
    },
    "financialTransactionReference": "<string>",
    "description": "<string>",
    "failureDetail": {
      "code": "unknown",
      "message": "<string>"
    },
    "ownershipGraph": {
      "owner": {
        "id": "<string>",
        "type": "<string>",
        "metadata": {},
        "owner": {
          "id": "<string>",
          "type": "<string>",
          "metadata": {},
          "owner": {}
        }
      }
    },
    "createTime": "2023-11-07T05:31:56Z",
    "updateTime": "2023-11-07T05:31:56Z",
    "metadata": {}
  }
}

Authorizations

​
Authorization
string
header
required

Bearer HTTP authentication specified with the header Authorization: Bearer <access_token>

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.

Maximum length: 64
​
Monime-Version
enum<string> | null

Specifies which version of the Monime API will handle this request.

Available options:
caph.2025-08-23,
caph.2025-06-20
​
Monime-Space-Id
string
required

The value is the tenancy parameter that Monime uses to determine which space the request is intended for.

Maximum length: 64

Body

application/json

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.

​
sourceFinancialAccount
object
required

Source financial account from which the funds will be withdrawn.

​
destinationFinancialAccount
object
required

Destination financial account where the funds will be deposited.

​
description
string | null

Optional description of the transfer. Useful for developer context, logging, or internal references.

Maximum length: 150
​
metadata
object | null

Custom metadata for attaching structured context or developer-defined identifiers.

Response

200 - application/json

OK

​
success
boolean

Represents the status of the query operation, confirming if it was successful. This field is always true

​
messages
any[]

Contains a list of messages providing relevant information or feedback related to the query or operation

​
result
object

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.

⌘I