biz-sdk v0.3.27

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 (i@van.com) 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