Currency Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Hold and manage a list of currencies available for the tenant.

Key Features:

  • Create, manage and delete currencies
  • Hold ISO-compliant currency information, including localized names
  • Store exchange rates
  • Calculate exchange between currencies, with high precision

Key Benefits:

  • Display product / service prices in the currency your customer prefers
  • Optionally, exchange currencies, for example if your PSP processes prices in USD only
  • Set prices for different markets (for more information, see the Price Service)
  • Support for an unlimited number of currencies

Currencies

Creating a new currency

Creates a new currency.

The currency consists of a code compliant with the ISO-4217 standard (see https://www.iso.org/iso-4217-currency-codes.html) and a currency name. The name field is localized.

If the Content-Language is set to *, the request body payload should contain localized fields as a map in the key:value pairs format, where key is the language code, and value is the translation.

Required scopes

  • currency.currency_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines language(s) of the payload.

Example: de
Request Body schema: application/json
code
required
string

Currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html).

required
string or object

Currency name. If the Content-Language is set to *, the field should be provided as a map that contains all translations in the key:value pairs format, where key is the language code and value is the translation. If the Content-Language contains a single language, the translation should be passed as a string value. If the Accept-Language header is empty, the translation will be returned in the language defined in the Configuration service as default.

Note: Only the languages defined in the system are allowed to be used here. If a language code not defined in the system is provided, the request will be rejected.

Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409

Conflict.

500

Internal Service Error occurred.

post/{tenant}/currencies
Request samples
application/json
{
  • "code": "USD",
  • "name": "Dollar"
}
Response samples
application/json
{
  • "code": "string"
}

Retrieving all currencies

Retrieves all currencies. You can filter and sort the results by the base currency parameters, for example code and name.

  • If the Accept-Language is set to *, each internationalized field will be returned as a map that contains all translations in a format of key:value pairs, where key is the language code, and value is the translation.
  • If the Accept-Language contains a single language, the translation will be returned as a string value.
  • If the Accept-Language header is empty, the translation will be returned in the language defined in the Configuration service as default.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

query Parameters
pageNumber
integer >= 1
Default: 1

The page number to be retrieved where the size of the pages is specified by the pageSize parameter. The number of the first page is 1.

pageSize
integer >= 1
Default: 60

The number of documents being retrieved on one page.

sort
string

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: sort=name,code:desc
code
string

Returns all currencies which contain the value. For example, for filter value: code=BD the following currencies might be returned: BBD, BDT, SBD, XBD

Example: code=BD
name
string

Filtering by localized fields without language key is possible only when Accept-Language header with correct language is provided or when it is not set at all (in that case default language is taken). For example, when Accept-Language is set to en and the name parameter is equal to name=Doll, then Dollar should be returned. When Accept-Language header is set to * filtering by localized fields is possible only when the fields contain a language key. For example, when Accept-Language is set to * and name parameter is equal to name.en=Doll then Dollar should be returned. 


object

Note: params is not a name of query param. Any localized value field can be taken as an additional filtering parameter.

Additional filtering can be done by each localized field available in API. Filtering by multiple fields is also allowed. In that case, fields are aggregated with the AND logic operator. In the case of string values, the contains approach is taken (filtering by substrings). In the case of boolean and number fields, the equals approach is taken.

Filtering query params example:

  • name.de=Eur - all currencies with name in language de containing Eur are returned.

  • When Accept-Language header is set to *, filtering by localized fields is possible only when fields contains a language key. For example, when Accept-Language is set to '*', the request with parameter name.en=Eur returns all currencies with name.en containing Eur in English.

Example: name.en=Eur
header Parameters
Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If the header value is empty, the language defined in Configuration service is returned. It can be a priority list working as a fallback mechanism.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-Count
boolean
Default: false

The flag indicates if the total count of items should be returned. The total count will be returned as a value of the X-Total-Count header.

Responses
200

OK

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

500

Internal Service Error occurred.

get/{tenant}/currencies
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Retrieving a currency by code
Retrieves a currency by the currency code.


    

  • If the Accept-Language is set to *, each internationalized field will be returned as a map that contains all translations in a format of key:value pairs, where key is the language code and value is the translation.
    • 

  • If the Accept-Language header contains a single language, the translation will be returned as a string value. 
    • 

  • If the Accept-Language header is empty, the translation will be returned in the language defined in the Configuration service as default.
    • 



SecurityOAuth2 
Request 
path Parameters
currencyCode
required
string
Three letter currency code, compliant with the ISO 4217 standard. 


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
header Parameters
Accept-Language
string
The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If the header value is empty, the language defined in Configuration service is returned. It can be a priority list working as a fallback mechanism.


 
 Example:  fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
Responses 
200
The currency has been retrieved successfully


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
Resource has not been found.


500
Internal Service Error occurred.


get/{tenant}/currencies/{currencyCode}
Request samples 
Response samples 
application/json
{
  • "code": "USD",
  • "name": "Dollar"
}
Updating a currency by code
Updates an existing currency. 


The currency code is immutable, so it cannot be changed in this request. For the name field, the following rules are applicable:


    

  • If the Content-Language is set to *, the name field should be represented as a map in thekey:value format, where key is the language code, and value is the translation.
    • 

  • If the Content-Language is set to a specific language, the name parameter should be passed as a string.
    • 





Required scopes


    

  • currency.currency_manage
    • 



SecurityOAuth2 
Request 
path Parameters
currencyCode
required
string
Three letter currency code, compliant with the ISO 4217 standard. 


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
header Parameters
Content-Language
string
The Content-Language request HTTP header defines language(s) of the payload.


 
 Example:  de
Request Body schema: application/json
required
string or object
The currency name. If the Content-Language is set to *, the field should be provided as a map that contains all translations in the format of key:value pairs, where key is the language code and value is the translation. If the Content-Language contains a single language, the translation should be passed as a string value. If the Content-Language header is empty, the default language defined in the Configuration service is taken.


Only the languages defined in the system are allowed to be used here. If a language code not defined in the system is provided, the request will be rejected.


 
required
object (updateMetadata) 
 
Responses 
204
Currency updated


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
Resource has not been found.


409
Conflict.


500
Internal Service Error occurred.


put/{tenant}/currencies/{currencyCode}
Request samples 
application/json
{
  • "name": "Dollar",
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Deleting a currency
Deletes the currency by provided code. If given currency does not exist in the system, the http code 204 will be returned.


Warning
Deleting a currency removes all exchange rates and prices related to the currency. Price removal is an asynchronous operation.





Required scopes


    

  • currency.currency_manage
    • 



SecurityOAuth2 
Request 
path Parameters
currencyCode
required
string
Three letter currency code, compliant with the ISO 4217 standard. 


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
query Parameters
forceDelete
boolean
 Default:  false
 
 Example:  forceDelete=true
Responses 
204
Currency deleted


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Internal Service Error occurred.


delete/{tenant}/currencies/{currencyCode}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Currency exchange
Creating a new exchange rate
Creates a new exchange rate between two currencies. 


Note: Both the source and target currency codes must be compliant with the ISO-4217 standard (see https://www.iso.org/iso-4217-currency-codes.html) and must be defined in the system. 




Required scopes


    

  • currency.currency_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
Request Body schema: application/json
sourceCurrency
required
string
The source currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system.


 
targetCurrency
required
string
The target currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html) defined in the system.


 
rate
required
string
Represents the exchange rate.


The value of the field is represented by a number where the cent part is separated by a comma. For example 1.09. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: 1.091934212


 
Responses 
201
Created


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


409
Conflict.


500
Internal Service Error occurred.


post/{tenant}/exchanges
Request samples 
application/json
{
  • "sourceCurrency": "USD",
  • "targetCurrency": "EUR",
  • "rate": "0.91"
}
Response samples 
application/json
{
  • "code": "string"
}
Retrieving all exchange rates
Retrieves all exchange rates. You can filter and sort the results by the fields, for example source or target currency.




Required scopes


    

  • currency.currency_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
query Parameters
pageNumber
integer  >= 1 
 Default:  1
The page number to be retrieved where the size of the pages is specified by the pageSize parameter.
The number of the first page is 1.


 
pageSize
integer  >= 1 
 Default:  60
The number of documents being retrieved on one page.


 
sort
string
Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.


 
 Example:  sort=name,code:desc
sourceCurrency
string
Returns all exchange definitions for which the source currency matches the pattern. The contains operation is used for the parameter. 


 
targetCurrency
string
Returns all exchange definitions for which the target currency matches the pattern. The contains operation is used for the parameter. 


 
header Parameters
X-Total-Count
boolean
 Default:  false
The flag indicates if the total count of items should be returned. The total count will be returned as a value of the X-Total-Count header.


 
Responses 
200
OK


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Internal Service Error occurred.


get/{tenant}/exchanges
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]
Retrieving an exchange rate by code
Retrieves a currency exchange rate definition by code.




Required scopes


    

  • currency.currency_read
    • 



SecurityOAuth2 
Request 
path Parameters
code
required
string
Identifier of the exchange rate definition. The identifier consists of source currency, underscore, and a target currency.


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
Responses 
200
Exchange rate returned


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
Resource has not been found.


500
Internal Service Error occurred.


get/{tenant}/exchanges/{code}
Request samples 
Response samples 
application/json
{
  • "code": "USD_EUR",
  • "sourceCurrency": "USD",
  • "targetCurrency": "EUR",
  • "rate": "0.91"
}
Updating an exchange rate by code
Updates an existing exchange rate by code. 


Note: The exchange rate code, source, and target currencies are immutable, so they cannot be changed in this request. Only the rate field can be changed.




Required scopes


    

  • currency.currency_manage
    • 



SecurityOAuth2 
Request 
path Parameters
code
required
string
Identifier of the exchange rate definition. The identifier consists of source currency, underscore, and a target currency.


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
Request Body schema: application/json
rate
required
string
Represents the exchange rate.


The value of the field is represented by a number where the cent part is separated by a comma. For example, 1.09. The cent part is not limited just to two digits. A rate with any precision can be returned. For example: 1.09193421


 
required
object (updateMetadata) 
 
Responses 
204
Exchange rate updated


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
Resource has not been found.


409
Conflict.


500
Internal Service Error occurred.


put/{tenant}/exchanges/{code}
Request samples 
application/json
{
  • "rate": "0.91",
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Deleting an exchange rate
Deletes the exchange rate definition by the provided code. If given definition does not exist in the system, the http code 204 will be returned.




Required scopes


    

  • currency.currency_manage
    • 



SecurityOAuth2 
Request 
path Parameters
code
required
string
Identifier of the exchange rate definition. The identifier consists of source currency, underscore, and a target currency.


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: This value must always be provided in lowercase.


 
Responses 
204
Exchange rate deleted


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Internal Service Error occurred.


delete/{tenant}/exchanges/{code}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}