flutterwave-node-v3

Flutterwave v3 NodeJS Library

Introduction

The Node library provides easy access to Flutterwave for Business (F4B) v3 APIs for your Node apps. It abstracts the complexity involved in direct integration and allows you to make quick calls to the APIs. Available features include:

• Collections: Card, Account, Mobile money, Bank Transfers, USSD, Barter, NQR, Apple Pay, Google Pay.
• Payouts and Beneficiaries.
• Recurring payments: Tokenization and Subscriptions.
• Split payments
• Card issuing
• Transactions dispute management: Refunds and Chargebacks.
• Transaction reporting: Collections, Payouts, Settlements, Refunds, Chargebacks and Transaction timeline.
• Bill payments: Airtime, Data bundle, Cable, Power, Toll, E-bills, and Remitta.
• Identity verification: Resolve bank account, resolve BVN information and generate OTP.

Table of Content

1. Requirements
2. Installation
3. Initialization
4. Usage
5. Testing
6. Debugging Errors
7. Support
8. Contribution guidelines
9. License
10. Changelog

Requirements

1. Flutterwave for business API Keys
2. Node

Installation

To install the library, run this comman in your Node terminal:

npm install flutterwave-node-v3

Initialization

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);

For staging, Use TEST API Keys and for production, use LIVE API KEYS. You can get your process.env.FLW_PUBLIC_KEY and process.env.FLW_SECRET_KEY from the Flutterwave dashboard. Read the requirement section for more information on how to get your API keys.

Usage

1. Collections
2. Tokenization
3. Split payments
4. Scheduled payments
5. Transfers
6. Card Issuing
7. Virtual Account
8. Bill payments
9. Transactions and reporting
10. Beneficiaries
11. Banks
12. Settlements
13. OTP
14. Ebills
15. Misc
16. Virtual Cards

SUBSCRIPTIONS

Get all subscriptions

This describes how to get all subscriptions

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );
const fetchSubscription = async () => {

    try {
        
        const response = await flw.Subscription.fetch_all()
        console.log(response);
    } catch (error) {
        console.log(error)
    }

fetchSubscription();

Fetch subscriptions with customer's email

This describes how to fetch subscriptions made by a single user.

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );
const getSubscription = async () => {

    try {
        const data = {
            "email": "[e-mail]"
        }
        const response = await flw.Subscription.get(data)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

getSubscription();

Cancel a subscription

This describes how to cancel a subscription

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const cancelSubscription = async () => {

    try {
        const payload={
            "id":"3477" //This is the unique id of the subscription you want to cancel. It is returned in the Get a subscription call as data.id
        }
        
        const response = await flw.Subscription.cancel(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

cancelSubscription();

Create order using billing code and product id

Activate a subscription

This describes how to activate a subscription

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const activateSubscription = async () => {

    try {
        const payload={
            "id":"3477" //This is the unique id of the subscription you want to activate. It is returned in the Get a subscription call as data.id
        }
        
        const response = await flw.Subscription.activate(payload)
        console.log(response);
    } catch (error) {
        console.log(error)
    }

}

activateSubscription();

PAYMENT PLANS

Create payment plan

This describes how to create a payment plan

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const createPaymentPlan = async () => {
  try {
    const payload = {
      amount: 500,
      name: 'the olufemi obafunmiso plan 2', //This is the name of the payment, it will appear on the subscription reminder emails
      interval: 'monthly', //This will determine the frequency of the charges for this plan. Could be monthly, weekly, etc.
      duration: 24, //This is the frequency, it is numeric, e.g. if set to 5 and intervals is set to monthly you would be charged 5 months, and then the subscription stops
    };

    const response = await flw.PaymentPlan.create(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

createPaymentPlan();

Get payment plan

This describes how to fetch all payment plans on your account

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const fetchAllPlans = async () => {
  try {
    const response = await flw.PaymentPlan.get_all();
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

fetchAllPlans();

Get a payment plan

This describes how to get a single payment plan

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const fetchPlan = async () => {
  try {
    const payload = {
      id: '5443', //This is the unique ìdof the payment plan you want to fetch. It is returned in the call to create a payment plan asdata.id`
    };

    const response = await flw.PaymentPlan.get_plan(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

fetchPlan();

Update a payment plan

This describes how to update an existing payment plan

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const updatePlan = async () => {
  try {
    const payload = {
      id: '5443', //This is the unique ìdof the payment plan you want to fetch. It is returned in the call to create a payment plan asdata.id`
      name: 'January neighbourhood contribution',
      status: 'active',
    };

    const response = await flw.PaymentPlan.update(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

updatePlan();

Cancel a payment plan

This describes how to cancel an existing payment plan

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const cancelPlan = async () => {
  try {
    const payload = {
      id: '5443', //This is the unique ìd` of the payment plan you want to cancel
    };

    const response = await flw.PaymentPlan.cancel(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

cancelPlan();

SUBACCOUNTS

Create a payment plan

This describes how to create a subaccount on Flutterwave

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const createSubaccount = async () => {
  try {
    const payload = {
      account_bank: '044',
      account_number: '0690000037',
      business_name: 'Eternal Blue',
      business_email: '[e-mail]',
      business_contact: 'Anonymous',
      business_contact_mobile: '090890382',
      business_mobile: '09087930450',
      country: 'NG',
      meta: [
        {
          meta_name: 'mem_adr',
          meta_value: '0x16241F327213',
        },
      ],
      split_type: 'percentage',
      split_value: 0.5,
    };

    const response = await flw.Subaccount.create(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

createSubaccount();

Fetch all subaccounts

This describes how to get all subaccounts

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const fetchAllSubaccounts = async () => {
  try {
    const response = await flw.Subaccount.fetch_all();
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

fetchAllSubaccounts();

Fetch a subaccount

This describes how to fetch a subaccount using the sub-account's ID

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const fetchSubaccount = async () => {
  try {
    const payload = {
      id: '5716',
    };

    const response = await flw.Subaccount.fetch(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

fetchSubaccount();

Update a subaccount

This describes how to update a subaccount

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );


const updateSubaccount = async () => {
  try {
    const payload = {
      id: '3244', //This is the unique id of the subaccount you want to update. It is returned in the call to create a subaccount as data.id
      business_name: 'Xyx lol!',
      business_email: '[e-mail]',
      account_bank: '044',
      account_number: '0690000040',
      split_type: 'flat',
      split_value: '200',
    };

    const response = await flw.Subaccount.update(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

updateSubaccount();

Delete a subaccount

This describes how to delete a subaccount

const Flutterwave = require('flutterwave-node-v3');

const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY  );

const updateSubaccount = async () => {
  try {
    const payload = {
      id: '3244', //This is the unique id of the subaccount you want to update. It is returned in the call to create a subaccount as data.id
    };

    const response = await flw.Subaccount.delete(payload);
    console.log(response);
  } catch (error) {
    console.log(error);
  }
};

updateSubaccount();

Testing

All of the libraries tests are run on Mocha. Available tests include rave.bank.test, rave.beneficiaries.test, rave.bills.test, rave.charge.test, rave.ebills.test, rave.settlements.test, rave.subscriptions.test. They can be run by running the test command in your terminal.

npm run test

Debugging Errors

We understand that you may run into some errors while integrating our library. You can read more about our error messages here. For authorization and validation error responses, double-check your API keys and request. If you get a server error, kindly engage the team for support.

Support

For additional assistance using this library, contact the developer experience (DX) team via email or on slack. You can also follow us @FlutterwaveEng and let us know what you think 😊.

Contribution guidelines

Read more about our community contribution guidelines here

License

By contributing to this library, you agree that your contributions will be licensed under its MIT license. Copyright (c) Flutterwave Inc.

Changelog

1.1.5 | 2023-04-13

Hotfix to hide header information in the library response.

Version changes.

• [FIXED] Removed headers in the response.