mtn-momo-api/README.md

The MTN-Momo-API is an npm package that provides a convenient and simplified way to interact with the MoMo (Mobile Money) API for making financial transactions. It abstracts the complexities of the API and offers a streamlined interface for requesting pay

# MTN Momo Collections

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

- [Getting Your API Credentials](#getting-your-api-credentials)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#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:

```bash
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](https://www.npmjs.com/package/mtn-momo-api) to install `mtn-momo-api`.

```bash
npm install mtn-momo-api --save
```
## Usage
Here's an example of how you can use the MTN Momo Collections library in your project:

```bash

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

```bash

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.