mtn-momo-client/README.md

A collection of utils to interact with the mtn-momo api

# mtn-momo

A collection of utils to interact with the mtn momo api

## Installation

- With yarn

```bash
yarn add mtn-momo-client
```

- With npm

```bash
npm install mtn-momo-client
```

- With pnpm

```bash
pnpm install mtn-momo-client
```

## Functionalities

### User provisioning

> This implements api user and key management as explained [here](https://momodeveloper.mtn.com/api-documentation/api-description/)

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](https://momodeveloper.mtn.com/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](https://momodeveloper.mtn.com/developer). 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**

```js
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](#api-endpoints).

```js
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.

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/collection/operations/RequesttoPay?). Gets back a referenceId you can use to fetch the transaction status.

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/collection/operations/RequesttoPayTransactionStatus?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/collection/operations/GetAccountBalance?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/collection/operations/GetBasicUserinfo?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/collection/operations/ValidateAccountHolderStatus?)

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/collection/operations/RequesttoPayDeliveryNotification?)

    > 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.

    ```ts
    // 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.

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/remittance/operations/Transfer?). Gets back a referenceId you can use to fetch the transaction status.

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/remittance/operations/GetTransferStatus?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/remittance/operations/GetAccountBalance?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/remittance/operations/GetBasicUserinfo?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/remittance/operations/ValidateAccountHolderStatus?)

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/remittance/operations/RequesttoPayDeliveryNotification?)

    > 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.

    ```ts
    // 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.

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/disbursement/operations/Transfer?). Gets back a referenceId you can use to fetch the transaction status.

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/disbursement/operations/GetTransferStatus?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/disbursement/operations/GetAccountBalance?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/disbursement/operations/GetBasicUserinfo?)

    ```ts
    // 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](https://momodeveloper.mtn.com/docs/services/disbursement/operations/ValidateAccountHolderStatus?)

    ```ts
    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](https://momodeveloper.mtn.com/docs/services/disbursement/operations/RequesttoPayDeliveryNotification?)

    > 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.

    ```ts
    // 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
      });
    ```