API version: Dec 15, 2021 10:22 am Back to last version

Bitbond Backend API

0.0.1

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.
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)
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.

Base URL

https://<client-subdomain>.bitbond.net/api/v1

Authentication

The API accepts 2 different authentication methods:

Bearer token (http)
Hmac signature (http_api_key)

Bearer token (http)

The API requires a token based authentication with signature (HMAC Signature) confirming every request.
A bearer token will be provided by Bitbond that will need to be included in the 'Authentication' header for each request to the server, along with an HMAC 'X-Signature' header. The HMAC signature will be used to verify the authenticity of the sender and the integrity of the request in transit.

Headers

To authorize API access this header needs to be added to the request.

Authorization: Bearer [token]
X-Signature: [HMAC signature]

Hmac signature (http_api_key)

Secret are used to build HMAC-SHA1 signatures on a client side.

Signature generation pseudo code:

/**
* HMAC a hashing function using SHA1 algorythm
* @param   {String} secret     The secret used to hash the message
* @param   {String} message    Message to be hashed
* @return  {Bin}               Binary digest
*/
HMAC = func(secret, message)

/**
* signatureKey returns derived key
* @param   {String} secret     The secret from tokens key/secret pair.
* @param   {String} date       UTC request date in YYYY-MM-DD format
* @param   {String} method     Request method POST, GET, DELETE etc
* @param   {String} path       Request path, e.g. /api/v1/access_tokens
* @return  {Bin}               Derived key used to generate payload signature
*/
signatureKey = func(secret, date, method, path) {
    HMAC(HMAC(HMAC("bitbond" + secret, date), method), path)
}

/**
* signature returns request signature
* @param   {String} key        The secret from tokens key/secret pair.
* @param   {String} payload    Raw request body
* @return  {String}            Request signature
*/
signature = func(key, payload) {
    HMAC(key, payload).toString()
}

Example in JavaScript:

import hmacSHA1 from 'crypto-js/hmac-sha1';

let generateSigningKey = (secret, dateStamp, method, path) => {
  let key = hmacSHA1(dateStamp, `bitbond${secret}`)
  key = hmac(method, key)
  key = hmac(path, key)
  return key
}

let dateStamp = (new Date()).toISOString().substring(0, 10)
let method = request.method
let path = request.url.getPathWithQuery()
let body = request.body && request.body.raw || ''
let signingKey = generateSigningKey(secret, dateStamp, method, path)
let signature = hmacSHA1(body, signingKey).toString()

addresses

Fetch the address of a personal investor

GET /users/{user_id}/kyc/identities/{identity_id}/addresses

Fetch the address of a personal investor, a legal representative or a business owner entity

Path parameters

user_id Required / string

User id
identity_id Required / string

Identity or Legal representative id

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required

Body Required