Mtn Open Api

Explore seamless integration with MTN Open API using this Ruby gem. For in-depth information, refer to the official documentation at https://momodeveloper.mtn.com/.

Key Features

• Full API Availability: Access a comprehensive set of API endpoints, providing developers with a versatile toolkit to address a wide range of scenarios. The gem's commitment to inclusivity ensures that all necessary API endpoints are readily available for integration.

• Robust Testing: Every endpoint is rigorously tested to ensure reliability and stability. By adhering to best practices in testing, the Mtn Open Api gem delivers a dependable solution that developers can trust for their projects.

• Intuitive Conversion: Experience a seamless transition from JSON responses to structured OpenStruct objects, providing a more Ruby-like interface for effortless interaction.

• Comprehensive Documentation: All methods are thoroughly documented, ensuring that developers have access to clear and concise information on the functionality and usage of each feature. This commitment to documentation enhances the gem's usability and simplifies the integration process.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add mtn_open_api -v 0.1.1

OR

gem 'mtn_open_api', '0.1.1'

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install mtn_open_api -v 0.1.1

Usage

MtnOpenApi::SandboxProvisioning

Sandbox User Provisioning

This class provides a convenient interface for making requests to the MTN MoMo sandbox-provisioning-api API.

Initialization

You can initialize it with the following parameters:

• base_url (optional): The base URL for the MTN MoMo sandbox-provisioning-api API. If not provided, the default value is https://sandbox.momodeveloper.mtn.com.
• headers (optional): A hash of HTTP headers to be included in the API requests.
• schema (optional): A hash representing the API schema. If not provided, the gem will use the default schema, which is already included in the gem. You can also download the schema from https://momodeveloper.mtn.com/API-collections#api=sandbox-provisioning-api.

Example

common_headers = {
  "Authorization": "string",
  "X-Callback-Url": "string",
  "X-Target-Environment": "string",
  "Ocp-Apim-Subscription-Key": "string"
}

sandboxprovisioning = MtnOpenApi::SandboxProvisioning.new(
  headers: common_headers
)

params = {
  "providerCallbackHost": "string"
}

extra_headers = {
  "X-Reference-Id": "string"
}

response = sandboxprovisioning.postV10Apiuser(params, extra_headers)

Methods

• postV10Apiuser Used to create an API user in the sandbox target environment.
• postV10ApiuserApikey Used to create an API key for an API user in the sandbox target environment.
• getV10Apiuser Used to get API user information.

MtnOpenApi::Collection

Enable remote collection of bills, fees or taxes

This class provides a convenient interface for making requests to the MTN MoMo collection API.

Initialization

You can initialize it with the following parameters:

• base_url (optional): The base URL for the MTN MoMo collection API. If not provided, the default value is https://sandbox.momodeveloper.mtn.com/collection.
• headers (optional): A hash of HTTP headers to be included in the API requests.
• schema (optional): A hash representing the API schema. If not provided, the gem will use the default schema, which is already included in the gem. You can also download the schema from https://momodeveloper.mtn.com/API-collections#api=collection.

Example

common_headers = {
  "Authorization": "string",
  "X-Callback-Url": "string",
  "X-Target-Environment": "string",
  "Ocp-Apim-Subscription-Key": "string"
}

collection = MtnOpenApi::Collection.new(
  headers: common_headers
)

params = {
  "amount": "string",
  "currency": "string",
  "externalId": "string",
  "payer": {
    "partyIdType": "MSISDN",
    "partyId": "string"
  },
  "payerMessage": "string",
  "payeeNote": "string"
}

extra_headers = {
  "X-Reference-Id": "string"
}

response = collection.requesttoPay(params, extra_headers)

Methods

• getAccountBalance Get the balance of own account.
• validateAccountHolderStatus Operation is used to check if an account holder is registered and active in the system.
• requesttoPay This operation is used to request a payment from a consumer (Payer). The payer will be asked to authorize the payment. The transaction will be executed once the payer has authorized the payment. The requesttopay will be in status PENDING until the transaction is authorized or declined by the payer or it is timed out by the system. Status of the transaction can be validated by using the GET /requesttopay/<resourceId>
• requesttoPayTransactionStatus This operation is used to get the status of a request to pay. X-Reference-Id that was passed in the post is used as reference to the request.
• bcAuthorize This operation is used to claim a consent by the account holder for the requested scopes.
• getBasicUserinfo This operation returns personal information of the account holder. The operation does not need any consent by the account holder.
• requesttoPayDeliveryNotification This operation is used to send additional Notification to an End User.
• getAccountBalanceInSpecificCurrency Get the balance of own account. Currency parameter passed in GET
• requestToWithdrawV1 This operation is used to request a withdrawal (cash-out) from a consumer (Payer). The payer will be asked to authorize the withdrawal. The transaction will be executed once the payer has authorized the withdrawal
• requestToWithdrawV2 This operation is used to request a withdrawal (cash-out) from a consumer (Payer). The payer will be asked to authorize the withdrawal. The transaction will be executed once the payer has authorized the withdrawal
• requestToWithdrawTransactionStatus This operation is used to get the status of a request to withdraw. X-Reference-Id that was passed in the post is used as reference to the request.
• createInvoice A merchant may use this in order to create an invoice that can be paid by an intended payer via any channel at a later stage.
• getInvoiceStatus This operation is used to get the status of an invoice. X-Reference-Id that was passed in the post is used as reference to the request
• cancelInvoice This operation is used to delete an invoice. The ReferenceId is associated with the invoice to be cancelled
• preApproval Preapproval operation is used to create a pre-approval.
• getPreApprovalStatus This operation is used to get the status of a pre-approval. X-Reference-Id that was passed in the post is used as reference to the request.
• createOauth2token This operation is used to claim a consent by the account holder for the requested scopes.
• getUserInfoWithConsent This operation is used to claim a consent by the account holder for the requested scopes.
• createAccessToken This operation is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.
• createPayments Making it possible to perform payments via the partner gateway. This may be used to pay for external bills or to perform air-time top-ups.
• getPaymentStatus This operation is used to get the status of a Payment. X-Reference-Id that was passed in the post is used as reference to the request

MtnOpenApi::Disbursement

Automatically deposit funds to multiple users

This class provides a convenient interface for making requests to the MTN MoMo disbursement API.

Initialization

You can initialize it with the following parameters:

• base_url (optional): The base URL for the MTN MoMo disbursement API. If not provided, the default value is https://sandbox.momodeveloper.mtn.com/disbursement.
• headers (optional): A hash of HTTP headers to be included in the API requests.
• schema (optional): A hash representing the API schema. If not provided, the gem will use the default schema, which is already included in the gem. You can also download the schema from https://momodeveloper.mtn.com/API-collections#api=disbursement.

Example

common_headers = {
  "Authorization": "string",
  "X-Callback-Url": "string",
  "X-Target-Environment": "string",
  "Ocp-Apim-Subscription-Key": "string"
}

disbursement = MtnOpenApi::Disbursement.new(
  headers: common_headers
)

params = "login_hint=ID:{msisdn}/MSISDN&scope={scope}&access_type={online/offline}"

extra_headers = {}

response = disbursement.bcAuthorize(params, extra_headers)

Methods

• getAccountBalance Get the balance of own account.
• validateAccountHolderStatus Operation is used to check if an account holder is registered and active in the system.
• getTransferStatus This operation is used to get the status of a transfer. X-Reference-Id that was passed in the post is used as reference to the request.
• getBasicUserinfo This operation returns personal information of the account holder. The operation does not need any consent by the account holder.
• bcAuthorize This operation is used to claim a consent by the account holder for the requested scopes.
• getAccountBalanceInSpecificCurrency Get the balance of own account. Currency parameter passed in GET
• depositV1 deposit operation is used to deposit an amount from the owner’s account to a payee account.
  Status of the transaction can be validated by using the GET /deposit/{referenceId}
• depositV2 deposit operation is used to deposit an amount from the owner’s account to a payee account.
  Status of the transaction can be validated by using the GET /deposit/{referenceId}
• getDepositStatus This operation is used to get the status of a deposit. X-Reference-Id that was passed in the post is used as reference to the request.
• refundV1 refund operation is used to refund an amount from the owner’s account to a payee account.
  Status of the transaction can be validated by using the GET /refund/{referenceId}
• refundV2 refund operation is used to refund an amount from the owner’s account to a payee account.
  Status of the transaction can be validated by using the GET /refund/{referenceId}
• getRefundStatus This operation is used to get the status of a refund. X-Reference-Id that was passed in the post is used as reference to the request.
• createOauth2token This operation is used to claim a consent by the account holder for the requested scopes.
• getUserInfoWithConsent This operation is used to claim a consent by the account holder for the requested scopes.
• createAccessToken This operation is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.
• transfer Transfer operation is used to transfer an amount from the own account to a payee account.
  Status of the transaction can validated by using the GET /transfer/{referenceId}

MtnOpenApi::Remittance

Remit funds to local recipients from the diaspora with ease

This class provides a convenient interface for making requests to the MTN MoMo remittance API.

Initialization

You can initialize it with the following parameters:

• base_url (optional): The base URL for the MTN MoMo remittance API. If not provided, the default value is https://sandbox.momodeveloper.mtn.com/remittance.
• headers (optional): A hash of HTTP headers to be included in the API requests.
• schema (optional): A hash representing the API schema. If not provided, the gem will use the default schema, which is already included in the gem. You can also download the schema from https://momodeveloper.mtn.com/API-collections#api=remittance.

Example

common_headers = {
  "Authorization": "string",
  "X-Callback-Url": "string",
  "X-Target-Environment": "string",
  "Ocp-Apim-Subscription-Key": "string"
}

remittance = MtnOpenApi::Remittance.new(
  headers: common_headers
)

params = {
  "amount": "string",
  "currency": "string",
  "externalId": "string",
  "payee": {
    "partyIdType": "MSISDN",
    "partyId": "string"
  },
  "payerMessage": "string",
  "payeeNote": "string"
}

extra_headers = {
  "X-Reference-Id": "string"
}

response = remittance.transfer(params, extra_headers)

Methods

• getAccountBalance Get the balance of own account.
• validateAccountHolderStatus Operation is used to check if an account holder is registered and active in the system.
• transfer Transfer operation is used to transfer an amount from the own account to a payee account.
  Status of the transaction can validated by using the GET /transfer/{referenceId}
• getTransferStatus This operation is used to get the status of a transfer. X-Reference-Id that was passed in the post is used as reference to the request.
• getBasicUserinfo This operation returns personal information of the account holder. The operation does not need any consent by the account holder.
• bcAuthorize This operation is used to claim a consent by the account holder for the requested scopes.
• getAccountBalanceInSpecificCurrency Get the balance of own account. Currency parameter passed in GET
• createOauth2token This operation is used to claim a consent by the account holder for the requested scopes.
• getUserInfoWithConsent This operation is used to claim a consent by the account holder for the requested scopes.
• createAccessToken This operation is used to create an access token which can then be used to authorize and authenticate towards the other end-points of the API.
• cashTransfer Cash transfer operation is used to transfer an amount from the owner’s account to a payee account. Status of the transaction can be validated by using GET /cashtransfer/{referenceId}
• getCashTransferStatus This operation is used to get the status of a transfer. X-Reference-Id that was passed in the post is used as reference to the request.

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/koodeyo/mtn_open_api.