moncash

Digicel Moncash API SDK for Node.js

Inspired by stripe SDK for Node.js

Digicel MonCash - MonCash is a mobile wallet that facilitates reliable, safe and convenient financial transactions to reduce the distance between people regardless of their location in Haiti. While providing its services to its customer base of over 1.5 million people, MonCash maintains its goal of expanding its range of available services.

Define: SDK

SDK stands for “Software Development Kit”, which is a great way to think about it — a kit. Think about putting together a model car or plane. When constructing this model, a whole kit of items is needed, including the kit pieces themselves, the tools needed to put them together, assembly instructions, and so forth.

Features

• Create payment
• Capture payment
• Transfert money

Installation

Moncash requires Node.js v12+ to run. Install the the SDK and start using it.

npm install --save moncash

Configuring the client

Digicel Moncash API Dashboard. Each business has it's own clientId clientSecret pairs.

const Moncash = require('moncash');

const moncash = new Moncash({
    mode:'sandbox', // 'sandbox' | 'live'
    clientId:'<clientId>',
    clientSecret:'<clientSecret>'
});

/*---------------or----------------*/

const Moncash = require('moncash');

const moncash = new Moncash();

moncash.configure({
    mode:'<mode>',     // 'sandbox' | 'live'
    clientId:'<clientId>',
    clientSecret:'<clientSecret>'
});

Create Payment

The only supported currency is 'HTG'. With the configue above.

moncash.payment.create({
    "amount": '<integer>',  // Ex: 50
    "orderId": '<string>'   // Must be unique 
},(err,payment)=>{
    if (err) {
        console.log(err.type);      // see Error handler section
        return false;
    }
    const paymentURI = moncash.payment.redirectUri(payment);
    console.log(payment,paymentURI);

    /* output:
        {
          mode: '<mode>',     // 'sandbox' | 'live'
          path: '/Api/v1/CreatePayment',
          payment_token: {
            expired: '<date>',
            created: '<date>',
            token: '<token>'
          },
          timestamp: '<timestamp>',
          status: '<status>'
        } 
        
        https://'<mode|"">'.moncashbutton.digicelgroup.com/Moncash-middleware/Payment/Redirect?token='<token>'
    */
});

Capture Payment

Two way to do so. By orderId or tansactionId.

moncash.capture.getByOrderId('<orderId>',(err,capture)=>{
    if (err) {
        console.log(err.type);      // see Error handler section
        return false;
    }
    console.log(capture);
    /* output:
        {
          path: '/Api/v1/RetrieveOrderPayment',
          payment: {
            reference: '<orderId>',
            transaction_id: '<transactionId>',
            cost: '<integer>',
            message: '<string>',
            payer: '<payerAccount>'
          },
          timestamp: '<timestamp>',
          status: '<status>'
        }
    */
});

/*---------------or----------------*/

moncash.capture.getByTransactionId('<transactionId>',(err,capture)=>{
    if (err) {
        console.log(err.type);      // see Error handler section
        return false;
    }
    console.log(capture);
    /* output:
        {
          path: '/Api/v1/RetrieveTransactionPayment',
          payment: {
            reference: '<orderId>',
            transaction_id: '<transactionId>',
            cost: '<integer>',
            message: '<string>',
            payer: '<payerAccount>'
          },
          timestamp: '<timestamp>',
          status: '<status>'
        }
    */
});

Tranfert money

The only supported currency is 'HTG'. In test for now.

moncash.transfert.create({
    "receiver":'<receiverAccount">',
    "amount": '<integer>',  // Ex: 50
    "desc": '<string>'
},(err,transfert)=>{
    if (err) {
        console.log(err.type);
        return false;
    }
    console.log(tranfert);
});

Error handling

List of errors in Moncash.errors.

const errors = Moncash.errors;

switch (err.type) {
    case errors.NotFoundError:
        console.log(err.description);
        break;
    case errors.UnauthorizedError:
        console.log("Verify your '<clientId>':'<clientSecret>' pairs");
        break;
    default:
        console.log('An error occured')
        break;
}

List of errors

• MoncashError
• APIError
• BadRequestError
• UnauthorizedError
• ForbiddenError
• NotFoundError
• ConflictError
• RequestTimeoutError
• TooManyRequestsError
• UnexpectedError

Development

Run all tests.

$ npm install
$ npm test

Run a single test suite without a coverage report.

$ npx jest test/capture.test.js

If you want to run tests using your Moncash clientId clientSecret pairs.

$ export MONCASH_TEST_CLIENT_ID='<clientId>'
$ export MONCASH_TEST_CLIENT_SECRET='<clientSecret>'
$ npm test

License

GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007

Useful links

• NPM package link
• Digicel Moncash API Dashboard
• RestAPI_MonCash_doc.pdf
• Old Moncash SDK for Node.js