The Modulr API platform lets developers manage and automate the flow of money by creating bank accounts with Sort Codes and making bank transfers.
The API is based on REST, and uses standard REST features like resource-based endpoints, HTTP verbs, standard responses and authentication.
You can use the Modulr API to:
The base URLs for the Modulr API sandbox environment are:
https://api-sandbox.modulrfinance.com/api-sandbox/ for SANDBOX
You can register on this portal to access the API catalogue and get test a API key.
You will be provided with the Production URL directly during sign up.
The API should be accessed over HTTPS only. Access to the Modulr API is restricted by IP address in Production - your IP addresses will be allow listed before you can start using service.
The API is protected with HMAC authentication, which requires you to calculate a signature based on certain message contents and include that in the Authorization header when making requests.
This value will be unique per request and uses a _keyid (token) and a _hmacsecret value that will both be provided to you. Different keys will be needed for sandbox and live. Instructions on how to calculate the hmac value are below.
Please store keys and secrets securely (particularly any LIVE tokens) as they authenticate all requests as being approved from your organisation. Sandbox environment keys may be time limited to a month for evaluation purposes, please contact us if you require an extension.
HMAC Signing is an access token method that adds another level of security by also sending a signature that identifies the request temporally to ensure that the request is from the requesting user, using a secret key that is never broadcast over the wire. HMAC signing implemented is based on the latest draft of the HMAC request signing standard.
The required steps and a worked example are provided below, please contact us if you require any further assistance.
Sample code is available here.
Set the HTTP “Date” header. The date format must be exactly as per the HTTP-date header specifications - RFC 7231
example header
Date: Mon, 25 Jul 2016 16:36:07 GMT
Set a header with label x-mod-nonce to a unique value per request (see below regarding nonces)
example header
x-mod-nonce: 28154b2-9c62b93cc22a-24c9e2-5536d7d
Create the signature string by concatenating the two headers above separated by a single newline character (note \n and not \r\n).
The header labels should be lowercase within the signature string.
signatureString := strings.ToLower("Date") + ": " + HTTP-date + "\n"
signatureString += strings.ToLower("x-mod-nonce") + ": " + nonce
example signature string
date: Mon, 25 Jul 2016 16:36:07 GMT\nx-mod-nonce: 28154b2-9c62b93cc22a-24c9e2-5536d7d
For a given key of 57502612d1bb2c0001000025fd53850cd9a94861507a5f7cca236882 and hmac secret of NzAwZmIwMGQ0YTJiNDhkMzZjYzc3YjQ5OGQyYWMzOTI=
calculate the hmac-SHA1 signature of the signature string.
Convert the result to a url encoded base64 string.
You should get a value of:
hex = 58132bfd8761cac6e6888124753adfda13fb49f0
url encoded base 64 = WBMr%2FYdhysbmiIEkdTrf2hP7SfA%3D
Set the Authorization header result with the below format
example header
Authorization: Signature keyId="57502612d1bb2c0001000025fd53850cd9a94861507a5f7cca236882",algorithm="hmac-sha1",headers="date x-mod-nonce",signature="WBMr%2FYdhysbmiIEkdTrf2hP7SfA%3D"
The HMAC calculation above uses a date/time value and also implements the recommended clock-skew from the HMAC specification to prevent against replay attacks. It is therefore essential that the sending system has an accurate time (e.g. synchronised with NTP), any significant time error may cause the request to be rejected.
The HMAC calculation above uses a nonce value. This value should be set and be unique per request that you send to our system. This is used in conjunction with the datetime to prevent replay attacks and detect duplicate messages. Suitable nonce examples may be: GUID/UUID, timestamp with a random element to allow for concurrent messages, sequential id’s etc. The only time a nonce should be re-used is if you do not receive a response from our system for an API call (as opposed to an error) and wish to re-try the same message, in which case you should use the same nonce as this will detect whether we have received and processed it.
The API supports idempotency for safely retrying non-idempotent requests without accidentally performing the same operation twice. For example, if a POST request to create a payment fails due to a network connection error, you can retry the request with the same x-mod-nonce to guarantee that only a single payment is created.
To retry a POST request idempotently you can:
x-mod-nonce as the original POST request and x-mod-retry = true This will send back the same response for requests made with the same x-mod-nonce for 24 hours. You cannot use the same nonce with different request parameters.
All endpoints are rate limited (X requests in X seconds), and each API key has a quota.
You can check the returned HTTP headers of any API request to see your current quota status, for example:
x-ratelimit-limit: 30000
x-ratelimit-remaining: 989
x-ratelimit-reset: 1480359249
x-ratelimit-reset uses Unix time to indicate when the quota is due to reset.
Exceeding the quota results in:
403 {"error": "Quota exceeded"}
429 {"error": "Rate limit exceeded"}
The following changes are considered backwards compatible, and should be handled:
message attributes returned by validation failures / other errors
All requests and responses are JSON-formatted. You must pass the standard JSON MIME type (application/json). Other content types will return a 500 error - Content type not supported”
The API uses the following response status codes:
| Status Code | Description |
|---|---|
| 200 | OK - The request has succeeded. The client can read the result of the request in the body and the headers of the response. |
| 201 | Created - The resource was created successfully. The response may have information about the newly created resource. |
| 400 | Bad Request - This is likely caused by validation errors, response body will provide further information. the client should make changes and resubmit, |
| 403 | Forbidden - The client is not allowed to access the resource. Please check your access token is valid and has not expired/ been revoked |
| 404 | Not Found - The requested resource doesn’t exist. Please check documentation and the request. |
| 405 | Method Not Allowed - HTTP method used to access this resource is incorrect, please check documentation |
| 500 | Internal Server Error - Response body may contain further information. You may need to contact Modulr administrator |
Please ensure that your application is able to process additional / new json fields in the body of responses without erroring. Addition of fields in the response will not be considered a breaking change by us.
Errors on the Modulr API will return a 4XX or a 5XX HTTP response code.
Additional information about the error will be returned in the response body, in the format:
{
"field": "id",
"code": "NOTFOUND",
"message": "Customer not found for id: C0200002"
}
Responses for list endpoints (Accounts, Transactions, Beneficiaries) are paginated by default.
The following options are available on all cursor-paginated endpoints:
Paginated results are always returned in an array, and include the following meta data:
{
"size": 15,
"totalSize": 189,
"page": 1,
"totalPages": 13
}
All timestamps are formatted as ISO8601 with timezone information. For API calls that allow for a timestamp to be specified, we use that exact timestamp. These timestamps look something like 2016-06-01T12:00:00.111Z. All times should be sent in UTC time zone.
For endpoints that require dates, we expect a date string of the formatYYYY-MM-DD, where an example would look like 2016-06-01.