mtn-momo-api

MTN Momo Collections

A simple library for integrating with the MTN Momo Collections API.

• Getting Your API Credentials
• Installation
• Usage
• API Reference
• Contributing
• License

Getting Your API Credentials

To use the MTN Momo Collections API, you need to generate your userId and userApiKey. Here's how you can generate them:

npx momo-sandbox --callback-host <callbackHost> --primary-key <primaryKey>

Replace <callbackHost> with the URL of your callback host and <primaryKey> with your actual MTN Mobile Money API primary or secondary key.

This command will generate a new user and display the userId and userApiKey in the console.

Note: "These credentials are specifically intended for use in the sandbox environment. In a production environment, you will be provided with the necessary credentials through the MTN OVA management dashboard after fulfilling the necessary KYC (Know Your Customer) requirements."

Installation

Use the package manager npm to install mtn-momo-api.

npm install mtn-momo-api --save

Usage

Here's an example of how you can use the MTN Momo Collections library in your project:

const { makeRequest } = require('mtn-momo-api');

makeRequest({
  callbackHost: '<callbackHost>',
  userApiKey: '<userApiKey>',
  userId: '<userId>',
  primaryKey: '<primaryKey>',
  amount: '<amount>',
  currency: '<currency>',
  externalId: '<externalId>',
  partyIdType: '<partyIdType>',
  partyId: '<partyId>',
  payerMessage: '<payerMessage>',
  payeeNote: '<payeeNote>'
})
  .then(({ response, status }) => {
    console.log('Response:', response);
    console.log('Transaction Status:', status);
  })
  .catch(error => {
    console.error('Error:', error);
  });

API Reference

makeRequest(options)

Initiates a request to pay using the MTN Momo Collections API.

• options: An object containing the following properties:

  • callbackHost: The callback URL for receiving payment notifications.
  • userApiKey: Your MTN Momo user API key.
  • userId: Your MTN Momo user ID.
  • primaryKey: Your MTN Momo primary key.
  • amount: The amount to be paid.
  • currency: The currency of the payment.
  • externalId: An ID generated by your system to uniquely identify the transaction.
  • partyIdType: The type of the party ID (e.g., MSISDN, EMAIL, etc.).
  • partyId: The party ID of the payer.
  • payerMessage: A message that will be displayed to the payer.
  • payeeNote: A note that will be displayed to the payee. Returns a promise that resolves to an object with the following properties:

• response: The response from the API.

• status: The transaction status.

Controller Class

The Controller class provides methods to interact with the MTN Momo Collections API.

Constructor

const { Controller } = require('mtn-momo-api');

const app = new Controller({
  callbackHost: '<callbackHost>',
  userApiKey: '<userApiKey>',
  userId: '<userId>',
  primaryKey: '<primaryKey>',
});

requestToPay(amount, currency, externalId, partyIdType, partyId, payerMessage, payeeNote)

Initiates a request to pay.

• amount: The amount to be paid.
• currency: The currency of the payment.
• externalId: An ID generated by your system to uniquely identify the transaction.
• partyIdType: The type of the party ID (e.g., MSISDN, EMAIL, etc.).
• partyId: The party ID of the payer.
• payerMessage: A message that will be displayed to the payer.
• payeeNote: A note that will be displayed to the payee.

Returns a promise that resolves to an object with the following properties:

• responseCode: The response code from the API.
• referenceId: The reference ID generated for the transaction.

getTransactionStatus(referenceId)

Retrieves the transaction status for a given reference ID.

• referenceId: The reference ID of the transaction. Returns a promise that resolves to the transaction status object.

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

License

This project is licensed under the MIT License.