NAV Navbar
HTML Angular ReactJS

Menapay Payment Integration Document

This document is written for application developers who want to integrate Menapay payment solution to their system. This integration requires additional software development to call required APIs to make a payment.

Integration

There are several steps needed to be executed in order to integrate the MenaPay payment infrastructure. These steps are described in detail below for plain HTML and JS, Angular and ReactJS frameworks.

Payment Flow

If you integrate successfully with Menapay payment solution, an example payment will be performed as below:

  1. Buyer chooses "Pay with Menapay" option from several payment options.
  2. Merchant system passes the required payment information to the "MenaPay Payment Integration Script".
  3. MenaPay Payment Integration Script initializes the "MenaPay Payment Modal" on merchant system.
  4. Buyer scans the QR code on payment modal using Menapay Payment App.
  5. Menapay Payment App displays the payment details.
  6. Buyer approves the payment.
  7. Menapay informs both buyer and merchant system about the payment result and the MenaPay payment modal is closed automatically.

Script File Integration

Script File Integration:

<!-- JavaScript library can be imported to HTML by inserting the script tag below between head elements. -->

<head>
    <script src="https://menapay-integration-test.s3-eu-west-1.amazonaws.com/menaPayIntegration.min.js"></script>
</head>
// Script should be downloaded and local path of the javascript file must be added to the "index.html" file.

<head>
    <script src="https://menapay-integration-test.s3-eu-west-1.amazonaws.com/menaPayIntegration.min.js"></script>
</head>
// JavaScript library can be imported to a ReactJS project by inserting the script tag below between head elements in your "index.html".

<head>
    <script src="https://menapay-integration-test.s3-eu-west-1.amazonaws.com/menaPayIntegration.min.js"></script>
</head>

The first step is importing the MenaPay Payment Integration Script to your project. You can find the script files for staging and production environments from the links below:

Steps for importing the script file is different for each environment/framework. These steps are described on their respective tabs.

Function Integration

Function Integration

<!-- The Javascript function should be called when the option is selected. -->

PayWithMenaPay.pay(username, amount, currency, description, callbackSuccessUrl, callbackErrorUrl, merchantData, popupTimeout, callbackFunction);

// In order to call the function from Typescript, you should declare the variable.
declare var PayWithMenaPay: any;

// Then you can call the function
pay() {
    PayWithMenaPay.pay('e38266d4-1e5f-4063-ad8a-a61ec959eeee', 1, 'USD', '2 kg apple', 'https://api.merchant.com/success?id=1', 'https://api.merchant.com/error?id=1', 'merchantData', 3000, callbackFunction);
}

// The Javascript function can be called from jsx by reaching from the "window" element.

window.PayWithMenaPay.pay('e38266d4-1e5f-4063-ad8a-a61ec959eeee', 1, 'USD', '2 kg apple', 'https://api.merchant.com/success?id=1', 'https://api.merchant.com/error?id=1', 'merchantData', 3000, callbackFunction);

The second step is initializing the "MenaPay Payment Modal" when "Pay with Menapay" option is selected by the buyer. This can be achieved by calling payWithMenaPay function on script and passing the required information about the payment. You can find the function signature and the required parameters to it below.

PayWithMenaPay.pay(username, amount, currency, description, callbackSuccessUrl, callbackErrorUrl, merchantData, popupTimeout, callbackFunction);

Parameter Type Description
username string Username information of the user who is registered in the MenaPay system
amount number Product price
currency string Currency code. Supported currencies: DZD, BHD, EGP, IQD, JOD, KWD, LBP, LYD, MAD, OMR, SAR, SYP, TND, AED, YER, SDG, TRY, QAR, USD
description string Product name
callbackSuccessUrl string Callback url if the operation is successful
callbackErrorUrl string Callback url if an error occurs during operation
merchantData  string Information created by merchant for this payment
popupTimeout number (Optional) Duration in milliseconds before the payment popup is closed after a payment operation is completed. (Default: 5000)
callbackFunction function (Optional) Callback function that will be called after a payment operation is completed. See "Getting Payment Callbacks > JS Callback Function" below for details.


Steps for integrating the function is different for each environment/framework. These steps are described on their respective tabs.

Frame Element Integration

Frame Element Integration

<!-- div element should be placed in your current html. -->

<div id="payWithMenaPayOverlay"></div>
<div id="payWithMenaPayElement"></div>
// div element should be placed in your current html.

<div id="payWithMenaPayOverlay"></div>
<div id="payWithMenaPayElement"></div>
// div element should be placed in your current render method.

<div id="payWithMenaPayOverlay"></div>
<div id="payWithMenaPayElement"></div>

The last step is creating the divisions on your UI which will be the container for the MenaPay Payment Modal. The id and style of the element should exactly be like in the example.

Getting Payment Callbacks

There are 2 ways that can be used for receiving payment callbacks. First one is by providing a Javascript callback function while working with the script. And the second way is HTTP callback messages to the callback URLs that are provided while requesting the QR code.

JS Callback Function

You can provide an optional callback function as a parameter to the pay function and it will be called with the parameters below when the payment operation is completed.

Callback Function

function callbackFunction(paymentId, merchantData, status, payment, message, code, error) { ... }

Callback Parameters

Parameter Description
paymentId The unique id representing this payment on MenaPay
merchantData Data that is passed by merchant at the beginning of the payment
status Status of the payment
message Success or error message if exists.
payment Contains the details of the payment
code Error code if exists.
error Boolean value representing if it is an error response or not.

HTTP Callback Message

Callback Message

     {
         "data": {
             "paymentId": "string",
             "merchantData": "string",
             "status": "string",
             "payment": {
                 "description": "string",
                 "menaCashAmount": "number(Double)",
                 "customerId": "string",
                 "transactionId": "string",
                 "transactionCode": "string",
                 "timestamp": "date"
             } 
         },
         "message": "string",
         "code": "number",
         "error": "boolean"
     }

Menapay Server performs a POST request to the callback URLs that are provided while opening the payment popup.

Client is expected to send an empty HTTP 200 OK response to the callback request.

Callback Parameters

Parameter Description
paymentId The unique id representing this payment on MenaPay
merchantData Data that is passed by merchant at the beginning of the payment
status Status of the payment
payment Contains the details of the payment
message Success or error message if exists.
code Error code if exists.
error Boolean value representing if it is an error response or not.