BPMCore Currency API

The Currency API provides lookup and retrieval of currency configurations used throughout the BankLingo platform. This API is primarily used for dropdown populations, currency validations, and multi-currency operations.

Base Endpoint

POST /api/core/cmd

Commands & Queries

1. Look Up Currencies

Quick currency lookup for autocomplete and dropdown controls. Returns a simplified list of currencies.

Command Name: LookUpCurrencysQuery

Request Parameters

Parameter	Type	Required	Description
searchText	string	No	Search in currency code or name
pageSize	integer	No	Max results (default: system maximum)
isActive	boolean	No	Filter by active status (default: true)

Request Example

{
  "Cmd": "LookUpCurrencysQuery",
  "Data": {
    "searchText": "NG",
    "pageSize": 10
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Currencies retrieved successfully.",
  "Data": {
    "items": [
      {
        "Code": "NGN",
        "Name": "Nigerian Naira",
        "Symbol": "₦",
        "IsActive": true
      },
      {
        "Code": "GHS",
        "Name": "Ghanaian Cedi",
        "Symbol": "₵",
        "IsActive": true
      }
    ]
  }
}

---

2. Get Currencies (Full List)

Retrieves a complete paginated list of all currencies with full details.

Command Name: GetCurrenciesQuery

Request Parameters

Parameter	Type	Required	Description
searchText	string	No	Search in currency code, name, or symbol
isActive	boolean	No	Filter by active status
pageNumber	integer	No	Page number (default: 1)
pageSize	integer	No	Items per page (default: 20)
isExport	boolean	No	Export all results (default: false)

Request Example

{
  "Cmd": "GetCurrenciesQuery",
  "Data": {
    "isActive": true,
    "pageNumber": 1,
    "pageSize": 50
  }
}

Response Structure

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Currencies retrieved successfully.",
  "Data": {
    "items": [
      {
        "Id": 1,
        "Code": "NGN",
        "Name": "Nigerian Naira",
        "Symbol": "₦",
        "DecimalPlaces": 2,
        "IsActive": true,
        "IsBaseCurrency": true,
        "ExchangeRate": 1.0000,
        "CreatedAt": "2023-01-01T00:00:00",
        "UpdatedAt": "2024-01-15T10:00:00"
      },
      {
        "Id": 2,
        "Code": "USD",
        "Name": "United States Dollar",
        "Symbol": "$",
        "DecimalPlaces": 2,
        "IsActive": true,
        "IsBaseCurrency": false,
        "ExchangeRate": 1580.50,
        "CreatedAt": "2023-01-01T00:00:00",
        "UpdatedAt": "2024-01-20T09:30:00"
      },
      {
        "Id": 3,
        "Code": "GBP",
        "Name": "British Pound Sterling",
        "Symbol": "£",
        "DecimalPlaces": 2,
        "IsActive": true,
        "IsBaseCurrency": false,
        "ExchangeRate": 1950.75,
        "CreatedAt": "2023-01-01T00:00:00",
        "UpdatedAt": "2024-01-20T09:30:00"
      }
    ],
    "totalRows": 45,
    "totalPages": 1,
    "pageSize": 50,
    "currentPage": 1
  },
  "HasNext": false,
  "HasPrevious": false
}

Response Fields

Field	Type	Description
Id	long	Currency ID
Code	string	ISO 4217 currency code (e.g., "NGN", "USD")
Name	string	Full currency name
Symbol	string	Currency symbol (e.g., "₦", "$", "£")
DecimalPlaces	integer	Number of decimal places (typically 2)
IsActive	boolean	Whether currency is active for transactions
IsBaseCurrency	boolean	True if this is the institution's base currency
ExchangeRate	decimal	Exchange rate to base currency
CreatedAt	datetime	When currency was added to system
UpdatedAt	datetime	Last exchange rate update timestamp

---

Currency Codes

Supported African Currencies

Code	Currency	Symbol	Country
NGN	Nigerian Naira	₦	Nigeria
GHS	Ghanaian Cedi	₵	Ghana
KES	Kenyan Shilling	KSh	Kenya
ZAR	South African Rand	R	South Africa
UGX	Ugandan Shilling	USh	Uganda
TZS	Tanzanian Shilling	TSh	Tanzania
EGP	Egyptian Pound	£	Egypt
MAD	Moroccan Dirham	د.م.	Morocco

Major Global Currencies

Code	Currency	Symbol	Region
USD	US Dollar	$	United States
EUR	Euro	€	European Union
GBP	British Pound	£	United Kingdom
JPY	Japanese Yen	¥	Japan
CNY	Chinese Yuan	¥	China
CHF	Swiss Franc	Fr	Switzerland

---

Common Use Cases

Example 1: Populate Currency Dropdown

Use LookUpCurrencysQuery for lightweight UI dropdowns:

{
  "Cmd": "LookUpCurrencysQuery",
  "Data": {
    "isActive": true,
    "pageSize": 100
  }
}

Example 2: Currency Validation

Validate currency before creating a transaction:

{
  "Cmd": "GetCurrenciesQuery",
  "Data": {
    "searchText": "NGN",
    "isActive": true
  }
}

Example 3: Exchange Rate Lookup

Get current exchange rates for multi-currency operations:

{
  "Cmd": "GetCurrenciesQuery",
  "Data": {
    "isActive": true,
    "isExport": true
  }
}

---

Integration Notes

Base Currency

• Every BankLingo instance has one base currency
• All exchange rates are relative to the base currency
• Base currency has ExchangeRate = 1.0000
• Typically set to the country's local currency

Exchange Rate Updates

• Exchange rates are updated periodically (configured per tenant)
• Updates may be manual or automated via external APIs
• Historical rates are tracked for audit purposes
• Multi-currency transactions use the rate at transaction time

Multi-Currency Transactions

When processing multi-currency transactions:

1. Retrieve currency details including exchange rate
2. Convert amounts to base currency for accounting
3. Store both original amount and base currency equivalent
4. Journal entries are typically in base currency

Currency Precision

• Most currencies use 2 decimal places
• Some currencies (e.g., JPY) use 0 decimal places
• System respects the DecimalPlaces configuration
• Rounding follows currency-specific rules

---

Best Practices

1. Cache Currency Data: Currencies change infrequently; cache for performance
2. Use LookUp for UI: Use LookUpCurrencysQuery for dropdowns/autocomplete
3. Use GetCurrencies for Validation: Use GetCurrenciesQuery when you need full details
4. Filter Inactive: Always filter for active currencies in transaction flows
5. Exchange Rate Awareness: Check UpdatedAt to ensure rates are current
6. Base Currency Handling: Special logic may be needed for base currency transactions

---

Error Scenarios

No Active Currencies

If no active currencies are configured:

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Currencies retrieved successfully.",
  "Data": {
    "items": [],
    "totalRows": 0
  }
}

Invalid Search

Empty results for unmatched search:

{
  "IsSuccessful": true,
  "StatusCode": "00",
  "Message": "Currencies retrieved successfully.",
  "Data": {
    "items": [],
    "totalRows": 0
  }
}

---

Related APIs

• General Ledger Accounts
• Deposit Accounts
• Loan Accounts
• Foreign Exchange Transactions

---

Documentation Author: Owa Oluwasegun Tunbosun, Senior Platform Engineer