Each investment represents a contract between the issuer of a product and the investor.
There are two ways of creating investments:
- You can use an existing invitation representing an online investment process and create an investment for it (see Invitations)
- If you don't need to track the investment process via invitations, you can directly create investments and store it in the digital securities registry. This process is described here.
For directly creating investments using the investment endpoints you need the following data:
- The ID of the investor the investment is created for
- The ID of the campaign
- The amount the investor is about to invest
As of now, creating and editing products and campaigns via the API is not supported. Campaigns can be created via the Cashlink Studio. The product configuration will be set up via the Cashlink support.
All investments need to be accepted by the issuer before they can be processed further. This can either be done via the Cashlink Studio or programmatically via the API.
If you provide the accepted_at field in the request to create an investment, the issuer doesn't need to perform this action via the Cashlink Studio. If you omit the field the issuer is notified via email that a new investment can be accepted.
Please note that creating accepted investments is not possible if you've used an invitation to create the investment.
The status field of an investment may have one of the following values:
The investment is signed but identification process for the investor is still pending.
The external review process is still pending.
The investment is ready to be accepted by the issuer.
The investment has been accepted by the issuer.
The investment amount has been marked as paid.
The digital securities have been credited to the recipient's wallet.
The KYC/AML check could not be completed successfully due to missing or inconsistent data.
The order has been canceled by the investor.
Order execution has been rejected by the issuer.
The contract has been canceled by the investor during the cancellation period.
The order has been canceled because the payment has not yet arrived on time.
Investments involve signed documents that legally describe the investment contract with the issuer (such as a subscription form). You can access the signed documents via the API's signed documents endpoint at any time.
If you directly create investments via the investments endpoints you can upload documents and add them to the investment via the signed documents endpoint.
Adding signed documents to an investment is not possible if you've used an invitation to create the investment. In this case, all signed documents are created automatically.
Payments of investors for investments can be recorded via the Cashlink Studio. You can - in addition or exclusively - mark investments as paid via the API by adding a payment date to the investment via the investments endpoint after the investment has been accepted by the issuer.
The payment amount is calculated based on the investment amount, agio, disagio and accrued interest. The investment amount and disagio are controlled via the API. The agio and accrued interest is calculated based on the product configuration.
Please note that the accrued interest and therefore the total payable amount can change until the investment has been accepted by the issuer. Show the total payment amount to investors only after the investment has been accepted.
For an investment to settle, it needs the wallet owned by the investor that should be used for this particular investment. Wallets can be associated with an investment directly during creation or they can be added after the initial creation by updating the investment.
The wallet association can be updated as long as the issuance transaction has not been triggered for that investment.
You are able to trigger the credit of digital securities by providing the ID of the investment. The credit can only be triggered if a wallet has been created for the investor and assigned to the investment. Also, the payment amount must has been marked as received.
The credit triggers a minting transaction on-ledger that increases the balance of the wallet associated with the investment with the purchased number of units.
The response contains a status field with the following codes
- processing: The task is created and is currently being executed
- failed: The task could not be completed
- succeeded: The task was completed successfully
- unknown: The task needs manual investigation to determine if the transaction has actually succeeded.
If the task failed because the minting transaction on-ledger could not be executed the error message should indicate that. If the task has succeeded the status of the investment is updated to DELIVERED.
If there is a credit initiated for an investment, it’s not possible to create a new credit for that investment, instead an error is returned to the client.
Using the cancellation endpoint, you can submit the request of an investor that the investment should be aborted. The investment will get the status ABORTED. The investment can be canceled by the investor if the investment is in one of the following states:
If the investment cannot be aborted via API an error will be returned to the client.
In addition, using the Cashlink Studio, there are other ways to cancel an investment in the issuer role. This includes the following
- the KYC/AML process could not be completed in time
- the payment has not been received in full and in time
- the issuer has rejected the investment
These issuer cancellations cannot be submitted via the API, but only via the Cashlink Studio.