Dohone-sdk NPM

DohoneSDK

A NodeJS SDK for easily use Dohone payment API.

Note

This module let you easily integrate Dohone payment API to your application or your web site for every Cameroon mobile payments operators (MTN Mobile Money, Orange Money and Express Union Mobile Money).

Before you start using this package, it's highly recommended to read documents below.

1. Requirements

There is no specific requirements for this package.

2. Installation

$ npm install dohone-sdk

3. Payin requests (collect payments)

3.1. Create a DohoneSDK object

You can find DohoneSDK class here.

var dohone = require('dohone-sdk');

// constants
var merchantKey = '...'; // your dohone merchant key (required)
var appName = '...'; // the name by which your application is recognized at Dohone
var hashCode = '...'; // your dohone hash code (only if you handle dohone notifications in your system)
var notifyUrl = '...'; // default notification URL for incoming payments

var dohoneSdk = dohone.payin(merchantKey, appName, hashCode, notifyUrl);

// ...

3.2. Make a « COTATION » command

// ...

/**
 * transaction is a JSON object with following properties
 *   - amount: number
 *   - currency: 'XAF', 'EUR' or 'USD'
 *   
 * params is a JSON object with following properties
 *   - mode: 0, 1, 2, 3 or 4 (exact as levelFeeds in Dohone docs)
 */
var transaction = {
    amount: 1000,
    currency: 'XAF'
};
var params = {
    mode: 0
};
dohoneSdk.quote(transaction, params, function (err, dohoneRes) {
    if (err) {
        // handle request error here
    }
    else if (dohoneRes.isSuccess) {
        // use dohoneRes.message here
    }
    else {
        // Dohone error, check dohoneRes.message
    }
});

// ...

3.3. Make a « START » command

// ...

/**
 * transaction is a JSON object with following properties
 *   - ref: string (unique transaction reference in your system)
 *   - amount: number
 *   - currency: 'XAF', 'EUR' or 'USD'
 *   - operator: 'DOHONE_OM', 'DOHONE_MOMO', 'DOHONE_EU', 'DOHONE_TRANSFER'
 *   - customerPhoneNumber: string
 *   - customerName: string
 *   - customerEmail: string
 *   - reason: string
 *   - notifyUrl: string (notification URL for this transaction)
 *   
 * params is a JSON object with following properties
 *   - OTP: number (payment code in case of Orange Money)
 */
var transaction = {
    ref: '146eb9e4-fad1-4214-a8ed-9e5316ef2fad',
    amount: 1000,
    currency: 'XAF',
    operator: 'DOHONE_OM', // Orange Money
    customerPhoneNumber: '699999999'
};
var params = {
    OTP: '452132' // provided by user
};
dohoneSdk.start(transaction, params, function (err, dohoneRes) {
    if (err) {
        // handle request error here
    }
    else if (dohoneRes.isSuccess) {
        if (dohoneRes.needCFRMSMS) {
            // must make a CFRMSMS command
        }
        else if (dohoneRes.hasREF) {
            // successful transaction
            // dohoneRes.REF is transaction reference
        }
        else {
            // unknown response, check dohoneRes.message
        }
    }
    else {
        // Dohone error, check dohoneRes.message
    }
});

// ...

3.4. Make a « CFRMSMS » command

// ...

/**
 * transaction is a JSON object with following properties
 *   - customerPhoneNumber: string
 *   
 * params is a JSON object with following properties
 *   - code: string (Dohone authorization code)
 */
var transaction = {
    customerPhoneNumber: '699999999'
};
var params = {
    code: 'A123' // provided by user
};
dohoneSdk.confirmSMS(transaction, params, function (err, dohoneRes) {
    if (err) {
        // handle request error here
    }
    else if (dohoneRes.isSuccess) {
        if (dohoneRes.needCFRMSMS) {
            // invalid code, make a CFRMSMS command again
        }
        else if (dohoneRes.hasREF) {
            // successful transaction
            // dohoneRes.REF is transaction reference
        }
        else {
            // error, check dohoneRes.message
        }
    }
    else {
        // Dohone error, check dohoneRes.message
    }
});

// ...

Bonus tip
We have noticed that the CFRMSMS command often returns an empty answer, it is sometimes necessary to make several attempts before getting a good answer. For this, we have provided a fourth optional parameter to the confirmSMS() method that defines the maximum number of attempts to be made, its default value is 1.
// for example, if you want to allow five attempts
dohoneSdk.confirmSMS(transaction, params, callback, 5);

3.5. Make a « VERIFY » command

// ...

/**
 * transaction is a JSON object with following properties
 *   - ref: string (unique transaction reference in your system)
 *   - dohoneRef: string (Dohone transaction reference)
 *   - amount: number
 *   - currency: 'XAF', 'EUR' or 'USD'
 */
var transaction = {
    ref: '146eb9e4-fad1-4214-a8ed-9e5316ef2fad',
    dohoneRef: '123456789',
    amount: 1000,
    currency: 'XAF'
};
dohoneSdk.verify(transaction, function (err, dohoneRes) {
    if (err) {
        // handle request error here
    }
    else if (dohoneRes.isSuccess) {
        // recognized transaction
    }
    else {
        // unknown transaction
    }
});

// ...

3.6. Handle Dohone's notifications

// ...

/**
 * data must contain request parameters sent by Dohone
 */
// For example, if you are using Express framework, then
var data = request.query;

// After that, map data using
data = dohoneSdk.mapNotificationData(data);

// Check request integrity using your hashCode
if (dohoneSdk.checkHash(data)) {
    dohoneSdk.verify(data, function (err, dohoneRes) {
        if (err){
            // handle request error here
        }
        if (dohoneRes.isSuccess) {
            // everything is OK, do what you want with data
        }
        else {
            // unrecognized transaction, you can ignore the request or do something else
        }
    });
}
else {
    // bad signature, you can ignore the request or do something else
}

// ...