Skip to main content
POST
/
v1
/
financial-accounts
Create Financial Account
curl --request POST \
  --url https://api.monime.io/v1/financial-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Monime-Space-Id: <monime-space-id>' \
  --data '{
  "name": "<string>",
  "currency": "<string>",
  "reference": "<string>",
  "description": "<string>",
  "metadata": {}
}'
{
  "success": true,
  "messages": [
    "<any>"
  ],
  "result": {
    "id": "<string>",
    "uvan": "<string>",
    "name": "<string>",
    "currency": "<string>",
    "reference": "<string>",
    "description": "<string>",
    "balance": {
      "available": {
        "currency": "<string>",
        "value": 123
      }
    },
    "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

Creates a new financial account for holding or managing funds within a Space.

​
name
string
required

Label for the financial account, e.g., 'Main Wallet' or 'Reserved Account'.

Maximum length: 100
​
currency
string
required

ISO 4217 currency code (e.g., 'SLE', 'USD') indicating the account's currency.

​
reference
string | null

Optional external reference ID for this account. Must be unique across financial accounts in the same Space.

Maximum length: 64
​
description
string | null

Optional note about the account’s usage or purpose.

Maximum length: 150
​
metadata
object | null

Updated metadata for storing additional context about the account.

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

A Financial Account is a logical wallet or ledger unit that holds and tracks money for a user or entity.
It represents a balance in a specific currency and serves as the foundation for all money movement within Monime.

Each account is uniquely identifiable, has a human-friendly display name (e.g., “Main Wallet”), and is always tied to a single currency such as SLE or USD.

In APIs, Financial Accounts act as the source or destination of funds for transfers, payouts, or collections.

Use Cases

  • Embedded Finance
    With Embedded Finance on Monime, fintechs can create dynamic wallet accounts hosted directly on Monime’s infrastructure.
    Incoming collections from cards, Mobile Money, or banks are deposited into these accounts, which can then be used for spend, cash-out, or peer-to-peer (P2P) transfers by moving funds between accounts. Example : Payments received through Checkout Sessions are credited to a user’s wallet account and can later be transferred to another user’s wallet, enabling seamless P2P experiences.

  • Settlement Account
    Businesses separate collected funds from the account used to settle merchants or subsidiaries.
    Example: A PSP routes daily Mobile Money collections into a Settlement Account before initiating payouts.

  • Disbursement Float
    A pre-funded account maintained to ensure outgoing transfers and payouts can always be covered.
    Example: Your platform maintains a Disbursement Float account; when it runs low, you top it up via an Internal Transfer.

  • Dedicated Currency Account
    Multi-currency platforms maintain one account per supported currency.
    Example: A customer has both a USD Account and an SLE Account, ensuring currency isolation and easier reconciliation.