biz-sdk

BizBot SDK

Integration to your App

• npm install biz-sdk --save

  const bizSdk = require('biz-sdk')({ ...params });

Params:

• env [string, required] - curent environment. Recommended options are local, dev, stage, prod.

• appToken [string, required] - application token. Contact BizBot in order to get appToken and then to be added to the list of apps when everything ready.

• host [string, required] - current url, used for generating links

• pageTitle [string, required] - default page title.

• showInAppsList [boolean, optional] - default is false. Use it to show your App in list on left menu. Designed to be used on dev environment only.

• appIcon [string, optional] - icon for you app in menu. Check https://feathericons.com/ to choose one.

• logLevel [string, optional] - disable logs except passed. Possible options are all, info, warnings, errors, none. Default is all.

• Example integration:

// index.js
const port = process.env.port || 8127;
const express = require('express');
const http = require('http');
const app = express();
const { routesPublic, routes } = require('./routes');
const sdk = require('biz-sdk');

async function startServer() {
  try {
    // biz-sdk initialization
    const bizSdk = await sdk({
      env: process.env.ENV || 'local',
      host: 'http://localhost:8127',
      pageTitle: 'BIZSDK DEV - BizBot',
      showInAppsList: true,
      appIcon: 'external-link',
      appToken: 'bd7fac74-2a4b-484d-a88e-f6ea4563564b',
    });

    bizSdk.setPublicRoutes(
      routesPublic(bizSdk.templates, bizSdk.helpers.getTranslationStrings)
    );
    bizSdk.setPrivateRoutes(
      routes(bizSdk.templates, bizSdk.helpers.getTranslationStrings)
    );
    app.use(bizSdk.getRoutes());

    const httpServer = http.createServer(app);
    httpServer.listen(port, function() {
      console.log('--== Development environment ==--');
      console.log('Listening on port %d', httpServer.address().port);
      console.log('-== You application config is: ==-');
      console.log(bizSdk.appConfig);
    });
  } catch (err) {
    console.error('Error initializing server', err);
  }
}
startServer();

module.exports = app;

// routes.js
const { Router } = require('express');

const routes = (templates) => {
  const routes = Router();
  routes.get('/', async function (req, res, next) {
    try {
      res.send(await templates.wrapBodyPrivate({
        htmlBody: `<Render your private page here>`,
        locale: req.cookies.lng,
        context: res.locals.context
      }));
    } catch (err) {
      return next(err)
    }
  });
  return routes;
};

const routesPublic = (templates) => {
  const routes = Router();
  routes.get('/public', async function (req, res, next) {
    try {
      res.send(await templates.wrapBodyPublic({
        htmlBody: `<Render your public page here>`,
        locale: req.cookies.lng,
        context: res.locals.context
      }));
    } catch (err) {
      return next(err)
    }
  });
  return routes;
};

module.exports = { routes, routesPublic };

• Run you app

BizSDK frontend methods

• login(cb, options)
  • cb [function, required]
  • options:
    • loaderId [string, optional] - loader element id e.g. auth_loader to become hidden when auth form loaded. Does not make sense if parent is modal
    • requireEmail [boolean, optional] - default is true. Show prompt asking email if user doesn't have it already
• logout(redirect)
  • redirect [string, optional] - redirect url after logging out
• showError(message)
  • message [string, optional] - default is Unexpected error
• showMessage(message, status)
  • message [string, required]
  • status [string, optional] - default is success.
• blockUI() - show loader blocking UI
• unblockUI() - hide loader that blocks UI
• updateNotificationCounter(contextId, userId, companies)
  • contextId [string|number, required] - userId or company orgNumber of current context
  • userId [string|number, required] - current userId
  • companies [array, required] - list of orgNumbers which counters should be checked, e.g. using data user.companies.map(i => i.orgNumber)
• getToken() - get current token

Payment process

• make POST request to /{context}/payments/payment-link where context is personal or company org.number with body:

  • orgNumber [string, optional] - if the payment is on behalf of the company
  • redirectUrl [string, required] - redirect if payment is succeed
  • failedRedirectUrl [string, optional] - redirects if payment is failed or declined by user. By default redirectUrl will be used if value is not passed.
  • vat [number, optional] - VAT tax percentage, default is 25%. Pass 0 if VAT should not be applied to your case.
  • amount [number, required] - in cents excluding VAT, e.g. 1000 for 10 NOK, so total amount is 12.5 NOK incl. VAT. Note that the minimal amount is 3000 because of Stripe's limitations. But some currencies are zero-decimal, then you don't need to multiply values. Check the list at https://stripe.com/docs/currencies#zero-decimal
  • currency [string, optional] - default is NOK.
  • description [string, optional] - text description of selling services or goods. It also will be shown in payment receipt. Default is payment from Ivan Lee ([e-mail]) 10 NOK including VAT 25%
  • items [array, optional] - items to be shown on the payment page. This data will not be included into payment receipt.
    • name [string] - service or good name, e.g Lawyer support for preparing Agreement template
    • price [number|string] - use ready to show format, e.g. 10 NOK or 15 NOK per signer
  • autoCapture [boolean, optional] - default is true. Define if funds are charged immediately, otherwise it should be done manually on Stripe's admin panel which is available for BizBot owner and maintainers only
  • metadata [dict, optional] - any other data you'd like to pass to payment's metadata, e.g. { order_id: 4325, item_name: 'Hamburger' }. Field customer_internal_id will be passed there automatically

• use url from the response and go to this page, e.g. using window.location.href = url;. Note that link is valid for 1 day

• don't forget to implement redirectUrl and failedRedirectUrl to handle payment status changing on your side. Note that intentId query parameter will be added to your successful redirect url. You can get payment details such as receipt url using request GET /payments/intent/:intentId.

Also you can make a refund by calling POST /payments/intent/:intentId/refund - amount [number, optional] - by default it will refund full amount

Subscription process

• ensure that subscription object is created on Stripe Dashboard and there is a valid tax rate entity for the subscription, tax rate should be exclusive

• make POST request to /{context}/payments/subscription-link where context is personal or company org.number with body:

  • orgNumber [string, optional] - if the it's on behalf of the company
  • redirectUrl [string, required] - redirect if subscription payment is succeed
  • failedRedirectUrl [string, optional] - redirects if subscription is failed or declined by user. By default redirectUrl will be used if value is not passed.
  • subscriptionId [string, required] - id of subscription to subscribe on.
  • isTrial [boolean, optional] - default is false.
  • trialPeriod [number, optional] - trial period in days, e.g. 14 for 2 weeks. Takes into account only if isTrial is true.
  • taxRate [string, optional] - id of Stripe taxRate entity. Default is 25% norwegian VAT.
  • trialSubscriptions [array, optional] - list of subscription IDs among which system will try to find and cancel existing trial period and replace it with new subscription. Passed subscriptionId will be pushed to the list in any case. It works the same way for trial subscription. If you'd like the trial to be used once only, check it yourself before this endpoint calling.
  • amount [number, required] - in cents excluding VAT, e.g. 10000 for 10 NOK, so total amount is 12.5 NOK incl. VAT. If isTrial is true then 0 is allowed. Note that there are different minimal amounts for different currencies because of Stripe's limitations, e.g. 3000 NOK. Some currencies are zero-decimal, then you don't need to multiply values. Check the list at https://stripe.com/docs/currencies#zero-decimal
  • currency [string, optional] - default is NOK.
  • description [string, optional] - general text description for subscription. It also will be shown in payment receipt.
  • items [array, optional] - items to be shown on subscription page. This data will not be included into receipt.
    • name [string] - service or good name, e.g Lawyer support, Full access
    • value [number|string|boolean] - e.g. 15 NOK per document or true - will appear as icon ✔ or ❌.
  • metadata [dict, optional] - any other data you'd like to pass to metadata, e.g. { type: 'trial', desc: 'Annual Premium plan' }. Field customer_internal_id will be passed there automatically

• use url from the response and go to this page, e.g. using window.location.href = url;. Note that link is valid for 1 day

• don't forget to implement redirectUrl and failedRedirectUrl to handle subscription status changing on your side