Getting started

Get access

We currently provide two configurations of our API:
  • The production environment. Use this environment to manage contracts for real-world securities. This configuration can be reached at https://main.cashlink-api.de/.
  • The sandbox environment. Intended for testing purposes. This configuration can be reached at https://sandbox.cashlink-api.de/
Please contact us to receive credentials to access the sandbox configuration for testing purposes. After testing is completed you'll be provided with the production credentials.
For security reasons, you should never use the sandbox environment for real-world securities.

Authentication

The API uses OAuth 2.0 for authentication. As part of our on-boarding process for either the sandbox or production environment, you will receive from us a pair of application ID and secret, which can be used to obtain a Client Credentials grant for your user account.
Currently, two scopes are used for read-only and full access to the contract management API: contracts:read and contracts:write.

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.
The recommended approach for interacting with such endpoints is as follows:
  1. 1.
    Create a unique, random key, such as a UUIDv4.
  2. 2.
    Store the intent to call an endpoint along with the generated key in the client database.
  3. 3.
    Flush to disk (e.g. commit an SQL transaction).
  4. 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 Cashlink API in your client-side database, you can use their internal IDs as idempotency keys!

Tasks

There are different types of tasks exposed via the API. For such tasks, a status field represents the current status of the task, which usually starts out as "processing", and transitions to either one of the final states "succeeded" or "failed". In the latter case, the error field will usually also be set, and can provide additional information. Feel free to contact support if it is unclear why a task failed, and the error message is not clear enough on the cause.
In some unlikely cases, a task might enter a final "unknown" state, which means that it is unclear whether the task succeeded or not. If you ever encounter this state, do not retry the task, or you might execute it twice as a result. Instead, the safest reaction is to contact us and let us know about the situation. Over time, we will address all of the situations that can lead to this state so that it should not occur.
Last modified 9mo ago