> For the complete documentation index, see [llms.txt](https://momojs.rewriteapi.cm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://momojs.rewriteapi.cm/reference/api-reference/client/disbursements.md).

# Disbursements

Represent Disbursements Client used for Disbursements product

| Method                                                                                        |
| --------------------------------------------------------------------------------------------- |
| *async* [`createAccessToken()`](#awaitcreate_access_token-authorization)                      |
| *async* [`getAccountBalance()`](#await-get_account_balance-authorization-target)              |
| *async* [`getAccountBalanceIn()`](#awaitget_account_balance_in-currency-authorization-target) |
| *async* [`getBasicUserInfo()`](#awaitget_basic_user_info-msisdn-authorization-target)         |
| *async* [`askUserInfo()`](#awaitask_user_info-authorization-target)                           |
| *async* [`deposit()`](#await-deposit-uuid-authorization-target-body-url_callback)             |
| *async* [`transfer()`](#await-tranfer-uuid-authorization-target-body-url_callback)            |
| *async* [`refund()`](#await-refund-uuid-authorization-target-body-url_callback)               |
| *async* [`getDepositStatus()`](#await-get_deposit_status-uuid-authorization-target)           |
| *async* [`getTransferStatus()`](#await-get_transfer_status-uuid-authorization-target)         |
| async [`getRefundStatus()`](#await-get_refund_status-uuid-authorization-target)               |
| *async* [`isActive()`](#await-isactive-account-account_type-authorization-target)             |

### *`await`*`createAccessToken( authorization )`

   Method to create access token for disbursements user

#### Parameters :

* **authorization** (string) - a valid basic authentification token

#### Return

\[boolean, data]

{% tabs %}
{% tab title="data" %}

```json
{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0
}
```

{% endtab %}
{% endtabs %}

#### Return Type :

array

### *`await`*` ``getAccountBalance( authorization, target )`

Method to get balance for disbursements user

#### Parameters :

* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

{% tabs %}
{% tab title="data" %}

```json
{
  "availableBalance": "string",
  "currency": "string"
}
```

{% endtab %}
{% endtabs %}

#### Return Type :

array

### *`await`*` ``getAccountBalanceIn( currency, authorization, target )`

Method to get balance in specific currency for disbursements user

#### Parameters :

* **currency** (string) - A valid ISO4217 Currency
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

{% tabs %}
{% tab title="data" %}

```json
{
  "availableBalance": "string",
  "currency": "string"
}
```

{% endtab %}
{% endtabs %}

#### Return Type :

array

### *`await`*` ``getBasicUserInfo( msisdn, authorization, target )`

Method to get basic user info without consent for disbursements user

#### Parameters :

* **msisdn** (string) - The number of the user
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

{% tabs %}
{% tab title="data" %}

```json
{
  "given_name": "string",
  "family_name": "string",
  "birthdate": "string",
  "locale": "string",
  "gender": "string",
  "status": "string"
}
```

{% endtab %}
{% endtabs %}

#### Return Type:

array

### *`await`*` ``askUserInfo( authorization, target )`

Method to get user info with consent for disbursements user

#### Parameters :

* **authorization** (string) - A valld bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

{% tabs %}
{% tab title="data" %}

```json
{
  "sub": "string",
  "name": "string",
  "given_name": "string",
  "family_name": "string",
  "middle_name": "string",
  "email": "string",
  "email_verified": true,
  "gender": "string",
  "locale": "string",
  "phone_number": "string",
  "phone_number_verified": true,
  "address": "string",
  "updated_at": 0,
  "status": "string",
  "birthdate": "string",
  "credit_score": "string",
  "active": true,
  "country_of_birth": "string",
  "region_of_birth": "string",
  "city_of_birth": "string",
  "occupation": "string",
  "employer_name": "string",
  "identification_type": "string",
  "identification_value": "string"
}
```

{% endtab %}
{% endtabs %}

#### Return Type :

array

### *`await`*` ``deposit( uuid, authorization, target, body, urlCallback )`

Method to make deposit for disbursement user

{% hint style="warning" %}
The library is only taking in charge deposit V2
{% endhint %}

#### Parameters :

* **uuid** (string) - A valid UUID version 4
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment
* **body** (Object) - A dictionnary with full detail of the payment \[*see detail below*]

{% tabs %}
{% tab title="body" %}
According to [MTN MOMO API](https://momodeveloper.mtn.com/docs/services/disbursement/operations/Deposit-V2?#requesttab1)

```json
{
  "amount": "string",
  "currency": "string",
  "externalId": "string",
  "payer": {
    "partyIdType": "MSISDN",
    "partyId": "string"
  },
  "payerMessage": "string",
  "payeeNote": "string"
}
```

{% endtab %}

{% tab title="details" %}

```json
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Amount that will be debited from the payer account."
    },
    "currency": {
      "type": "string",
      "description": "ISO4217 Currency"
    },
    "externalId": {
      "type": "string",
      "description": "External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report. <br>External id is not required to be unique."
    },
    "payer": {
      "type": "object",
      "properties": {
        "partyIdType": {
          "enum": [
            "MSISDN",
            "EMAIL",
            "PARTY_CODE"
          ],
          "type": "string"
        },
        "partyId": {
          "type": "string"
        }
      },
      "description": "Party identifies a account holder in the wallet platform. Party consists of two parameters, type and partyId. Each type have its own validation of the partyId<br> MSISDN - Mobile Number validated according to ITU-T E.164. Validated with IsMSISDN<br> EMAIL - Validated to be a valid e-mail format. Validated with IsEmail<br> PARTY_CODE - UUID of the party. Validated with IsUuid"
    },
    "payerMessage": {
      "type": "string",
      "description": "Message that will be written in the payer transaction history message field."
    },
    "payeeNote": {
      "type": "string",
      "description": "Message that will be written in the payee transaction history note field."
    }
  }
}
```

{% endtab %}
{% endtabs %}

* **urlCallback** ( \[Optional] string ) - The website receiving call back

#### Return :

\[boolean, data]

#### Retrun Type :

array

### *`await`*` ``transfer( uuid, authorization, target, body, urlCallback )`

Method to transfer for disbursement user

#### Parameters :

* uuid (string) - A valid UUID version 4&#x20;
* authorization (string) - A valid bearer authentification token
* body (Object) - A dictionnary with full detail of the payment \[[*see detail below*](/reference/api-reference/body-details.md)]
* urlCallback ( \[Optional] string ) - The website receiving call back

#### Return :

\[boolean, data]

#### Return Type :

array

### *`await`*` ``getDepositStatus( uuid, authorization, target )`

Method to get a withdrawal status for collection user

#### Parameters :

* **uuid** (string) - A valid UUID version 4
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

{% tabs %}
{% tab title="data" %}
According to [MTN MOMO API](https://momodeveloper.mtn.com/docs/services/disbursement/operations/GetDepositStatus?#response200tab4)

```json
{
  "amount": "string",
  "currency": "string",
  "financialTransactionId": "string",
  "externalId": "string",
  "payer": {
    "partyIdType": "MSISDN",
    "partyId": "string"
  },
  "payerMessage": "string",
  "payeeNote": "string",
  "status": "PENDING",
  "reason": {
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
  }
}
```

{% endtab %}
{% endtabs %}

#### Return Type:

array

### *`await`*` ``refund( uuid, authorization, target, body, urlCallback )`

Method to transfer for disbursement user

{% hint style="warning" %}
The library is only taking in charge only Refund V2
{% endhint %}

#### Parameters :

* **uuid** (string) - A valid UUID version 4
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment
* **body** (Object) - A dictionnary with full detail of the payment&#x20;

{% tabs %}
{% tab title="body" %}
According to [MTN MOMO API](https://momodeveloper.mtn.com/docs/services/disbursement/operations/Refund-V2?#requesttab1)

```json
{
  "amount": "string",
  "currency": "string",
  "externalId": "string",
  "payerMessage": "string",
  "payeeNote": "string",
  "referenceIdToRefund": "UUID-REQUEST-TO-PAY"
}
```

{% endtab %}

{% tab title="details" %}

```json
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Amount that will be debited from the payer account."
    },
    "currency": {
      "type": "string",
      "description": "ISO4217 Currency"
    },
    "externalId": {
      "type": "string",
      "description": "External id is used as a reference to the transaction. External id is used for reconciliation. The external id will be included in transaction history report. <br>External id is not required to be unique."
    },
    "payerMessage": {
      "type": "string",
      "description": "Message that will be written in the payer transaction history message field."
    },
    "payeeNote": {
      "type": "string",
      "description": "Message that will be written in the payee transaction history note field."
    },
    "referenceIdToRefund": {
      "type": "string",
      "description": "Format - UUID. Recource ID of the created refund transaction. This ID is used, for example, validating the status of the‘ ’transaction generated using UUID version 4."
    }
  }
}
```

{% endtab %}
{% endtabs %}

* **urlCallback** ( \[Optional] string ) - The website receiving call back

#### Return :

\[boolean, data]

#### Return Type :

array

### *`await`*` ``getTransferStatus( uuid, authorization, target )`

Method to get transfer status for disbursement user

#### Parameters :

* **uuid** (string) - A valid UUID version 4
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

{% tabs %}
{% tab title="data" %}
According to [MTN MOMO API](https://momodeveloper.mtn.com/docs/services/disbursement/operations/GetTransferStatus?#response200tab4)

```json
{
  "amount": "string",
  "currency": "string",
  "financialTransactionId": "string",
  "externalId": "string",
  "payee": {
    "partyIdType": "MSISDN",
    "partyId": "string"
  },
  "payerMessage": "string",
  "payeeNote": "string",
  "status": "PENDING",
  "reason": {
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
  }
}
```

{% endtab %}
{% endtabs %}

#### Return Type :

array

### *`await`*` ``getRefundStatus( uuid, authorization, target )`

Method to get transfer status for disbursement user

#### Parameters :

* **uuid** (string) - A valid UUID version 4
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :&#x20;

\[boolean, data]

{% tabs %}
{% tab title="data" %}
According to [MTN MOMO API](https://momodeveloper.mtn.com/docs/services/disbursement/operations/GetRefundStatus?#response200tab4)

```json
{
  "amount": "string",
  "currency": "string",
  "financialTransactionId": "string",
  "externalId": "string",
  "payee": {
    "partyIdType": "MSISDN",
    "partyId": "string"
  },
  "payerMessage": "string",
  "payeeNote": "string",
  "status": "PENDING",
  "reason": {
    "code": "PAYEE_NOT_FOUND",
    "message": "string"
  }
}
```

{% endtab %}
{% endtabs %}

#### Return Type :

array

### *`await`*` ``isActive( account, accountType, authorization, target )`

Method to check if an account is active for a collection user

#### Parameters :

* **account** (string) - The account target
* **accountType** (string) - Specifies the type of the party ID. Allowed values \[msisdn, email, party\_code]. default set to msisdn
* **authorization** (string) - A valid bearer authentification token
* **target** (string) - The target environment

#### Return :

\[boolean, data]

#### Return Type :

array