mtn-momo

A collection of utils to interact with the mtn momo api

Installation

• With yarn

yarn add mtn-momo-client

• With npm

npm install mtn-momo-client

• With pnpm

pnpm install mtn-momo-client

Functionalities

User provisioning

This implements api user and key management as explained here

This is needed when developing to get the credentials you will use when getting the access token to access any service. You will need to first obtain a subscription key by subscribing to any of the mtm momo products. Once you have subscribed and logged in, you will find the primary key of the product you want to use under your developer profile. Its the primary key. Below are the apis you can use for user provisioning.

• createAPIUserAndKey - This returns you all the details you need to provision a user

Usage

import { createAPIUserAndKey } from 'mtn-momo-client';

const subscriptionKey =
  'the subscription key of the product as explained above';

const data = await createAPIUserAndKey({
  providerCallbackHost: 'http://localhost',
  subscriptionKey,
});

// data will be in the shape. You can use this to create target api methods as shown below
data = {
  userId: 'the api user id',
  apiKey: 'the api key ',
  targetEnvironment: TargetEnvironment.Sandbox, // should be TargetEnvironment.Production when you go live
  subscriptionKey: 'the primary key of the product',
  providerCallbackHost: 'the url where you want confirmations redirected to',
};

The createAPIUserAndKey is all you need to generate user credentials. Its is just a facade around, createProvisioningClient that creates a client you will use to make provisioning requests, createAPIUser that creates an api user and returns the id of the user, createAPIKey that creates an apiKey and returns it and fetchAPIUser that returns the targetEnvironment and the providerCallbackHost as stored by mtn. We recommend that you createAPIUserAndKey and only use the other low level functions if you find a use case it doesn't cover

We don't have versioning exposed because, user provisioning has only one version (v1) unlike other apis that have multiple versions

Creating tokens

• Access token

  This is a token you can use to access other endpoints of the API. You can create an access token for each product by using the createAccessToken method. You will barely use this method as creating and regenerating a token when the created one is expired is dealt with by the API endpoint utilities.

import { createAccessToken, TargetEnvironment } from 'mtn-momo-client';

const accessTokenDetails = createAccessToken({
  userId: 'the api user id',
  apiKey: 'the api key ',
  targetEnvironment: TargetEnvironment.Sandbox, // should be TargetEnvironment.Production when you go live
  subscriptionKey: 'the primary key of the product',
  providerCallbackHost: 'the url where you want confirmations redirected to',
}); // returns {accessToken: '',tokenType: 'access_token', expiresIn: 3600 }

API endpoints

• Collection API

  • Create collection Api

    Create the methods you will use to access the collection api endpoints. Each end point has a corresponding method to talk to it.

    import { createAPIUserAndKey, createCollectionAPI } from 'mtn-momo-client';
    
    const collectionPrimaryKey =
      'The collection api subscription primary key found in your dashboard';
    
    // You can generate configs to create collectionAPI in development by using the createAPIUserAndKey utility
    // In production you will get the userId, apiKey from your dashboard these are part of the config payload generated by createAPIUserAndKey
    const config = await createAPIUserAndKey({
      providerCallbackHost: 'http://localhost',
      subscriptionKey: collectionPrimaryKey,
    });
    
    // returns an object containing methods you can use to access the collections api
    const collectionAPI = createCollectionAPI(config);

  • Request to pay

    This operation is used to request a payment from a consumer (Payer) and is fully documented here. Gets back a referenceId you can use to fetch the transaction status.

    import { PartyIDVariant } from 'mtn-momo-client';
    
    const { referenceId } = await collectionAPI.requestToPay({
      amount: '1000',
      currency: 'EUR',
      externalId: '012345678',
      payer: {
        partyIdType: PartyIDVariant.MSISDN,
        partyId: '256779840633',
      },
      payerMessage: 'message to payer',
      payeeNote: 'note to payee',
    });

  • Request to pay transaction status

    This operation is used to get the status of a request to pay by using the referenceId of the request to pay transaction and is fully documented here

    // fetch transaction status and details
    const paymentStatusAndDetails =
      await collectionAPI.requestToPayTransactionStatus({
        referenceId,
      });

  • Get Account balance

    This operation gets the balance of the account and is fully documented here

    // fetch user Account balance
    const accountBalance = await collectionAPI.getAccountBalance(); // returns the availableBalance and currency

  • Get Basic user info

    This operation returns personal information of the account holder. The operation does not need any consent by the account holder and is fully documented here

    // fetch user information associated with the given phone number
    const accountBalance = await collectionAPI.getBasicUserInfo({
      accountHolderMSISDN: '256779840633',
    });

  • Validate account holder status

    This operation is used to check if an account holder is registered and active in the system and is fully documented here

    import { AccountHolderIdVariant } from 'mtn-momo-client';
    
    // fetch status of the account holder
    const isActive = await collectionAPI.validateAccountHolderStatus({
      accountHolderId: '256779840633',
      accountHolderIdType: AccountHolderIdVariant.msisdn,
    });
    console.log({ isActive }); // boolean, true when active, false otherwise

  • Request to pay delivery notification

    This operation is used to send additional Notification to an End User. and is fully documented here

    This was tested to work properly with the collection API but fails with the disbursement am remittance API. The cause is unknown even though the documentation for all products is uniform and we generate the method with the same function in the codebase.

    // send additional notification to end user
    const { notificationMessage } =
      await collectionAPI.requestToPayDeliveryNotification({
        referenceId, // the reference id of the transaction
        notificationMessage: 'Hello Momo', // custom message you want to send
      });

• Remittance API

  • Create remittance API

    Create the methods you will use to access the remittance api endpoints. Each end point has a corresponding method to talk to it.

    import { createAPIUserAndKey, createRemittanceAPI } from 'mtn-momo-client';
    
    const remittancePrimaryKey =
      'The remittance api subscription primary key found in your dashboard';
    
    // You can generate configs to create remittanceAPI in development by using the createAPIUserAndKey utility
    // In production you will get the userId, apiKey from your dashboard these are part of the config payload generated by createAPIUserAndKey
    const config = await createAPIUserAndKey({
      providerCallbackHost: 'http://localhost',
      subscriptionKey: remittancePrimaryKey,
    });
    
    // returns an object containing methods you can use to access the remittance api
    const remittanceAPI = createRemittanceAPI(config);

  • Transfer

    Transfer operation is used to transfer an amount from the own account to a payee account and is fully documented here. Gets back a referenceId you can use to fetch the transaction status.

    import { PartyIDVariant } from 'mtn-momo-client';
    
    const { referenceId } = await remittanceAPI.transfer({
      amount: '1000',
      currency: 'EUR',
      externalId: '123456789',
      payee: {
        partyIdType: PartyIDVariant.MSISDN,
        partyId: '256779840633',
      },
      payerMessage: 'message to payer',
      payeeNote: 'note to payee',
    });

  • Get transfer status

    This operation is used to get the status of a transfer by using the referenceId of the transfer transaction and is fully documented here

    // fetch transfer status and details
    const transferStatusAndDetails = await remittanceAPI.getTransferStatus({
      referenceId,
    });

  • Get Account balance

    This operation gets the balance of the account and is fully documented here

    // fetch user Account balance
    const accountBalance = await remittanceAPI.getAccountBalance(); // returns the availableBalance and currency

  • Get Basic user info

    This operation returns personal information of the account holder. The operation does not need any consent by the account holder and is fully documented here

    // fetch user information associated with the given phone number
    const accountBalance = await remittanceAPI.getBasicUserInfo({
      accountHolderMSISDN: '256779840633',
    });

  • Validate account holder status

    This operation is used to check if an account holder is registered and active in the system and is fully documented here

    import { AccountHolderIdVariant } from 'mtn-momo-client';
    
    // fetch status of the account holder
    const isActive = await remittanceAPI.validateAccountHolderStatus({
      accountHolderId: '256779840633',
      accountHolderIdType: AccountHolderIdVariant.msisdn,
    });
    console.log({ isActive }); // boolean, true when active, false otherwise

  • Request to pay delivery notification

    This operation is used to send additional Notification to an End User. and is fully documented here

    This was tested to work properly with the collection API but fails with the disbursement am remittance API. The cause is unknown even though the documentation for all products is uniform and we generate the method with the same function in the codebase.

    // send additional notification to end user
    const { notificationMessage } =
      await remittanceAPI.requestToPayDeliveryNotification({
        referenceId, // the reference id of the transaction
        notificationMessage: 'Hello Momo', // custom message you want to send
      });

• Disbursement API

  • Create disbursement API

    Create the methods you will use to access the disbursement api endpoints. Each end point has a corresponding method to talk to it.

    import {
      createAPIUserAndKey,
      createDisbursementAPI,
    } from 'mtn-momo-client';
    
    const disbursementPrimaryKey =
      'The disbursement api subscription primary key found in your dashboard';
    
    // You can generate configs to create disbursementAPI in development by using the createAPIUserAndKey utility
    // In production you will get the userId, apiKey from your dashboard these are part of the config payload generated by createAPIUserAndKey
    const config = await createAPIUserAndKey({
      providerCallbackHost: 'http://localhost',
      subscriptionKey: disbursementPrimaryKey,
    });
    
    // returns an object containing methods you can use to access the disbursement api
    const disbursementAPI = createDisbursementAPI(config);

  • Transfer

    Transfer operation is used to transfer an amount from the own account to a payee account and is fully documented here. Gets back a referenceId you can use to fetch the transaction status.

    import { PartyIDVariant } from 'mtn-momo-client';
    
    const { referenceId } = await disbursementAPI.transfer({
      amount: '1000',
      currency: 'EUR',
      externalId: '123456789',
      payee: {
        partyIdType: PartyIDVariant.MSISDN,
        partyId: '256779840633',
      },
      payerMessage: 'message to payer',
      payeeNote: 'note to payee',
    });

  • Get transfer status

    This operation is used to get the status of a transfer by using the referenceId of the transfer transaction and is fully documented here

    // fetch transfer status and details
    const transferStatusAndDetails = await disbursementAPI.getTransferStatus({
      referenceId,
    });

  • Get Account balance

    This operation gets the balance of the account and is fully documented here

    // fetch user Account balance
    const accountBalance = await disbursementAPI.getAccountBalance(); // returns the availableBalance and currency

  • Get Basic user info

    This operation returns personal information of the account holder. The operation does not need any consent by the account holder and is fully documented here

    // fetch user information associated with the given phone number
    const accountBalance = await disbursementAPI.getBasicUserInfo({
      accountHolderMSISDN: '256779840633',
    });

  • Validate account holder status

    This operation is used to check if an account holder is registered and active in the system and is fully documented here

    import { AccountHolderIdVariant } from 'mtn-momo-client';
    
    // fetch status of the account holder
    const isActive = await disbursementAPI.validateAccountHolderStatus({
      accountHolderId: '256779840633',
      accountHolderIdType: AccountHolderIdVariant.msisdn,
    });
    console.log({ isActive }); // boolean, true when active, false otherwise

  • Request to pay delivery notification

    This operation is used to send additional Notification to an End User. and is fully documented here

    This was tested to work properly with the collection API but fails with the disbursement am remittance API. The cause is unknown even though the documentation for all products is uniform and we generate the method with the same function in the codebase.

    // send additional notification to end user
    const { notificationMessage } =
      await disbursementAPI.requestToPayDeliveryNotification({
        referenceId, // the reference id of the transaction
        notificationMessage: 'Hello Momo', // custom message you want to send
      });