Our web services consist of a collection of HTTP RESTful(ish) APIs utilizing JSON format, servers are listening on the following hosts offering secure TLS connections.

Host	Environment	Description
rest.prod.rafiki-api.com	Production	This is the actual live environment, It should only be utilized once your integration has been thoroughly tested in the sandbox environment.
rest.sandbox.rafiki-api.com	Sandbox	You can use this environment to safely test your integration code

Request

Requests employ standard HTTP methods, also known as verbs, including POST, GET, PUT, and DELETE, as outlined in RFC 7231, unless a specific endpoint specifies otherwise.

Every resource detailed in this document provides instructions on the required request structure, encompassing HTTP body, headers, and other essential components.

As a general guideline, any POST or PUT request that includes a body requires the appropriate Content-Type header, indicating the associated MIME serialization strategy (currently supporting only JSON). Without this header, our server will promptly reject the request, responding with an HTTP 400 error.

Response

Each response body will be serialized according to the high level structures outlined below :

✅
HTTP 2xx
Property Type Description
"data" array/object Employed to precisely depict the response data of resources. If a single entity is returned, the data is represented as an object. Conversely, when multiple records need to be listed, the data structure becomes an array.
"meta" object Relevant metadata unique to the resource, such as pagination information and total record count.

❗️
HTTP >= 4xx
Property Type Description
"code" enum Specific error message categorisation (See error codes)
"message" string A human-readable description explaining the reason for the request failure.
"errors" object An object containing key/value pairs to provide a detailed and granular representation of the failure reason.

Status codes

Status codes play a pivotal role in crafting a polished HTTP API design. Irrespective of the architectural approach, responses must consistently align with the semantics of the selected status code.

While the HTTP standard already defines the meaning of each code, this particular section of our documentation aims to provide further clarity on their utilization within the context.

Status	Description
200	This indicates a generic “success”, the server has successfully interpreted the request, executed its job, and responded back accordingly.
201	Successful requests in a create context. E.g. a brand new record was inserted.
202	Upon receiving the request, the server successfully acknowledges and accepts it. However, the actual execution of the work is deferred as it is pushed into a queue. The resource typically provides a dedicated endpoint for polling job update statuses. It is your responsibility to make periodic requests at specified intervals to check for updates.
400	The server couldn't process the request accurately. This could be due to issues such as a malformed JSON object or a missing/mismatched Content-Type header.
401	When attempting to access a protected resource with an API key that is invalid, expired, or blacklisted
402	When trying to transfer money from a wallet that lacks the required balance.
403	When the API key is valid but lacks the necessary permissions to access the resource, or is explicitly prohibited from performing the specified action.
404	The requested resource at the provided URL cannot be found, or any referenced ID within an HTTP request body does not exist.
409	When two or more requests are concurrently using the same idempotency key.
422	Similarly with the 400 status code, the difference here lies in the reason for the error. In this case, the error is due to a validation issue. Although the JSON document's structure is syntactically correct, one or more of its properties may be invalid concerning the specific resource. For instance, it could be a phone number that doesn't adhere to the specified format.
500	An issue occurred on our end. We will have logged the request to identify the root cause and resolve the problem.