veend-sdk/ONLENDING.md

a nodejs package for veend products

### Veendhq SDK

# **Onlending SDK Integration**

## 1. **Loan Products**

> Initialize the SDK with your credentials:
> Call the `loanProducts` method to fetch available loan products:

```javascript
sdk.onlending
  .loanProducts()
  .then((res) => {
    // Handle successful retrieval of loan products
    console.log("Loan Products:", res); // Log or use the retrieved loan products
  })
  .catch((err) => {
    // Handle any errors during retrieval
    console.error("Error:", err);
  });
```

### **Response Handling**

> Upon successful execution, you will receive a response that can be logged or used for further processing. Here's an example response format:

<details>
<summary>🟢 Successful Response</summary>

```javascript
Loan Products: {
  status: 'success',
  data: [
    {
      id: 6,
      name: '12 months',
      shortName: 'twel',
      description: 'Twelve months tenure product',
      currency: [Object],
      nominalAnnualInterestRate: 0,
      interestCompoundingPeriodType: [Object],
      interestPostingPeriodType: [Object],
      interestCalculationType: [Object],
      interestCalculationDaysInYearType: [Object],
      lockinPeriodFrequency: 12,
      lockinPeriodFrequencyType: [Object],
      withdrawalFeeForTransfers: false,
      allowOverdraft: false,
      enforceMinRequiredBalance: false,
      maxAllowedLienLimit: 0,
      lienAllowed: false,
      withHoldTax: false,
      accountingRule: [Object],
      isDormancyTrackingActive: false,
      isProductActive: true,
      productTenure: '12'
    },
    {
      id: 10,
      name: '3 months',
      shortName: 'tree',
      description: 'Three months tenure product',
      currency: [Object],
      nominalAnnualInterestRate: 22,
      interestCompoundingPeriodType: [Object],
      interestPostingPeriodType: [Object],
      interestCalculationType: [Object],
      interestCalculationDaysInYearType: [Object],
      withdrawalFeeForTransfers: false,
      allowOverdraft: false,
      enforceMinRequiredBalance: false,
      maxAllowedLienLimit: 0,
      lienAllowed: false,
      withHoldTax: false,
      accountingRule: [Object],
      isDormancyTrackingActive: false,
      isProductActive: true,
      lockinPeriodFrequency: 3,
      productTenure: '3'
    },
    {
      id: 12,
      name: '6 months',
      shortName: 'Sxmo',
      description: 'Six months tenure fixed savings product',
      currency: [Object],
      nominalAnnualInterestRate: 24,
      interestCompoundingPeriodType: [Object],
      interestPostingPeriodType: [Object],
      interestCalculationType: [Object],
      interestCalculationDaysInYearType: [Object],
      withdrawalFeeForTransfers: false,
      allowOverdraft: false,
      enforceMinRequiredBalance: false,
      maxAllowedLienLimit: 0,
      lienAllowed: false,
      withHoldTax: false,
      accountingRule: [Object],
      isDormancyTrackingActive: false,
      isProductActive: true,
      lockinPeriodFrequency: 6,
      productTenure: '6'
    },
    {
      id: 13,
      name: 'Savings2d',
      shortName: 'S2d',
      description: 'savings product for 2 days',
      currency: [Object],
      nominalAnnualInterestRate: 1,
      interestCompoundingPeriodType: [Object],
      interestPostingPeriodType: [Object],
      interestCalculationType: [Object],
      interestCalculationDaysInYearType: [Object],
      minRequiredOpeningBalance: 10000,
      lockinPeriodFrequency: 2,
      lockinPeriodFrequencyType: [Object],
      withdrawalFeeForTransfers: false,
      allowOverdraft: false,
      overdraftLimit: 0,
      minRequiredBalance: 0,
      enforceMinRequiredBalance: true,
      maxAllowedLienLimit: 0,
      lienAllowed: false,
      nominalAnnualInterestRateOverdraft: 0,
      minOverdraftForInterestCalculation: 0,
      withHoldTax: false,
      accountingRule: [Object],
      isDormancyTrackingActive: false,
      isProductActive: true,
      productTenure: '2'
    }
  ]
}
```

</details>

## 2. **Create Loan**

To integrate the **Veend** SDK for creating a Loan, follow these steps:

1. Initialize the SDK with your credentials.
2. Create a payload object and call the createLoan method to initiate the loan creation:

### Parameters for `loanPayload`

| **Parameter**         | **Type** | **Required** | **Description**                                                                            |
| --------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------ |
| `title`               | `string` | Yes          | The name or title of the loan. Example: `"New Business Loan"`.                             |
| `amount`              | `number` | Yes          | The loan amount in currency units. Example: `500000`.                                      |
| `tenure`              | `string` | Yes          | The duration of the loan in months. Example: `"6"`.                                        |
| `withdrawalFrequency` | `enum`   | Yes          | Specifies when withdrawals can be made. Possible values are `"maturity"` or `"quarterly"`. |
| `callbackUrl`         | `string` | No           | A URL to be notified about loan events. Can be left empty if not needed.                   |

Here is an example:

```javascript
const loanPayload = {
  title: "New Business Loan", // Required
  amount: 500000, // Required
  tenure: "6", // Required
  withdrawalFrequency: "maturity", // Required
  callbackUrl: "", // Optional
};

sdk.onlending
  .createLoan(loanPayload)
  .then((res) => {
    // Handle successful loan creation
    console.log("Loan Created:", res); // You can use the response to show loan details or update the UI
  })
  .catch((err) => {
    // Handle any errors during loan creation
    console.error("Error:", err);
  });
```

### **Response Handling**

> Upon successful execution, you will receive a response that can be logged or used for further processing. Here's an example response format:

<details>
<summary>🟢 Successful Response</summary>

```javascript
Loan Created: {
  data: {
    funding: {
      accountNumber: '8122595530',
      accountName: 'Veend HQ/New Business Loan',
      bankName: 'Wema'
    },
    _id: '677d485cab59b3b22bf2913e'
  },
  status: 'success'
}
```

</details>

## 3. **Get Loan Details**

To integrate the **Veend** SDK for retrieving a loan details, follow these steps:

1. Initialize the SDK with your credentials.
2. Pass in the `loanAccountId` and call the `getLoan` method to fetch the loan details.

Here is an example:

```javascript
sdk.onlending
  .getLoan(loanAccountId) // Replace with the specific loan account ID
  .then((res) => {
    // Handle successful retrieval of loan details
    console.log("Loan Details:", res);
    // You can use the response to display loan details in the UI or for further processing
  })
  .catch((err) => {
    // Handle any errors that occur during the API call
    console.error("Error:", err);
  });
```

### **Response Handling**

> Upon successful execution, you will receive a response that can be logged or used for further processing. Here's an example response format:

<details>
<summary>🟢 Successful Response</summary>

```javascript
Loan Details: {
  _id: '6703a635d74ec48ee17acfb2',
  name: 'Test Email',
  funding: {
    accountNumber: '8124192240',
    accountName: 'Veend HQ/Test Email',
    bankName: 'Wema'
  },
  summary: {
    totalInterestPosted: 6049,
    accountBalance: 106049,
    totalOverdraftInterestDerived: 0,
    interestNotPosted: 0,
    availableBalance: 106049,
    totalEarnings: 6049,
    interestRate: 24,
    totalEstimatedEarning: 11900.75,
    totalDeposits: 100000
  },
  ledger: { account: '6703a635d74ec48ee17acfb2', balance: 0 },
  savingsId: '12479'
}
```

</details>

## 4. **Get Loans**

To integrate the **Veend** SDK for retrieving loans, follow these steps:

1. Initialize the SDK with your credentials.
2. Call the `getLoans` method to fetch the loan data.

Here is an example:

```javascript
sdk.onlending
  .getLoans()
  .then((res) => {
    // Handle successful retrieval of loans
    console.log("Loans:", res); // Log or use the retrieved loan data
  })
  .catch((err) => {
    // Handle any errors during retrieval
    console.error("Error:", err);
  });
```

### **Response Handling**

> Upon successful execution, you will receive a response containing the loan data. This data is divided into three categories: `activeLoans`, `completedLoans`, and `expiredLoans`,that can be logged or used for further processing. Here is the detailed explanation for each category, and an example response format:

#### Active Loans:

These are loans that are currently ongoing. Borrowers are still within their repayment period, and the loan has not yet been fully repaid or marked as completed.

#### Completed Loans:

Loans that have been fully repaid by the borrower and successfully closed. These loans are no longer active and indicate successful repayment history.

#### Expired Loans:

These are loans where the repayment period has lapsed without full repayment being made. They may be considered overdue or delinquent, depending on your system's definitions.

<details>
<summary>🟢 Successful Response</summary>

```javascript
Loans: {
  status: 'success',
  data: {
    activeLoans: [
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object], [Object],
      [Object], [Object]
    ],
    completedLoans: [],
    expiredLoans: [
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object], [Object], [Object], [Object],
      [Object], [Object]
    ]
  }
}
```

</details>