This documentation is intended for developers who wish to integrate MaishaPay payment on an e-commerce site. This documentation is not tied to any specific technology. The developer is free to perform the integration with any web or mobile tool. It combines HTML, JavaScript, and CSS to invoke an embedded payment form. When your customer enters their payment information, the details are verified and validated so that your server-side code can execute.
It requires both the public and secret API keys of the merchant corresponding to the mode in which the account is set 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 from the 'Developer' menu in the account. It is important to note that all requests sent to our servers must include these elements for a better experience.
1. Retrieval of 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
Accessing MaishaPay Checkout involves using an HTML form where the action attribute points to the URL below, with requests being of the POST type.
< form action="http://maishapay.test/payment/vers1.0/merchant/checkout" method="POST" >
3. Payment Form
Add the following code to the payment page of your platform, ensuring that the information contained in this form is sent via your server-side code:
<form action="https://marchand.maishapay.online/payment/vers1.0/merchant/checkout" method="POST">
<input type="hidden" name="gatewayMode" value=0> // required, 0 : SandBox 1 : Live
<input type="hidden" name="publicApiKey" value="MP-SBPK-xxxxxxx">// required
<input type="hidden" name="secretApiKey" value="MP-SBSK-wwwwww">// required
<input type="hidden" name="montant" value="{TOTAL_AMOUNT}">// required
<input type="hidden" name="devise" value="{USD|CDF|FCFA|EURO}">// required
<input type="hidden" name="callbackUrl" value="{callback Url}">// nullable
<input type="submit" value="Payer">
</form>
Important: Before going live, you must have completed at least one successful payment in SANDBOX (Test) mode.
| setting | Mandatory | Description |
|---|---|---|
[gatewayMode] |
Oui | The Mode your account is in at the time of the request. 0 : SandBox (Test) et 1 : Live |
[publicApiKey] |
Oui | the public API key retrieved in the developer section |
[secretApiKey] |
Oui | the secret API key retrieved in the developer section |
[montant] |
Oui | The net amount of the transaction. i.e. the fees related to each transaction are deducted at the API level |
[devise] |
Non | the currency of the transaction. choose between USD, CDF, FCFA or EURO. |
[callbackUrl] |
Non | If this variable exists, regardless of the client's choice or the outcome of the transaction, a POST request is redirected to the URL inserted as value. Otherwise, the client is notified directly via our server of the status of the transaction. |
If all expected parameters are present and valid, the client is redirected to our server to proceed to the next step. But, in case of an error during this call, MaishaPay will return information to help you modify your request.
4. Redirect to MaishaPay
The secure URL inserted in the previous step is used to redirect the user to MaishaPay servers to continue the transaction and complete the payment.
This is a classic HTTP redirect.
5. Payment confirmation
The customer is then redirected to the MaishaPay site for :
- Enter the Orange Money telephone number to use to make the payment ;
- Confirm that you have read the general conditions of use ;
- Validate the payment request.
6. Sending the payment request to the customer's phone
MaishaPay uses the services of telephone operators to transmit the payment request to the telephone number provided by the customer.
A menuUSSD on the telephone which allows the customer to confirm or cancel the payment.
7. Customer notification
The customer receives a message on their phone confirming the transaction and transferring the funds in the case of a successful transaction, or a message cancelling the transaction.
7. Notification of the status of the transaction on your merchant site
The customer receives a message on their phone confirming the transaction and transferring the funds in the case of a successful transaction, or a message cancelling the transaction.
8. Merchant site notification callbackUrl
Le callbackUrl or return link, allows you to automatically redirect your customer to a specific page of your choice, once he has reached the end of the transaction settlement process.
This link will also return the transaction status: status, the description: description, the transaction reference: transactionRefId and the payment reference to the operator: operatorRefId.
Optional status. In the event that you do not provide this value, the customer will be directed to one of our pages indicating the transaction status.
Exemple
With the return link specified for an approved transaction
https://www.mywebsite.com/?status=202&description=Accepted&transactionRefId=1234&operatorRefId=ABCD
Dans cet exemple, le lien par https://www.mywebsite.com/ est celui que vous spécifié comme callbackUrl.