Getting started

Authentication

Every call to the API must be authenticated via OAuth client credentials. More information.

During setup, your point of contact will provide you with your client ID and client secret.

Idempotency

For certain POST endpoints, the API uses client-supplied idempotency keys to ensure that requests can be retried safely without performing the same operation twice. Repeated calls to those endpoints with the same idempotency key will return the cached response from the first call. Keys are expected to be set as header parameters with "X-Idempotency-Key".

The recommended approach for interacting with such endpoints is as follows:

1. Create a unique, random key, such as a UUIDv4.

2. Store the intent to call an endpoint along with the generated key in the client database.

3. Flush to disk (e.g. commit an SQL transaction).

4. Perform the call to the endpoint.

This ensures that even if the response from the API to a client gets lost, or the client experiences any sort of outage between steps 3 and 4, the client can always safely retry the same action.

If you already have objects corresponding to tasks in the API in your client-side database, you can use their internal IDs as idempotency keys!

Pagination

Endpoints that list objects will return a paginated response in the following format

{
    'count': 20, 
    'next': 'https://...', 
    'previous': 'https://...', 
    'results': [...]
}

The response will always be sorted by the creation date of the object with the oldest first. Using the next and previous URLs you can move through the different pages. The results array will hold the objects on the current page.

Monetary values

Monetary values are represented as a combination of amount, decimals & currency.

For example, {"amount": "40000000", "decimals": 3, "currency": "EUR"} means "EUR 40,000.000".

Handling documents

The document endpoint can be used to upload documents. Files are uploaded via HTTP multipart. The endpoint will return a document ID that can be used in other requests to refer to that document.

Webhooks

You can also register webhooks so that we can notify your application about events with regards to investments. To use that, please provide your point of contact at Cashlink with the following data:

• URL to be used as the target for webhooks

• OAuth client credentials or bearer authentication token so that we can authenticate at your server.

Webhooks are sent every time the status of an investment changes.

POST <customer-provided URL>

Webhooks are retried until the called endpoint returns a 2xx.

Request

{
  "investment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "ACCEPTED",
  "changed_at": "2020-12-11T14:59:46.716Z"
}