The MMAPI SDK for Node.js enables Node.js developers to easily work with GSMA Mobile Money API Specification 1.2.0.
The SDK provides separate use cases to handle necessary MMAPI functionality including Merchant Payments, Disbursements, International Transfers, P2P Transfers, Recurring Payments, Account Linking, Bill Payments and Agent Services (including Cash-In and Cash-Out). Each use case exposes use case scenarios to customize your application integrations as needed. The SDK also includes a Samples, so you can test interactions before integration.
This document contains the following sections:
- Node.js 16.13.1 LTS or higher
Create a Node.js project in your directory, then run the following command to install the Mobile Money Api Node.js SDK.
npm install mmapi-nodejs-sdkAfter you install the SDK, make it available to your app and configure your environment. Configuration details include either sandbox for testing or live for production, and your consumer key, consumer secret, api key, security option and callback url for your app.
In the directory where you installed the SDK, include this code to make the SDK available and configure your environment with your application credentials for sandbox and live environments in the Developer Dashboard.
/**
* MMAPI Node.js SDK dependency
*/
const mmapi = require('mmapi-nodejs-sdk');
/**
* Set up and return MMAPI Noe.js SDK environment.
*/
const consumerKey = process.env.CONSUMER_KEY
const consumerSecret = process.env.CONSUMER_SECRET;
const apiKey = process.env.API_KEY;
const securityOption = process.env.SECURITY_OPTION; // DEVELOPMENT_LEVEL, STANDARD_LEVEL, ENHANCED_LEVEL
const callbackUrl = process.env.CALLBACK_URL;
let environment;
if (process.env.NODE_ENV === 'production') {
environment = new mmapi.core.LiveEnvironment(consumerKey, consumerSecret, apiKey, securityOption, callbackUrl);
}
environment = new mmapi.core.SandboxEnvironment(consumerKey, consumerSecret, apiKey, securityOption, callbackUrl);
/**
* Returns MMAPI Noe.js SDK HTTP client instance with environment.
* Use this instance to invoke MMAPI APIs
*/
let client = new mmapi.core.MobileMoneyApiHttpClient(environment);| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Payee-Initiated Merchant Payment | Payee Initiated Merchant Payment | createMerchantTransaction | |
| Payee-Initiated Merchant Payment using the Polling Method | Payee Initiated Merchant Payment | createMerchantTransaction | |
| Poll to Determine the Request State | viewRequestState | serverCorrelationId | |
| Retrieve a Transaction | viewTransaction | transactionReference | |
| Payer-Initiated Merchant Payment | Payer Initiated Merchant Payment | createMerchantTransaction | |
| Payee-Initiated Merchant Payment using a Pre-authorised Payment Code | Obtain an Authorisation Code | createAuthorisationCode | { identifierType1: identifier1 } |
| Perform a Merchant Payment | createMerchantTransaction | ||
| View An Authorisation Code | viewAuthorisationCode | { identifierType1: identifier1 } | |
| Merchant Payment Refund | Perform a Merchant Payment Refund | createRefundTransaction | |
| Merchant Payment Reversal | Perform a Merchant Payment Reversal | createReversal | originalTransactionReference |
| Obtain a Merchant Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Payments for a Merchant | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve Representation a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Individual Disbursement | Perform an Individual Disbursement | createDisbursementTransaction | |
| Bulk Disbursement | Perform a Bulk Disbursement | createBatchTransaction | |
| View A Transaction Batch | viewBatchTransaction | batchId | |
| Retrieve Batch Transactions that have Completed | viewBatchCompletions | batchId | |
| Retrieve Batch Transactions that have been Rejected | viewBatchRejections | batchId | |
| Bulk Disbursement with Maker / Checker | Perform a Bulk Disbursement | createBatchTransaction | |
| Update A Transaction Batch | updateBatchTransaction | batchId | |
| View A Transaction Batch | viewBatchTransaction | batchId | |
| Retrieve Batch Transactions that have Completed | viewBatchCompletions | batchId | |
| Retrieve Batch Transactions that have been Rejected | viewBatchRejections | batchId | |
| Individual Disbursement Using the Polling Method | Perform an Individual Disbursement | createDisbursementTransaction | |
| Poll to Determine the Request State | viewRequestState | serverCorrelationId | |
| Retrieve a Transaction | viewTransaction | transactionReference | |
| Disbursement Reversal | Perform a Transaction Reversal | createReversal | originalTransactionReference |
| Obtain a Disbursement Organisation Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Transactions for a Disbursement Organisation | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve Representation a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| International Transfer via Hub | Request a International Transfer Quotation | createQuotation | |
| Perform an International Transfer | createInternationalTransaction | ||
| Bilateral International Transfer | Request a International Transfer Quotation | createQuotation | |
| Perform an International Transfer | createInternationalTransaction | ||
| International Transfer Reversal | Perform a Transaction Reversal | createReversal | originalTransactionReference |
| Obtain an FSP Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Transactions for an FSP | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve Representation a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| P2P Transfer via Switch | Retrieve the Name of the Recipient | viewAccountName | { identifierType1: identifier1 } |
| Request a P2P Quotation | createQuotation | ||
| Perform a P2P Transfer | createTransferTransaction | ||
| Bilateral P2P Transfer | Retrieve the Name of the Recipient | viewAccountName | { identifierType1: identifier1 } |
| Perform a P2P Transfer | createTransferTransaction | ||
| ‘On-us’ P2P Transfer Initiated by a Third Party Provider | Retrieve the Name of the Recipient | viewAccountName | { identifierType1: identifier1 } |
| Request a P2P Quotation | createQuotation | ||
| Perform a P2P Transfer | createTransferTransaction | ||
| P2P Transfer Reversal | Perform a Transaction Reversal | createReversal | originalTransactionReference |
| Obtain an FSP Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Transactions for an FSP | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve Representation a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Setup a Recurring Payment | Setup a Recurring Payment | createAccountDebitMandate | { identifierType1: identifier1 } |
| Take a Recurring Payment | Take a Recurring Payment | createMerchantTransaction | |
| Take a Recurring Payment using the Polling Method | Take a Recurring Payment | createMerchantTransaction | |
| Recurring Payment Refund | Perform a Recurring Payment Refund | createRefundTransaction | |
| Recurring Payment Reversal | Perform a Merchant Payment Reversal | createReversal | originalTransactionReference |
| Payer sets up a Recurring Payment using MMP Channel | Setup a Recurring Payment | createAccountDebitMandate | { identifierType1: identifier1 } |
| Obtain a Service Provider Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Payments for a Service Provider | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Setup an Account Link | Establish an Account to Account Link | createAccountLink | { identifierType1: identifier1 } |
| Perform a Transfer for a Linked Account | Use a Link to make a Transfer | createTransferTransaction | |
| Perform a Transfer using an Account Link via the Polling Method | Use a Link to make a Transfer | createTransferTransaction | |
| Perform a Transfer Reversal | Perform a Transaction Reversal | createReversal | originalTransactionReference |
| Obtain a Financial Service Provider Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Transfers for a Financial Service Provider | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Successful Retrieval of Bills | Retrieve a Set of Bills | viewAccountBills | { identifierType1: identifier1 } |
| Make a Successful Bill Payment with Callback | Perform a Bill Payment Transaction | createBillTransaction | |
| Make a Bill Payment | createBillPayment | { identifierType1: identifier1 }, billReference | |
| Make a Bill Payment with Polling | Make a Bill Payment Via the Polling Method | createBillPayment | { identifierType1: identifier1 }, billReference |
| Poll to Determine the Request State | viewRequestState | serverCorrelationId | |
| Retrieve Bill Payments for a Given Bill | viewBillPayment | { identifierType1: identifier1 }, billReference | |
| Retrieval of Bill Payments | Retrieve a Set of Bill Payments | viewBillPayment | { identifierType1: identifier1 }, billReference |
| Retrieve a Transaction | Retrieve a Transaction | viewTransaction | transactionReference |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve a Missing Resource | viewResource | link |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Agent-initiated Cash-out | Agent Initiated Cash-out | createWithdrawalTransaction | |
| Agent-initiated Cash-out using the Polling Method | Agent Initiated Cash-out | createWithdrawalTransaction | |
| Poll to Determine the Request State | viewRequestState | serverCorrelationId | |
| Retrieve a Transaction | viewTransaction | transactionReference | |
| Customer Cash - out at an ATM using an Authorisation Code | Obtain an Authorisation Code | createAuthorisationCode | { identifierType1: identifier1 } |
| ATM Initiated Cash-Out | createWithdrawalTransaction | ||
| Agent-initiated Customer Cash-in | Retrieve the Name of the Depositing Customer | viewAccountName | { identifierType1: identifier1 } |
| Agent Initiated Cash-in | createDepositTransaction | ||
| Cash-out Reversal | Perform a Transaction Reversal | createReversal | originalTransactionReference |
| Register a Customer Mobile Money Account | Create a Mobile Money Account | createAccount | |
| Verify a Customer’s KYC | Retrieve Account Information | viewAccount | { identifierType1: identifier1 } |
| Update KYC Verification Status | updateAccountIdentity | { identifierType1: identifier1 }, identityId | |
| Obtain an Agent Balance | Get an Account Balance | viewAccountBalance | { identifierType1: identifier1 } |
| Retrieve Transactions for an Agent | Retrieve a Set of Transactions for an Account | viewAccountTransactions | { identifierType1: identifier1 } |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | clientCorrelationId |
| Retrieve a Missing Resource | viewResource | link |
It is not mandatory to fork this repository for using the MMAPI SDK. You can refer Setting Up for configuring and working with SDK without forking this code.
For contributing or referring the samples, you can fork/refer this repository.
To run integration tests using your consumer key, consumer secret and api key, clone this repository and run the following command:
So, there are actually two different types of tests, and we're going to try them all. The first is a unit test. The second type of test is an integration test.
$ npm install
$ CONSUMER_KEY=YOUR_CONSUMER_KEY CONSUMER_SECRET=YOUR_CONSUMER_SECRET API_KEY=YOUR_API_KEY SECURITY_OPTION=YOUR_SECURITY_OPTION CALLBACK_URL=YOUR_CALLBACK_URL npm run test
In a unit test, you test one specific function on a class. You call a function with some input, and test the return value. Each unit test is done in isolation. If, for example, a class needs a simulator connection, we're actually going to fake that simulator connection so that we can focus on testing just the logic of the class itself.
$ npm install
$ CONSUMER_KEY=YOUR_CONSUMER_KEY CONSUMER_SECRET=YOUR_CONSUMER_SECRET API_KEY=YOUR_API_KEY SECURITY_OPTION=YOUR_SECURITY_OPTION CALLBACK_URL=YOUR_CALLBACK_URL npm run test test/unit
An integration test is basically a unit test: you call functions and check their return values. But now, instead of faking the simulator connection, you'll use the real simulator connection.
$ npm install
$ CONSUMER_KEY=YOUR_CONSUMER_KEY CONSUMER_SECRET=YOUR_CONSUMER_SECRET API_KEY=YOUR_API_KEY SECURITY_OPTION=YOUR_SECURITY_OPTION CALLBACK_URL=YOUR_CALLBACK_URL npm run test test/integration
To test interactions before integration by by trying out different samples, clone this repository and run the following command:
Note: Update the samples/test_harness.js with your sandbox client credentials or pass your client credentials as environment variable while executing the samples.
To run all usecase scenarios for a usecase (merchantpay, disbursements, etc)
$ npm install
$ CONSUMER_KEY=YOUR_CONSUMER_KEY CONSUMER_SECRET=YOUR_CONSUMER_SECRET API_KEY=YOUR_API_KEY SECURITY_OPTION=YOUR_SECURITY_OPTION CALLBACK_URL=YOUR_CALLBACK_URL node samples/merchantPayment/runAll.js
$ npm install
$ node samples/merchantPayment/runAll.js
By default runAll.js will execute all usecase scenarios for the usecase
To select a specific use case scenario, edit the samples/merchantPayment/runAll.js by passing the usecase number as shown below
(async () => {
})(5);To run a usecase scenario by passing parameters to the function manually
Replace the parameter with a value
// samples/merchantPayment/createMerchantTransaction.js
if (require.main === module) {
(async () => {
try {
await createMerchantTransaction(false, true);
} catch (err) {
}
})();
}$ npm install
$ node samples/merchantPayment/createMerchantTransaction.js