The Bitbond Backend API provides resource endpoints for fetching projects, creating orders and investments and collecting KYC information about the investors.
Creating orders
To create an order the following necessities need to be met:
- The current user needs to be approved. A user is approved automatically when they go through a successful video identification session. When a user is approved the approved_at is set to a non-null value and the approved attribute is set to true.
- An order can only be created for a live project. A live project has its start_date before now and its end_date after.
- The investment terms need to be accepted by a user for the project they want to invest into. The investment terms are accepted by user for a project by successfully creating terms through the investment_terms endpoint.
- The order amount must be greater than the project minimum required investment amount.
Creating users
The locale attribute takes en or de as values, with en being set by default when no value is specified.
When an order is created it will have status new and a unique order code will be generated. The order code will be used as a reference code when sending payments.
Once a new payment comes in, an investment is created. The details of the payment are analysed and the order status changes accordingly to fulfilled, if the amount sent matches the order, underpaid, if the amount sent is lower than the order and overpaid if the amount sent is larger than the order.
An order can also have status cancelled, either by admin action or by user action.
Creating identities
An identity contains personal data about a user. Identities are of many types ranging from individuals, legal representatives, and business owners. They share common attributes described in the Identity model. Generally an individual investor will have one identity that collects information regarding contact details, citizenship and taxes. A business investor will hold one legal representative, that will need to be kyc-ed via video identification, and multiple business owners.
Allocating investments
Once an investor places an order for a project, the details of the bank account they need to send the funds to is revealed.
In order to complete the flow, the investor needs to send the amount designated for the investment to the IBAN provided along with the custom reference code generated. The reference code will be created out of the order code. When the funds reach the Bvdh bank account, a webhook is triggered on Bitbond's side containing the transaction's payload.
The investment is allocated to the user, order and project based on the reference code.
VIDEO IDENTIFICATION FLOW
The video identification process is handled through IDnow, as the video identification provider.
There are a few requirements to be able to start a video identification process:
- an identity needs to be created with contact data and financial information
POST /users/{user_id}/identities
- an address needs to be added for the identity
POST /users/{user_id}/identities/{identity_id}/addresses
- the bank account details need to be filled in for the user
POST /users/{user_id}/bank_accounts
- the identity terms need to be create for the identity
POST /users/{user_id}/identities/{identity_id}/identity_terms
If a video identification session is attempted without the above requirements to be met, an error will be thrown.
There are two steps to perform a video identification session:
- Initiate the session by making a POST request to the
/kyc/identities/{identity_id}/video_identifications
endpoint - Make a GET request to the
/kyc/identities/{identity_id}/video_identifications/{id}
endpoint to verify the video_identifications object has the idnow_id and the redirect_url attributes filled in. A polling mechanism might be needed to fetch the latest data.
When the redirect_url attribute is present, the user can be redirected to their video provider (IDnow) session.
Once the user goes through the video identification session, a webhook is triggered to synchronize data from the video provider (IDnow) to Bitbond. In order to check the status of the video session make a GET request to the /kyc/identities/{identity_id}/video_identifications/{id} endpoints to verify the object has the status attribute filled in.
The video_identifications object can be accessed through the /identities/{id} endpoint as well.
IMPORTANT NOTE:
On staging, the video identification provider (IDnow) does not automatically trigger the webhook to synchronize data on Bitbond's side, therefore the video_identification object status attribute will never be updated.
At the moment, upon going through the video identification session, the user is not redirected back into the investor application. This feature is work in progress.
Webhooks
Webhook URLs can be added through Admin frontend application. API will automatically retry a webhook if the response status code will be anything other than 200
. Webhooks are called with payload in POST request body when the following events happen:
order_created
- Is triggered when the endpoint
POST /users/:user_id/projects/:project_id/orders
is used and after a new order is successfully created.
- Is triggered when the endpoint
order_fulfilled
- Is triggered when the endpoint
POST /admin/investments/:id/allocate
is used and after the investment is successfully allocated in the system. - Is triggered when a bank payment transaction is received by the bank and after new investment is successfully allocated in the system.
- Is triggered when admin user is seeding test environment with test investment data using Asset Manager
Labs
section (does not apply to production)
- Is triggered when the endpoint
order_cancelled
- Is triggered when admin user cancels the order in Asset Manager
investment_received
- Is triggered automatically when investment funds are recieved on BVDH bank account
- Is triggered when admin user manually allocates the investment in the Asset Manager
- Is triggered when admin user is seeding test environment with test investment data using Asset Manager
Labs
section (does not apply to production)
kyc_video_identification_success
- Is triggered after the investor goes through a successful IDNOW KYC process.
- Is tiggered when KYC process is mocked using Asset Manager
Labs
section (does not apply to production)
kyc_approved
- Is triggered after successfull auto-approval process when investor finishes the KYC process.
kyc_rejected
- Is triggered when admin user rejects the investor in Asset Manager
distribution_created
- Is triggered when distribution to Blockchain was processed.
transaction_created
(WIP)
Webhook payloads
order_created
{
event: 'order_created',
order_id: {String} UUID,
user_id: {String} UUID,
project_id: {String} UUID,
}
order_fulfilled
{
event: 'order_fulfilled',
order_id: {String} UUID,
user_id: {String} UUID,
project_id: {String} UUID,
}
order_cancelled
{
event: 'order_cancelled',
order_id: {String} UUID,
user_id: {String} UUID,
project_id: {String} UUID,
}
investment_received
{
event: 'investment_received',
investment_id: {String} UUID,
user_id: {String} UUID,
project_id: {String} UUID,
}
kyc_video_identification_success
{
event: 'kyc_video_identification_success',
user_id: {String} UUID
}
kyc_approved
{
event: 'kyc_approved',
user_id: {String} UUID
}
kyc_rejected
{
event: 'kyc_rejected',
user_id: {String} UUID
}
distribution_created
{
event: 'distribution_created',
order_id: {String} UUID,
user_id: {String} UUID,
project_id: {String} UUID,
}
transaction_created
(WIP)
{
event: 'transaction_created',
transaction_id: {String} UUID,
custody_account_holder_id: {String} UUID,
custody_account_id: {String} UUID,
user_id: {String} UUID
}
This is the documentation for version 0.0.1
of the API. Last update on Dec 15, 2021.
https://<client-subdomain>.bitbond.net/api/v1