Currencies Configuration
  • 27 Jun 2022
  • 6 Minutes To Read
  • Dark
    Light
  • PDF

Currencies Configuration

  • Dark
    Light
  • PDF

Early Access Feature
If you would like to request early access to this feature, please get in touch with your Mambu Customer Success Manager to discuss your requirements. For more information, see Mambu Release Cycle - Feature Release Status.

Currencies are used to configure the currency type associated with monetary values in Mambu. For more information, see Currencies.

With Configuration as Code (CasC), you may batch configure your currencies configuration via the API using YAML. For general information on CasC, see Configuration as Code Overview.

Please be Aware

The CasC for currencies feature currently supports fiat currencies only. If you have access to cryptocurrencies or non-traditional currencies, they are not currently supported by CasC. For more information about crypotcurrencies and non-traditional currencies, see Currencies.

API Operations

CasC for currencies supports two operations.

Action Endpoint Description
GET /configuration/currencies.yaml Get current currencies configuration.
PUT /configuration/currencies.yaml Write a new currencies configuration to Mambu.
Please Note

If you PUT a configuration to Mambu, any current configuration settings not included in the new YAML configuration will be deleted. PATCH requests are not currently supported.

Requests

For general information on CasC requests such as authentication and required headers, see Configuration as Code Overview.

The following section shows sample requests using curl and basic authentication. For all examples, replace TENANT_NAME with your actual tenant name.

GET configuration

You can get your current currencies configuration either for all time periods, from a specified start date.

Retrieving all rates for all time periods

curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/currencies.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'

{auth} is the base-64-encoded value of username:password. For more information, see Authentication in our API reference.

Retrieving rates for specified time periods

To retrieve rates from a specific start date, use the startDate parameter in the YYY-MM-DD format. The midnight value of the configuration start date is determined by your organization's timezone.

curl -X GET 'https://TENANT_NAME.mambu.com/api/configuration/currencies.yaml?startDate=2019-01-02' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Authorization: Basic {auth}'

{auth} is the base-64-encoded value of username:password. For more information, see Authentication in our API reference.

Sample response

The following example shows a reply for a query with a start date value of the 2nd of January, 2019.

---
startDate: "2019-01-02"
baseCurrency:
  code: "USD"
  name : "US Dollars"
  symbol: "$"
  symbolPosition: "BEFORE_NUMBER"
  digitsAfterDecimal: 2
  type: "FIAT_CURRENCY"
foreignCurrencies:
  - currency:
      code: "EUR"
      name: "Euro"
      symbol: "€"
      symbolPosition: "AFTER_NUMBER"
      digitsAfterDecimal: 2
      type: "FIAT_CURRENCY"
    accountingRates:
      - startDate: "2018-01-02T00:00+11:00"
        rate: 100
      - startDate: "2020-01-02T00:00+11:00"
        rate: 100
    exchangeRates:
      - startDate: "2018-01-02T00:00+11:00"
        buyRate: 100
        sellRate: 110
      - startDate: "2020-01-02T00:00+11:00"
        buyRate: 200
        sellRate: 210     

Note that in this example the returned accounting and exchange rates have a start date of the 2nd of January, 2018, and that this date falls before our specified query start date of the 2nd of January, 2019, as shown in the first line.

This is because the returned values for accounting and exchange rates begin with the value that was in effect at the time of the query startDate. That value is reported along with its start date, which is the date the rate was added to Mambu. See the timeline below for an illustration.

Timeline showing start date is before start date specified in parameter.

If you specify a query startDate value that lies before the start date of a foreign currency exchange or accounting rate - that is, before the currency was added to Mambu - you will receive a reply that begins with the earliest exchange or accounting rate that was entered into Mambu along with its start date. That date will be after the specified query startDate. See the timeline below for an illustration:

Timeline showing start date is after start date specified in parameter.

PUT configuration

curl -X PUT 'https://tenanturl.mambu.com/api/configuration/currencies.yaml' \
-H 'Accept: application/vnd.mambu.v2+yaml' \
-H 'Content-Type: application/yaml' \
-H 'Authorization: Basic {auth}' \
--data-binary @currencies.yaml

“@currencies.yaml” represents the absolute path of the file on your device.

Use “--data-raw” if you want to specify the YAML body inline.

Configuration body example

startDate: "2019-01-02" 
baseCurrency:
  code: "USD"
  name : "US Dollars"
  symbol: "$"
  symbolPosition: "BEFORE_NUMBER"
  digitsAfterDecimal: 2
  type: "FIAT_CURRENCY"
foreignCurrencies:
  - currency:
      code: "EUR"
      name: "Euro"
      symbol: "€"
      symbolPosition: "AFTER_NUMBER"
      digitsAfterDecimal: 2
      type: "FIAT_CURRENCY"
    accountingRates:
      - startDate: "2019-01-02T00:00+11:00"
        rate: 100
      - startDate: "2019-01-05T00:00+11:00"
        rate: 100
    exchangeRates:
      - startDate: "2019-01-02T00:00+11:00"
        buyRate: 100
        sellRate: 110
      - startDate: "2020-06-29T00:00+10:00"
        buyRate: 200
        sellRate: 210  

Attributes

Name Type Description Required
startDate String Date starting from which the configuration is applied and/or retrieved, based on the organization timezone. Can be null if all the data is retrieved or updated.
baseCurrency Currency configuration Model representing the currency configuration.
foreignCurrencies Foreign Currency Configuration List of all foreign currencies. Can be empty. Ordered by currency code, ascending.

Base currency attributes

Name Type Description Required
code String The unique currency code.
name String The currency name.
symbol String The currency symbol.
symbolPosition String The position of the currency symbol. The options are BEFORE_NUMBER and AFTER_NUMBER.
digitsAfterDecimal String Number of digits that are supported for given currency.
type String The type of currencies. Only FIAT_CURRENCY is currenlty supported.

Foreign currency attributes

Name Type Description Required
currency Currency configuration Model representing the currency configuration.
currency.code String The unique currency code.
currency.name String The currency name.
currency.symbol String The currency symbol.
currency.symbolPosition String The position of the currency symbol.
currency.digitsAfterDecimal String Number of digits that are supported for given currency.
currency.type String The type of currencies. Only FIAT_CURRENCY is currenlty supported.
accountingRates Accounting Rate Configuration The accounting rate for the current currency and base currency. Ordered by start date, ascending. Required only if Accounting in Multicurrency is enabled, not required otherwise.
accountingRates.startDate String The accounting rate will apply starting with this date.
accountingRates.rate Number The accounting rate.
exchangeRates Exchange rate configuration The exchange rate for the current currency and base currency. Ordered by start date, ascending.
exchangeRates.startDate String The exchange rate applies starting with this date.
exchangeRates.buyRate Number The buy exchange rate.
exchangeRates.sellRate Number The sell exchange rate.

Replies

If you do not receive a 200 OK response then fix any validation errors and make another PUT request until you receive a 200 OK response.

Please Note

If you PUT a valid YAML configuration to the API and you do not receive a 200 OK status code within 60 seconds, you may receive a 504 Gateway Timeout status code. We expect all responses to be below 60 seconds.

If you encounter this issue, please contact us through Mambu Support so we can investigate it.

Validations

Name Validation
name Must have a maximum length of 256 characters.
symbol Must have a maximum length of 4 characters.
code The code can not be changed at update. It has the initial value set when the tenant was first created or provisioned.
accountingRates List cannot be empty if Accounting in Multicurrency is enabled. Existing accounting rates can not be edited or removed, they must be left as they were retrieved. Only new rates can be added.
accountingRates.startDate It must be greater than the previous rate start date. If it’s the first rate, it’s start date is compared with the configuration start date.
accountingRates.rate Must be between 0 and 2000000000000000
exchangeRates List cannot be empty. Existing accounting rates can not be edited or removed, they must be left as they were retrieved. Only new rates can be added.
exchangeRates.startDate It must be greater than the previous rate start date. If it’s the first rate, it’s start date is compared with the configuration start date.
exchangeRates.buyRate It must be between 0 and 2000000000000000
exchangeRates.sellRate It must be between 0 and 2000000000000000. It must be greater than the buy rate.

Warnings

You will receive a list of warnings if you try to delete a foreign currency which is in use because those cannot be deleted.

You will also receive warnings if a foreign currency does not have an accounting rate specified or an exchange rate specified.

Please Note

Unlike the Mambu UI, you cannot omit the exchange rate or accounting rate when adding or editing a currency when making API requests.


Was This Article Helpful?