Woven Node SDK

A modern, developer-friendly Node.js SDK for the Woven API. Simplifies integration with Virtual Accounts, Direct Debit, Reserved Accounts, Transactions, and Payouts.

Installation

npm install woven-node

For local development:

npm install
npm run build

Quick Start

import { Woven } from "woven-node";

const woven = new Woven({
  apiSecret: process.env.WOVEN_SECRET!,
});

// Start making API calls
const accounts = await woven.virtualAccounts.fetch();

Virtual Accounts

Fetch Virtual Accounts

Retrieve all virtual accounts linked to your integration.

const accounts = await woven.virtualAccounts.fetch();

Create Customer with Virtual Account

Create a customer and assign them a virtual account for receiving payments.

const customer = await woven.virtualAccounts.createCustomer({
  customer_reference: "CUST_12345",
  name: "Jane Doe",
  email: "[email protected]",
  mobile_number: "08012345678",
  expires_on: "2025-12-31",
  use_frequency: 10,
  min_amount: 500,
  max_amount: 100000,
  bvn: "***********",
  nin: "12345678901",
  callback_url: "https://yourapp.com/webhook",
  destination_nuban: "***********",
  meta_data: {
    userId: "user_abc123",
    source: "mobile_app",
  },
});

console.log(customer);

Direct Debit

Create Biller

Register your business as a biller to debit customer accounts.

const biller = await woven.directDebit.createBiller({
  rcNumber: "RC123456",
  name: "Acme Subscriptions Ltd",
  address: "15 Marina Road, Lagos",
  email: "[email protected]",
  phoneNumber: "08************",
});

Fetch Products

Retrieve all direct debit products configured for your account.

const products = await woven.directDebit.fetchProducts();

Create Mandate

Authorize your biller to debit a customer's bank account.

const mandate = await woven.directDebit.createMandate({
  customerId: "CUST_12345",
  productId: "PROD_67890",
  bankCode: "058",
  accountNumber: "***********",
});

Fetch Mandates (Paginated)

Retrieve mandates with pagination support.

const mandates = await woven.directDebit.fetchMandates({
  page: 1,
  pageSize: 20,
});

Get Mandate Status

Check whether a mandate has been approved by the customer.

const status = await woven.directDebit.getMandateStatus({
  mandateCode: "MND_ABC123",
  token: "tk_xyz789",
});

Reserved Accounts

Create Reserved Account

Generate a reserved account for specific use cases.

const reservedAccount = await woven.reservedAccounts.createReservedAccount({
  account_name: "Escrow Account",
  bvn: "***********",
  nin: "12345678901",
});

Fetch Reserved Accounts with Filters

Query reserved accounts with optional filters for vnuban, status, date range, and more.

const accounts = await woven.reservedAccounts.fetchReservedAccounts({
  vnuban: "98**************",
  from: "2025-01-01",
  to: "2025-02-16",
  account_reference: "ACCT_REF_001",
  status: "ACTIVE",
  page: 1,
});

Transactions

List All Transactions

Retrieve transactions with optional filters.

const transactions = await woven.transactions.listTransactions(
  {
    from: "2025-01-01",
    to: "2025-02-16",
    transaction_type: "credit",
    status: "successful",
  },
  1 // page number
);

Verify Transaction

Check the status of a specific transaction using its unique reference.

const transaction = await woven.transactions.verifyTransaction(
  "TXN_ABC123456",
  "2025-02-01",
  "2025-02-16"
);

Get Transactions for a Virtual Account

Retrieve all transactions tied to a specific vNUBAN.

const accountTransactions = await woven.transactions.getVNUBANTransactions(
  "1234567890",
  1
);

Filter by Settlement Status

Get transactions based on their settlement status.

const settledTransactions = await woven.transactions.getBySettlementStatus(
  "SETTLED",
  "2025-01-01",
  "2025-02-16"
);

Payouts

Single Payout

Initiate a one-time payout to a beneficiary.

const payout = await woven.payout.singlePayout({
  amount: 50000,
  beneficiary_account: "***********",
  beneficiary_bank_code: "058",
  beneficiary_name: "John Doe",
  narration: "Payment for services",
  source_account: "98**************",
  unique_reference: "PAY_XYZ123",
});

Scheduled Payout

Schedule a payout for a future date.

const scheduledPayout = await woven.payout.initiateScheduledPayout({
  amount: 25000,
  beneficiary_account: "9***********",
  beneficiary_bank_code: "044",
  schedule_date: "2025-03-01",
  source_account: "1234567890",
});

Bulk Payout (Validate First)

Validate a batch of payouts before initiating.

const validation = await woven.payout.bulkPayoutValidate({
  payouts: [
    {
      amount: 10000,
      beneficiary_account: "1111111111",
      beneficiary_bank_code: "058",
      beneficiary_name: "Alice Smith",
    },
    {
      amount: 20000,
      beneficiary_account: "2222222222",
      beneficiary_bank_code: "044",
      beneficiary_name: "Bob Johnson",
    },
  ],
  source_account: "98**************",
});

Initiate Bulk Payout

Execute a validated bulk payout.

const bulkPayout = await woven.payout.bulkPayoutInitiate({
  reference: "BULK_REF_001",
  source_account: "98**************",
  PIN: "1234",
});

Fetch Payout

Retrieve payout details by reference.

const payoutDetails = await woven.payout.fetchPayout({
  payout_reference: "PAY_XYZ123",
});

Verify Payout

Check the final status of a payout.

const payoutStatus = await woven.payout.verifyPayout({
  payout_reference: "PAY_XYZ123",
});

Funding History

Retrieve the funding history for an account.

const history = await woven.payout.fundingHistoryPayout({
  account_number: "98**************",
  start_date: "2025-01-01",
  end_date: "2025-02-16",
});

List Payouts

Query payouts with optional filters.

const payouts = await woven.payout.listPayout({
  beneficiary_nuban: "***********",
  amount: 50000,
});

Fetch Banks

Get a list of supported banks and their codes.

const banks = await woven.payout.fetchBanks();

Sample

import { Woven } from "woven-node";

const woven = new Woven({
  apiSecret: process.env.WOVEN_SECRET!,
});

async function main() {
  try {
    // Fetch virtual accounts
    const accounts = await woven.virtualAccounts.fetch();
    console.log("Virtual Accounts:", accounts);

    // Create a customer
    const customer = await woven.virtualAccounts.createCustomer({
      customer_reference: "DEMO_CUST_001",
      name: "Demo User",
      email: "[email protected]",
      mobile_number: "08012345678",
      bvn: "***********",
      nin: "12345678901",
    });
    console.log("Customer:", customer);

    // Create a biller
    const biller = await woven.directDebit.createBiller({
      rcNumber: "RC987654",
      name: "Demo Biller",
      address: "Lagos, Nigeria",
      email: "[email protected]",
      phoneNumber: "08************",
    });
    console.log("Biller:", biller);

    // Fetch products
    const products = await woven.directDebit.fetchProducts();
    console.log("Products:", products);

    // List transactions
    const transactions = await woven.transactions.listTransactions();
    console.log("Transactions:", transactions);

    // Initiate a payout
    const payout = await woven.payout.singlePayout({
      amount: 10000,
      beneficiary_account: "***********",
      beneficiary_bank_code: "058",
      beneficiary_name: "Test User",
      source_account: "98**************",
      unique_reference: "TEST_PAY_001",
    });
    console.log("Payout:", payout);

  } catch (error) {
    console.error("Error:", error);
  }
}

main();

Error Handling

Always wrap SDK calls in try/catch blocks to handle errors gracefully.

try {
  const result = await woven.virtualAccounts.fetch();
  console.log(result);
} catch (error) {
  if (error.response) {
    // API returned an error response
    console.error("API Error:", error.response.data);
  } else {
    // Network or other error
    console.error("Error:", error.message);
  }
}

Environment Variables

Create a .env file in your project root:

WOVEN_SECRET=your_api_secret_here

Load it using a package like dotenv:

import dotenv from "dotenv";
dotenv.config();

const woven = new Woven({
  apiSecret: process.env.WOVEN_SECRET!,
});

Best Practices

• Never expose your API secret on the frontend or in version control.
• Log API errors you can use popular logger libraries, for best practice.
• Validate input before making API calls to catch errors early.
• Use pagination Always paginate for eg: when fetching transactions etc.
• Keep your SDK updated to benefit from bug fixes and new features.

TypeScript Support

This SDK is built with TypeScript and includes type definitions for all methods and responses.

import { Woven } from "woven-node";

// IntelliSense will suggest available methods and parameters
const woven = new Woven({ apiSecret: "..." });

Support

For issues, feature requests, or questions:

• GitHub Issues: github.com/woven/woven-node/issues
• Email: [email protected]
• Documentation: docs-v2.woven.finance

License

MIT