Introduction
Monoova's FX API is REST based and uses resource-oriented URLs. We use JSON for both both the request and response format.
Authentication
We use Oauth 2.0 to authenticate requests and issue a URL-safe Base64 string Bearer tokens (e.g. bU-lu-whMaoJaC_TQ9vWjXknJPWlBK2XPM45fXX2Bl0) for use within the headers of subsequent requests. These have a lifespan of 24 hours.
Errors
We use the standard HTTP response codes to indicate if a request was a success or failure. You can expect:
- A 200 response code if the request was successful
- A 4XX response code if there was something wrong with your request
- A 5XX reponse code if there was an error on our end
If a 4XX code is returned the response will include some information on why the request failed. The errors will be in a standard format like:
{
"errors": {
"object": [
"Object record had some error."
],
"object.field": [
"Object field was invalid"
]
}
}
If the error can be attributed to a single field, then the error will be returned in that field. The field will be namespaced using .
Names, Codes and IDs
We use internal IDs for some fields, like country, currency and remuneration type. These also have a corresponding human readable names or codes. For countries and currencies we use the ISO standard codes. While either ID or Name/Code are accepted by the API, if both are provided the ID will take precedence.
Idempotency
Our requests support idempotency, using the Idempotency-Key header. This acts as a unique identifier for the request and can be used to prevent duplicate requests.
The key will remain active for 24 hours, and is unique to your user. The result and response code of the original request will be returned for any subsequent requests, including any 500 errors. The exception to this is if the original request is still being processed, then a 409 error will be returned.
While not enforced, it is recommended to use this header for all POST/PUT /PATCH requests. The header is ignored on GET requests as they are already idempotent. We also recommend using a V4 UUID for the key, but any unique string with sufficient entropy will work.
Pagination
Most endpoints that return a list of objects will also support pagination. The pagination parameters are page and page_size, which can be used to control the number of results returned per page and the page of results to return. The default page size is 20, and the maximum page size is 100. If no page is specified, the first page will be returned. The response will include a pagination object with the following properties:
Transaction
Represents an FX conversion/deal/order between two currencies the base currency and counter currency. A base currency amount is sold and counter currency amount is purchased, one of which is provided by the customer and the other is calculated based on the exchange_rate.
Attributes
- status - the current state of the transaction. read only
- status_label - a human readable version of status. read only
- base_currency - This is the currency that the customer wants to sell.
- counter_currency - This is the currency that the customer wants to buy, and send to beneficiaries via payments.
- base_currency_amount - The amount of base_currency being sold.
- counter_currency_amount - The amount of counter_currency being purchased.
- exchange_rate - The exchange rate including any markup. read only
- value_date - This is the date the FX conversion will be executed.
- fees - This is sum of fees across all payments. read only
- receipt_amount - This is the total amount payable by the customer including and markup and payment fees. read only
- receipt_account - This is the account the customer should pay into to settle the transaction. read only
- payments - the payments that have been added to the transaction. read only
- created_date - the date the payment was created. read only
- updated_date - the date the payment was updated. read only