js-lib-8p v0.2.0

8Pay JavaScript library

This module provides a way to programmatically interact with 8Pay's smart contracts running on the Ethereum blockchain.

Installation

This is a Node.js module available through the npm registry.

Before installing, download and install Node.js.

Installation is done using the npm install command:

$ npm install 8pay

Usage

This module uses web3 under the hood, which is the most popular library used to interact with the Ethereum blockchain.

To keep things familiar with web3 users we decided to follow the same strucure when sending transactions but adds additional functionalities.

To get started, import the module and connect to the desired network and provider (Infura, Metamask, or any web3 compatible provider):

const Web3 = require('web3');
const EightPay = require('8pay');

const provider = 'https://rinkeby.infura.io/v3/<your-api-key>';
const web3 = new Web3(provider);

const eightPay = new EightPay(web3, 'rinkeby');

Sending transactions

There are two ways to sign a transaction before broadcasting it to the blockchain:

• Using unlocked account (e.g. Metamask, ganache-cli)

 eightPay.fixedRecurring.bill(planId, subscriptions)
    .send({ from: account })

• With privateKey

eightPay.fixedRecurring.bill(planId, subscriptions)
    .send({ privateKey: '0x32df7......' })

Options

The send methods accepts the same options available in web3.

Events

The following events are emitted when sending a transaction: transactionHash, receipt, confirmation and error.

const receipt = await eightPay.fixedRecurring.bill(planId, subscriptionIds)
    .send({ from: account })
    .on('transactionHash', hash => {})
    .on('receipt', receipt => {})
    .on('confirmation', confirmation => {})
    .on('error', error => {})

Functionalities

Here is the list of all the available methods for each billing model.

Fixed Recurring

Bill

Bills users subscribed to a specific plan.

Caller: Anyone. Given that this function can only bill expired subscriptions, no harm can be done by leaving it callable by anyone. This behaviour allows for future services implementations.

Parameters:

• planId - id of the plan
• subscriptionIds - array of subscription on-chain ids

const planId = '0x57b2059e526841b3dfd964144513359c9fcfd6d91040b6c47f589c1e032b6bf4';
const subscriptionIds = ['0xe63ba761797e289076f80a7c0916a31740684806aaf507da85f81ee785fec6ba'];

const receipt = await eightPay.fixedRecurring.bill(planId, subscriptionIds)
    .send({ from: account })

Terminate

Forcefully cancels subscriptions linked to a plan.

Caller: plan's admin or operational accounts with termination permission

Parameters:

• planId - id of the plan
• subscriptionIds - array of subscription on-chain ids

const planId = '0x57b2059e526841b3dfd964144513359c9fcfd6d91040b6c47f589c1e032b6bf4';
const subscriptionIds = ['0xe63ba761797e289076f80a7c0916a31740684806aaf507da85f81ee785fec6ba'];

const receipt = await eightPay.fixedRecurring.unsubscribe(planId, subscriptionIds)
    .send({ from: account })

Variable Recurring

Bill

Bills users subscribed to a specific plan.

Caller: plan's admin or operational accounts with billing permission

Parameters:

• planId - id of the plan
• subscriptionIds - array of subscription on-chain ids
• amounts - array of amounts to charge for each subscription

const planId = '0x57b2059e526841b3dfd964144513359c9fcfd6d91040b6c47f589c1e032b6bf4';
const subscriptionIds = ['0xe63ba761797e289076f80a7c0916a31740684806aaf507da85f81ee785fec6ba'];
const amounts = [eightPay.utils.addDecimals(10, '8PAY')];

const receipt = await eightPay.variableRecurring.bill(planId, subscriptionIds, amounts)
    .send({ from: account })

Terminate

Forcefully cancels subscriptions linked to a plan.

Caller: plan's admin or operational accounts with termination permission

Parameters:

• planId - id of the plan
• subscriptionIds - array of subscription on-chain ids

const planId = '0x57b2059e526841b3dfd964144513359c9fcfd6d91040b6c47f589c1e032b6bf4';
const subscriptionIds = ['0xe63ba761797e289076f80a7c0916a31740684806aaf507da85f81ee785fec6ba'];

const receipt = await eightPay.variableRecurring.unsubscribe(planId, subscriptionIds)
    .send({ from: account })

On Demand

Bill

Bills users subscribed to a specific plan.

Caller: plan's admin or operational accounts with billing permission

Parameters:

• planId - id of the plan
• subscriptionIds - array of subscription on-chain ids
• amounts - array of amounts to charge for each subscription

const planId = '0x57b2059e526841b3dfd964144513359c9fcfd6d91040b6c47f589c1e032b6bf4';
const subscriptionIds = ['0xe63ba761797e289076f80a7c0916a31740684806aaf507da85f81ee785fec6ba'];
const amounts = [eightPay.utils.addDecimals(10, '8PAY')];

const receipt = await eightPay.onDemand.bill(planId, subscriptionIds, amounts)
    .send({ from: account })

Terminate

Forcefully cancels subscriptions linked to a plan.

Caller: plan's admin or operational accounts with termination permission

Parameters:

• planId - id of the plan
• subscriptionIds - array of subscription on-chain ids

const planId = '0x57b2059e526841b3dfd964144513359c9fcfd6d91040b6c47f589c1e032b6bf4';
const subscriptionIds = ['0xe63ba761797e289076f80a7c0916a31740684806aaf507da85f81ee785fec6ba'];

const receipt = await eightPay.onDemand.unsubscribe(planId, subscriptionIds)
    .send({ from: account })

Accounts

The accounts utility can be used to obtain an account object from a private key or a mnemonic. The account object has two properties: address and privateKey.

const privateKey = '<your-private-key>';
const account = eightPay.accounts.fromPrivateKey(privateKey);
// OR
const mnemonic = '<mnemonic>';
const mnemonicIndex = 0;
const account = eightPay.accounts.fromMnemonic(mnemonic, mnemonicIndex);

console.log(account.address);
console.log(account.privateKey);

Utils

To help in parsing amount from and to ethereum decimals, you can use addDecimals and parseDecimals methods.

const ethAmount = eightPay.utils.addDecimals(1, 'ETH') // 1000000000000000000
const amount = eightPay.utils.parseDecimal(ethAmount, 'ETH') // 1