Docs REST API

This documentation describes the API (Application Programming Interface) used by Corporate Merchants to perform mobile money transactions server-to-server. This documentation is not tied to any specific technology. The developer is free to integrate it with any business application.

The API requires both the API keys (public and secret) from the merchant, corresponding to the mode in which the account is presented at the time of the request (Sandbox or Live), as well as the code related to the account status (0: Sandbox, 1: Live). All these parameters can be obtained in the "Developer" menu of the account. It should be noted that all requests sent to our servers must include these elements for an optimal experience.

1. Retrieving `API keys`

From the merchant site, you need to retrieve the API keys while verifying the account's operating mode.

 gatewayMode : 0 (SANDBOX)
publicApiKey : MP-SBPK-xxxxxxxxxxxxxx secretApiKey : MP-SBSK-xxxxxxxxxxxxxx

 gatewayMode : 1 (LIVE)
publicApiKey : MP-LIVEPK-xxxxxxxxxxxxxx secretApiKey : MP-LIVESK-xxxxxxxxxxxxxx

2.`EndPoints`

To initiate your request to our API, you need to specify the endpoint, keeping in mind that the requests are of the POST type.

                                        https://marchand.maishapay.online/api/payment/rest/vers1.0/merchant

3. Request Format

Requests sent to the API as well as the responses are in JSON format.

                                        
{
    "gatewayMode": 0, // required, 0 : SandBox 1 : Live
    "publicApiKey": "MP-SBPK-xxxxxxx", // required,
    "secretApiKey" : "MP-SBSK-wwwwww", // required
    "transactionReference": "ABCD", // required
    "amount":{double}, // required
    "currency" : "{USD, CDF,USD, CDF, FCFA, EURO}", // required USD, CDF, FCFA, EURO
    "customerFullName": "Jhon DOe", // nullable
    "customerPhoneNumber" : "+243xxxxxxxxx", // nullable
    "customerEmailAddress" : null, // nullable
    "chanel":"MOBILEMONEY", // required MOBILEMONEY
    "provider": "MPESA", // required MPESA, ORANGE, AITEL, AFRICEL, MTN
    "walletID" :"+24381xxxxx" // required
}

Important: Before moving to production, you must have completed at least one successful payment in SANDBOX (Test) mode.

Setting	Mandatory	Description
`[gatewayMode]`	Oui	The mode in which your account is set at the time of the request. 0: Sandbox (Test) and 1: Live
`[publicApiKey]`	Oui	The public API key retrieved from the developer section
`[secretApiKey]`	Oui	The secret API key retrieved from the developer section
`[transactionReference]`	Oui	A unique code corresponding to the transaction reference.
`[amount]`	Oui	The net amount of the transaction. Note that the fees associated with each transaction are deducted at the API level.
`[currency]`	Non	The currency of the transaction. Choose between USD, CDF, FCFA, or EUR.
`[customerFullName]`	Non	Optional: The full name of the customer making the payment.
`[customerPhoneNumber]`	Non	Optional: The customer's number if different from the number on which the transaction will be processed.
`[customerEmailAddress]`	Non	Optional: The customer's email address.
`[chanel]`	Oui	The method by which the payment will be made in the case of MOBILE MONEY.
`[provider]`	Oui	The telecom operator. MPESA, ORANGE, AIRTEL, AFRICEL, MTN.
`[walletID]`	Oui	The phone number to be used for the transaction.

In case of an error during this call, MaishaPay will return information to help you adjust your request.

4.Response Format

If all the expected parameters are present and valid, you will receive a JSON response in the following format:

                                        
{
    "headers": {},
    "original": {
        "status": 200,
        "data": {
            "originatingTransactionId": "bndgdbdgsb12345", // votre réference
            "statusCode": "202",
            "statusDescription": "Accepted",
            "transactionId": "108475", //notre reference
        }
    },
    "exception": null
}

5. Sending the payment request to the customer's phone.

MaishaPay contacts the telecom operators to send the payment request to the phone number provided by the customer.
Une menu USSD A USSD menu on the phone allows the customer to confirm or cancel the payment.

6. Customer Notification

The customer receives a message on their phone to confirm the transaction and process the funds in the case of a successful transaction, or a cancellation message if the transaction is aborted.