Chimoneyjs

Chimoneyjs is a js wrapper for Chimoney

• Account
• Info
• Payout
• Mobile Money
• Wallet
• Sub-Account
• Redeem

Getting Started

• Register with Chimoney

• Request for API KEY from support

• set Your "CHIMONEY_API_KEY" environment variable You can use a .env file as shown below to set your API key

  CHIMONEY_API_KEY = "YOUR API KEY"

Installing

- npm install chimoneyjs

Usage

Using chimoneyjs

There are two ways of setting your API key.

• You can export it as an environment variable as mentioned above (recommended)
• You can pass it as an argument when initialising chimoney

// Initialise chimoney without api key (recommended)
const chimoney = require("chimoneyjs")();

// Initialise chimoney with api key
require("dotenv").config();
const chimoney = require("chimoneyjs")(process.env.API_KEY);

The issue with the latter is that you'd have to initialise your api key whenever you import the package. For this reason we recommend exporting your apiKey as an environment variables

Full Example

const { account, wallet } = require("chimoneyjs")();

account
  .getAllTransactions()
  .then((response) => console.log(response)) // model of response {status:"success", data:...}
  .catch((err) => console.log(err));

API

Every function returns the response body as received from the Chi Money API. Ideally each response is an object with status and data properties. status always has a value of "success". For more information about the responses visit ChiMoneyAPI documentation

// sample response
{
  status: "success",
  data: {
        amountInUSD: "20",
        destinationCurrency: "NGN",
        amountInDestinationCurrency: 11000,
        validUntil: "2022-10-18T22:46:20.616Z"
      }
}

Using the Account API

const { account } = require("chimoneyjs")();

getTransactionsByIssueID(issueID, subAccount)

For more information visit Chi Money API

This function gets all transactions by IssueID

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | issueID | string | | The issueID of the transaction | | subAccount | string | null | The subAccount of the transaction |

getAllTransactions(subAccount)

For more information visit Chi Money API

This functions returns a list of transactions by account

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | subAccount | string | null | The subAccount of the transaction |

accountTransfer(receiver, amount, wallet, subAccount)

For more information visit Chi Money API

This transaction transfers funds from wallet to receiver

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | receiver | string | | The receiver of the funds | | amount | number | | The amount of funds | | wallet | string | | The wallet to be transfered from | | subAccount | string | null | The subAccount of the transaction |

deleteUnpaidTransaction(chiRef, subAccount)

For more information visit Chi Money API

This function deletes an unpaid transaction

Returns: The response from the ChiMoney API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | chiRef | string | | The ID of the transaction | | subAccount | string | null | The subAccount of the transaction |

getTransactionByID(transctionId, subAccount)

For more information visit Chi Money API

This function gets a transaction by ID

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ------------ | ------------------- | ----------------- | --------------------------------- | | transctionId | string | | The ID of the transaction | | subAccount | string | null | The subAccount of the transaction |

Using the Info API

const { info } = require("chimoneyjs")();

airtimeCountries()

For more information visit Chi Money API

This function returns a list of countries that support airtime

Returns: The response from Chi Money API

assets()

For more information visit Chi Money API

This function returns a list of supported assets

Returns: The response from the Chi Money API

banks(country)

For more information visit Chi Money API

Returns: The response from Chi Money API

| Param | Type | Default | Description | | ------- | ------------------- | --------------------------- | ----------------------------------------- | | country | string | "NG" | The country code, default is Nigeria(NG). |

localAmountInUSD(originCurrency, amountInOriginCurrency)

For more information visit Chi Money API

This function returns the equivalent of local currency in USD

Returns: The response from the Chi Money API

| Param | Type | Description | | ---------------------- | ------------------- | --------------------------------- | | originCurrency | string | The source currency | | amountInOriginCurrency | number | The amount in the origin currency |

mobileMoneyCodes()

For more information visit Chi Money API

This function returns a list of supported mobile money codes

Returns: The response from the Chi Money API

usdInLocalAmount(destinationCurrency, amountInUSD)

For more information visit Chi Money API

This function returns the equivalent of USD in the destination currency.

Returns: The response from the Chi Money API

| Param | Type | Description | | ------------------- | ------------------- | ------------------------ | | destinationCurrency | string | The destination currency | | amountInUSD | number | The amount in USD |

Using the MobileMoney API

const { mobileMoney } = require("chimoneyjs")();

getAllTransactions(subAccount)

For more information visit Chi Money API

This function returns an array of all mobile money(momo) transactions

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | subAccount | string | null | The subAccount of the transaction |

makePayment(paymentDetails, subAccount)

For more information visit Chi Money API

This function enables a user to make payment with mobile money (momo)

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | -------------- | ------------------- | ----------------- | ---------------------------------------------- | | paymentDetails | Object | | An object with the appropriate payment details | | subAccount | string | null | The subAccount of the transaction |

verifyPayment(id, subAccount)

For more information visit Chi Money API

This function enables the user to verify mobile money payments

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | id | string | | The transaction id | | subAccount | string | null | The subAccount of the transaction |

Using the Payouts API

const { payouts } = require("chimoneyjs")();

airtime(airtimes, subAccount)

For more information visit Chi Money API

This function handles the Chi Money airtime API.

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ------------------------------------------------- | | airtimes | Array.<object> | | An array of object containing the airtime details | | subAccount | string | null | The subAccount of the transaction |

Example

const airtimes = [
  {
    countryToSend: "Nigeria",
    phoneNumber: "+2348123456789",
    valueInUSD: 3,
  },
];

bank(banks, subAccount)

For more information visit Chi Money API

This function handles the bank API

Returns: The response from Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ----------------------------------------------- | | banks | Array.<object> | | An array of objects containing the bank details | | subAccount | string | null | The subAccount of the transaction |

Example

const banks = [
  {
    countryToSend: "Nigeria",
    account_bank: "044",
    account_number: "0690000031",
    valueInUSD: 1,
    reference: "1234567890",
  },
];

chimoney(chimoneys, subAccount)

For more information visit Chi Money API

This functions handles the chimoney API

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ---------------------------------------------------- | | chimoneys | Array.<object> | | An array of objects containing the chimoney details. | | subAccount | string | null | The subAccount of the transaction |

Example

const chimoneys = [
  {
    valueInUSD: 1,
    email: "[email protected]",
    twitter: "@tester",
  },
];

mobileMoney(momos, subAccount)

For more information visit Chi Money API

This function handles mobile money API

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ------------------------------------------------------- | | momos | Array.<object> | | An array of objects containing the mobile money details | | subAccount | string | null | The subAccount of the transaction |

Example

const momos = [
  {
    countryToSend: "Nigeria",
    phoneNumber: "+2348123456789",
    valueInUSD: 1,
    reference: "1234567890",
  },
];

giftCard(giftCards, subAccount)

For more information visit Chi Money API

This function handles the gift card API

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ---------------------------------------------------- | | giftCards | Array.<object> | | An array of objects containing the gift card details | | subAccount | string | null | The subAccount of the transaction |

Example

const giftCards = [
  {
    email: "[email protected]",
    valueInUSD: 1,
    redeemData: {
      productId: "3",
      countryCode: "NG",
      valueInLocalCurrency: 1000,
    },
  },
];

status(chiRef, subAccount)

For more information visit Chi Money API

This function handles the status API

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | chiRef | string | | The Chi Money reference | | subAccount | string | null | The subAccount of the transaction |

initiateChimoney(chimoneys, crypto_payments, subAccount)

For more information visit Chi Money API

This function handles the initiate chimoney API

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ------------------- | --------------------------------- | ------------------ | ---------------------------------------------------------- | | chimoneys | Array.<object> | | An array of objects containing the chimoney details | | turnOffNotification | boolean | false | If set to true turns of email notification for this payout | | crypto_payments | Array.<object> | | An array of objects containing the crypto payment details | | subAccount | string | null | The subAccount of the transaction |

Example

const chimoneys = [
  {
    valueInUSD: 1,
    email: "[email protected]",
    twitter: "@tester",
  },
];

Example

const crypto_payments = [
  {
    xrpl: {
      address: "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
      issuer: "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
      currency: "XRP",
    },
  },
];

Using the Redeem API

const { redeem } = require("chimoneyjs")();

airtime(chiRef, phoneNumber, countryToSend, meta, subAccount)

For more information visit Chi Money API

This function allows you to redeem airtime transactions

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ------------- | ------------------- | ----------------- | ------------------------------------- | | chiRef | string | | The Chi reference | | phoneNumber | string | | Phone number | | countryToSend | string | | Country to send to | | meta | object | | Any data to be sent along the request | | subAccount | string | null | The subAccount of the transaction |

any(chiRef, redeemData, [meta], subAccount)

For more information visit Chi Money API

This function allows you to redeem any transaction (chimoney, momo, airtime)

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ---------------------------------------------------------------------------------------- | | chiRef | string | | The Chi reference | | redeemData | array.<object> | | Any array of objects containing data needed to redeem the transaction. see example below | | [meta] | object | {} | Any data to be sent along with the request. defaults to an empty object | | subAccount | string | null | The subAccount of the transaction |

Example

const redeemData = [
  {
    countryCode: "NG",
    productId: 1,
    valueInLocalCurrency: 1000,
  },
];

chimoney(chimoneys, subAccount)

For more information visit Chi Money API

This function allows you to redeem chimoney

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | --------------------------------- | ----------------- | ------------------------------------------------- | | chimoneys | array.<object> | | An array of objects containing the redeem details | | subAccount | string | null | The subAccount of the transaction |

Example

const chimoneys = [
  {
    field: "data",
  },
];

giftCard(chiRef, redeemOptions, subAccount)

For more information visit Chi Money API

This function allows you to redeem giftcard

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ------------- | ------------------- | ----------------- | ----------------------------------------- | | chiRef | string | | The Chi reference | | redeemOptions | object | | The data needed to redeem the transaction | | subAccount | string | null | The subAccount of the transaction |

mobileMoney(chiRef, redeemOptions, subAccount)

For more information visit Chi Money API

This function allows you to redeem mobile money (momo)

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ------------- | ------------------- | ----------------- | ----------------------------------------- | | chiRef | string | | The Chi reference | | redeemOptions | object | | The data needed to redeem the transaction | | subAccount | string | null | The subAccount of the transaction |

Using the SubAccount API

const { subAccount } = require("chimoneyjs")();

create(name, email)

For more information visit Chi Money API

This function creates a new subAccount with the provided name and email

Returns: The response from the Chi Money API

| Param | Type | Description | | ----- | ------------------- | ------------------------------- | | name | string | Name to give the new subAccount | | email | string | Email |

deleteAccount(id)

For more information visit Chi Money API

This function deletes the subAccount with the given id

Returns: The response from the Chi Money API

| Param | Type | Description | | ----- | ------------------- | ------------------------ | | id | string | The id of the subAccount |

getDetails(id)

For more information visit Chi Money API

This function gets the details of the subAccount with the associated id

Returns: The response from the Chi Money API

| Param | Type | Description | | ----- | ------------------- | ------------------------ | | id | string | The id of the subAccount |

getAll()

For more information visit Chi Money API

This function returns all the subAccounts associated with a user

Returns: The response from the Chi Money API

Using the Wallet API

const { wallet } = require("chimoneyjs")();

list(subAccount)

For more information visit Chi Money API

This function gets all the wallets associated with a user

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | subAccount | string | null | The subAccount of the transaction |

details(id, subAccount)

For more information visit Chi Money API

This function gets the details associated with a single user wallet

Returns: The response from the Chi Money API

| Param | Type | Default | Description | | ---------- | ------------------- | ----------------- | --------------------------------- | | id | string | | The wallet id | | subAccount | string | null | The subAccount of the transaction |

transfer(receiver, wallet, amount, subAccount)

For more information visit Chi Money API

This function lets you transfer funds to receiver

Returns: The response from the Chi Money API

| Param | Type | Description | | ---------- | ------------------- | ------------------------------------------------ | | receiver | string | The receiver id | | wallet | string | The wallet type | | amount | number | The amount of funds to be transferred in dollars | | subAccount | string | The subAccount of the transaction |

Errors

There are four main types of errors throw by the chimoneyjs package.

• ValueError: Missing required function parameter(s)
• TypeError: Parameter with a wrong type was passed into a function.
• ChiMoneyError: Error with the request sent to the Chi Money API. This is as a result of invalid data being sent to the Chi Money server.
• AuthKeyError: This occurs when the API wasn't set.