Introduction

monoova's 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 at a minimum the client website or back office scope is required to access the api the client website scope is used for user access and will scope all requests to a single users account the back office scope is used for admin access and will require the user id parameter for any request that is not already scoped to another object 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 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 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 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 "pagination" { "item count" 123, "page" 1, "page size" 20 } 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