Mukalla Telecom Pro REST API Documentation

Comprehensive guide to integrate with our payment platform and telecom services

REST API v1.0 Secure 7 November 2025

Get Started Here

Everything you need to begin integrating with our API

Welcome to the API Documentation

This documentation explains how to work with the API service of our Payment platform. Please read all instructions carefully to ensure successful integration.

Required Credentials

The following essential variables are required to integrate with our API services:

UserName

Your account username

Password

Your account password

AccountNumber

Your unique account identifier

API Token

Your API authentication token

API Configuration

Request Method POST
Content-Type application/json
Response Format JSON
Character Encoding UTF-8
Important Security Notice
  • Keep your API credentials secure and never expose them in client-side code
  • Use HTTPS for all API requests to ensure data encryption
  • Implement proper error handling to avoid exposing sensitive information
  • Rotate your API tokens regularly for enhanced security

Generate Login Token

Learn how to generate authentication tokens for API access

Generate Login Token and access token generation are performed by sending AccountNumber, UserName, and Token in the request body fields.

Token Generation Formula

The Token field is generated using MD5 hashing with the following formula:

Formula 
Token = md5(UserName + AccountNumber + md5(Password) + APIToken)

Example in PHP

PHP 
$token = md5($UserName . $AccountNumber . md5($Password) . $ApiToken);

Example in C#

C# 
using System;
using System.Security.Cryptography;
using System.Text;

public class Program
{
    public static void Main()
    {
        string UserName = "YourUserName";
        string AccountNumber = "YourAccountNumber";
        string Password = "YourPassword";
        string ApiToken = "YourApiToken";
        string token = GenerateToken(UserName, AccountNumber, Password, ApiToken);
        Console.WriteLine(token);
    }

    public static string GenerateToken(string userName, string accountNumber, string password, string apiToken)
    {
        string innerMd5 = GetMd5Hash(password);
        string concatenatedString = userName + accountNumber + innerMd5 + apiToken;
        return GetMd5Hash(concatenatedString);
    }

    private static string GetMd5Hash(string input)
    {
        using (MD5 md5 = MD5.Create())
        {
            byte[] inputBytes = Encoding.UTF8.GetBytes(input);
            byte[] hashBytes = md5.ComputeHash(inputBytes);
            StringBuilder sb = new StringBuilder();
            for (int i = 0; i < hashBytes.Length; i++)
            {
                sb.Append(hashBytes[i].ToString("x2"));
            }
            return sb.ToString();
        }
    }
}
Next Steps

Once you've generated your token, you can proceed to the Login endpoint to obtain your access token for making authenticated API requests.

Networks Data

Available network providers and their identifiers

Each network has a unique identifier (Network Number) that you'll use when making API requests. Reference this table to find the correct network number for your operations.

Network Number Description

Services Data

Complete list of available services across all networks

Services are organized by network. Each service has a unique Service Number that corresponds to a specific network operation. Use these numbers in your API requests to specify which service you want to access.

Network Number Service Number Description

API Endpoints

Complete reference for all available API endpoints

Login

Authentication
POST
https://mukallatelecompro.nflow.tech/rest-api/login

Obtain an access token by sending a login request. The access_token received will be used in all subsequent requests.

The response includes an access_token (for future requests) and token_expires (token expiration date and time). Ensure the access token is valid before making requests; otherwise, generate a new one.

Request Body
Field Name Description Required
AccountNumber Your account number on our platform Required
UserName Your username on our platform Required
Token Generated token using the formula described in Generate Login Token Required
Response Examples
Success Response
JSON 
{
    "status": true,
    "message": "Login Successful",
    "access_token": "*********************",
    "token_expires": "2024-08-05 19:31:45"
}
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Global Operations

These operations relate to your account, such as viewing the balance, checking transaction status, and reviewing feed entries.

Important: In these requests, the NetworkNumber is typically set to 0. The ServiceNumber specifies the desired service from network 0.

Examples:

  • To check account balance: ServiceNumber = 1
  • To check transaction status: ServiceNumber = 2
  • To view feed vouchers: ServiceNumber = 3

Get Account Balance

Query
POST
https://mukallatelecompro.nflow.tech/rest-api/

Retrieve your current account balance.

Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 1 Service Number for balance query
Response Examples
Success Response
JSON 
{
    "status": true,
    "agentBalance": 100,
    "message": "Agent Balance Query Success",
    "transactionID": 0
}
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Get Operation Status

Query
POST
https://mukallatelecompro.nflow.tech/rest-api/

Check the status of a specific operation using your transaction ID.

To check an operation's status, send a request with ServiceNumber = 2 and include your system's TransactionID.

The response includes:

  • status: Overall request status
  • operationStatus: Transaction status (1: Ready, 0: Failed, -1: Pending)
  • mobileNumber: Phone number
  • price: Transaction price
  • message: Status message
  • details: Additional transaction notes
  • transactionID: Your system's transaction number
  • referenceID: Our system's transaction number
Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 2 Service Number for status query
TransactionID Your Transaction ID Transaction ID from your system
Response Examples
Operation Success Response
JSON 
{
    "status": true,
    "operationStatus": 1,
    "mobileNumber": "777777777",
    "price": 100,
    "message": "جاهزة",
    "details": "Operation Notes",
    "transactionID": 1234,
    "referenceID": 4321
}
Operation Pending Response
JSON 
{
    "status": true,
    "operationStatus": -1,
    "mobileNumber": "777777777",
    "price": 100,
    "message": "في الانتظار",
    "details": "Operation Notes",
    "transactionID": 1234,
    "referenceID": 4321
}
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Get Feed Clients Balance

Query
POST
https://mukallatelecompro.nflow.tech/rest-api/

Display the feed vouchers that have been added to your account.

The response will include a data array of objects. Each object contains:

  • Date: The date of the document
  • Amount: The amount that was added
  • Currency: The name of the currency
  • Notes: Any notes related to the document
Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 3 Service Number for clients balance
Response Example
JSON 
{
    "status": true,
    "data": [
        {
            "Date": "2024-08-03",
            "Amount": "70000.00000",
            "Currency": "ريال يمني",
            "Notes": "Notes"
        },
        {
            "Date": "2024-08-01",
            "Amount": "100000.00000",
            "Currency": "ريال يمني",
            "Notes": "Notes"
        }
    ],
    "message": "Query Success"
}
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Get Games and Gift Cards Categories

Query
POST
https://mukallatelecompro.nflow.tech/rest-api/

Retrieve a list of available games and gift card categories with pricing and requirements.

Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 4 Service Number for categories
Response Example
JSON 
{
  "status": true,
  "data": [
    {
      "TheNumber": 1,
      "ServiceName": "بـوبـجـي",
      "CategoryName": "بوبجي ( 60 شدة )",
      "GameUnitsCount": 60,
      "LinkCode": "pubg_60",
      "Price": 0.858,
      "CurrencyName": "دولار",
      "LocalPrice": 467.61,
      "LocalCurrencyName": "ريال يمني",
      "AllowFreeQuantity": false,
      "MinQuantity": 1,
      "MaxQuantity": 1,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    },
    {
      "TheNumber": 2,
      "ServiceName": "بـوبـجـي",
      "CategoryName": "بوبجي ( 120 شدة )",
      "GameUnitsCount": 120,
      "LinkCode": "pubg_120",
      "Price": 1.716,
      "CurrencyName": "دولار",
      "LocalPrice": 935.22,
      "LocalCurrencyName": "ريال يمني",
      "AllowFreeQuantity": false,
      "MinQuantity": 1,
      "MaxQuantity": 1,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    },
    {
      "TheNumber": 1626,
      "ServiceName": "يويو شات - Yoyo Chat",
      "CategoryName": "يويو  حسب الطلب",
      "GameUnitsCount": 1,
      "LinkCode": "YoyoChat",
      "Price": 0.0009,
      "CurrencyName": "دولار",
      "LocalPrice": 0.495,
      "LocalCurrencyName": "يمني",
      "AllowFreeQuantity": true,
      "MinQuantity": 250,
      "MaxQuantity": 1000000,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    }
  ],
  "message": "Success",
  "transactionID": 1
}
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Query Operations

Check balance, offers, and subscriptions for Yemeni telecom companies

POST
https://mukallatelecompro.nflow.tech/rest-api/

These requests are used to check the balance, offers, and subscriptions of subscribers of Yemeni telecom companies. Typically, the request data is structured as follows:

  • NetworkNumber: The network number through which the request will be made
  • ServiceNumber: The service inquiry number you want to request
  • MobileNumber: The subscriber's phone number
  • TransactionID: A unique transaction number for each request
Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber Example: 1 The network number through which the request will be made:
  • 1: Yemen Mobile
  • 5: ADSL
  • 6: Land Phone
  • 7: Yemen 4G
ServiceNumber 101 The service inquiry number you want to request:
  • 101: Get Yemen Mobile Balance
  • 102: Get Yemen Mobile Loan
  • 107: Get Yemen Mobile Offers
  • 501: Get ADSL Balance
  • 601: Get Land Phone Balance
  • 701: Get Yemen 4G Balance
MobileNumber 7XXXXXXXX - 0XXXXXXX - 10XXXXXX Mobile number to query
TransactionID XXXXXXXXX A unique transaction number for each request. This number must be unique for every request
Response Examples
Yemen Mobile Balance Success Response
JSON 
{
    "status": true,
    "mobileBalance": 154.15,
    "availableCredit": "",
    "mobileType": 1,
    "mobileTypeName": "دفع مسبق",
    "message": "Balance Query Success",
    "transactionID": 0
}
mobileType: The type of subscriber - 1: Prepaid, 2: Postpaid
Yemen Mobile Loan Success Response
JSON 
{
    "status": true,
    "loanStatus": false,
    "loanStatusString": "الرقم غير متسلف",
    "message": "Balance Query Success"
}
Yemen Mobile Offers Success Response
JSON 
{
    "status": true,
    "data": [
        {
            "offerID": "A115887147",
            "offerName": "شريحه 4G",
            "offerStartDate": "2020-01-01 03:00:00",
            "offerEndDate": "2037-01-01 00:00:00"
        },
        {
            "offerID": "A4990006",
            "offerName": "باقة مزايا فورجي فولتي الشهريه دفع مسبق",
            "offerStartDate": "2024-07-21 17:14:06",
            "offerEndDate": "2024-08-19 23:59:59"
        },
        {
            "offerID": "A3825",
            "offerName": "دفع مسبق باقة نت توفير فورجي 5 جيجا الشهرية",
            "offerStartDate": "2024-07-26 18:01:40",
            "offerEndDate": "2024-08-24 23:59:59"
        }
    ],
    "message": "Balance Query Success"
}
ADSL Balance Success Response
JSON 
{
    "status": true,
    "mobileBalance": "44.18 جيجابايت",
    "expiredDate": "21/10/2024",
    "offerAmount": "12600",
    "minAmount": "250",
    "message": "Balance Query Success",
    "transactionID": "1"
}
Landphone Balance Success Response
JSON 
{
    "status": true,
    "mobileBalance": "2869",
    "message": "Balance Query Success",
    "transactionID": "1"
}
Yemen 4G Balance Success Response
JSON 
{
    "status": true,
    "mobileBalance": "26.90جيجابايت",
    "expiredDate": "2024-11-06",
    "offerAmount": "2400",
    "offerSize": "2400",
    "callBalance": "",
    "message": "Balance Query Success",
    "transactionID": "1"
}
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Payment Operations

Execute payment transactions for balance, offers, and gaming services

Optional Webhook Fields

Optional fields can be included in all payment operations requests:

  • WebHookURL: A URL in your system that our platform will call when the status of the order changes. This allows your system to receive updates without the need to query the transaction status manually.
  • WebHookCode: An optional code or password for the transaction. It will be sent along with the request to the WebHook URL provided in the request. This code acts as a signature for the transaction and helps prevent conflicts. It is recommended that this code be unique for each transaction.

Payment Balance

Payment
POST
https://mukallatelecompro.nflow.tech/rest-api/
Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber Example: 1 The network number you want to use
ServiceNumber Example: 103 The service number you wish to request
MobileNumber 7XXXXXXXX - 0XXXXXXX - 10XXXXXX The subscriber's mobile phone number
Amount 100 The payment amount or the amount you wish to charge to the mobile number. Note:
  • Sabafon, YOU, and Y Telecom: The amount is the number of units to charge. This amount will be multiplied by the unit price specified in our system. For example, if the unit price in our system is 1.21 and you send an amount of 10, the total transaction price will be 12.1.
  • Yemen Mobile, Landline, ADSL, and Yemen 4G: The amount is the value to be charged or paid to the subscriber's number.
TransactionID xxx A unique transaction ID in your system. Each transaction must have a unique ID, and the same ID cannot be used for multiple transactions.
WebHookURL Optional https://your-domain.com/webhook A URL in your system that our platform will call when the status of the order changes
WebHookCode Optional xxxxxxxxx An optional code or password for the transaction. It will be sent along with the request to the WebHook URL
Response Example
Success Response
JSON 
{
    "status": true,
    "operationStatus": 1,
    "agentBalance": 2445990.29131,
    "price": 5227,
    "message": "Payment success",
    "transactionID": "1",
    "referenceID": 243085
}
Response Fields:
  • status: The overall status of the request. If true, it indicates that the request was successful as a whole.
  • operationStatus: The status of the operation. Values: 1: Successful, 0: Failed, -1: Pending
  • agentBalance: The agent's balance after the transaction.
  • price: The price of the transaction.
  • message: Notes or remarks about the transaction.
  • transactionID: The unique transaction ID sent from your side.
  • referenceID: The reference ID for the transaction from our platform.
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Payment Offers

Payment
POST
https://mukallatelecompro.nflow.tech/rest-api/

For requesting payment offers to telecom companies.

Instead of the Amount field, use the OfferCode field. The OfferCode is the code of the offer or package you want to request from our platform.

Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber Example: 2 The network number through which the request will be made
ServiceNumber Example: 202 The service inquiry number you want to request
MobileNumber 7XXXXXXXX - 73XXXXX - 71XXXXXX - 70XXXXXX The subscriber's mobile phone number
OfferCode PREWhatsApp The Offer Link Code
TransactionID xxx A unique transaction ID in your system
WebHookURL Optional https://your-domain.com/webhook A URL in your system for status updates
WebHookCode Optional xxxxxxxxx Optional code for transaction verification
Response Example
JSON 
{
    "status": true,
    "operationStatus": 1,
    "agentBalance": 2445990.29131,
    "price": 5227,
    "message": "Payment success",
    "transactionID": "1",
    "referenceID": 243085
}
Response Fields:
  • status: The overall status of the request. If true, it indicates that the request was successful as a whole.
  • operationStatus: The status of the operation. Values: 1: Successful, 0: Failed, -1: Pending
  • agentBalance: The agent's balance after the transaction.
  • price: The price of the transaction.
  • message: Notes or remarks about the transaction.
  • transactionID: The unique transaction ID sent from your side.
  • referenceID: The reference ID for the transaction from our platform.
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Payment Game Services and Gift Cards

Payment
POST
https://mukallatelecompro.nflow.tech/rest-api/
Request Headers
Header Name Value Description
api-token access_token from Login Request Access token obtained from the Login endpoint
Content-Type application/json Specifies the media type of the resource
Request Fields
Field Name Value Description
NetworkNumber Example: 8 The network number through which the request will be made
ServiceNumber Example: 801 The service inquiry number you want to request
MobileNumber Mobile number to recharge (if applicable)
LinkCode Example: pubg_60 The category or service code on our platform for which you want to create an order. Get this from Get Games and Gift Cards Categories Request
Fields
JSON 
{
  "ZoneID": "ThePlayerZoneID",
  "PlayerID": "ThePlayerID",
  "EmailAddress": "TheEmailAddress"
}
 Field in JSON format. This field contains the necessary information for the requested category, such as the player's ID or email
Quantity 1 The quantity field is used in game charging categories that allow free quantities such as the number of coins or gold coins
TransactionID xxx A unique transaction ID in your system
WebHookURL Optional https://your-domain.com/webhook A URL in your system for status updates
WebHookCode Optional xxxxxxxxx Optional code for transaction verification
Response Example
JSON 
{
    "status": true,
    "operationStatus": 1,
    "agentBalance": 2445990.29131,
    "price": 5227,
    "message": "Payment success",
    "transactionID": "1",
    "referenceID": 243085
}
Response Fields:
  • status: The overall status of the request. If true, it indicates that the request was successful as a whole.
  • operationStatus: The status of the operation. Values: 1: Successful, 0: Failed, -1: Pending
  • agentBalance: The agent's balance after the transaction.
  • price: The price of the transaction.
  • message: Notes or remarks about the transaction.
  • transactionID: The unique transaction ID sent from your side.
  • referenceID: The reference ID for the transaction from our platform.
Error Response
JSON 
{
    "status": false,
    "message": "Error Message"
}

Example Webhook Request

If you set the WebHookURL to https://your-domain.com/webhook and the WebHookCode to xxxxxxxxx, our platform will send a request to your system upon updating the operation as follows:

Endpoint: https://your-domain.com/webhook
Method: GET
Parameters
JSON Format (for clarity) 
{
    "OperationStatus": 1,
    "WebHookCode": "xxxxxxxxx",
    "TransactionID": "TransactionID From Your System",
    "ReferenceID": 220065,
    "price": 507.87,
    "message": "Order Success"
}

Note: The parameters will not be in JSON format in the actual request. They are shown here in JSON format for clarity. The parameters will be sent as a query string in the URL.

Parameter Descriptions
Parameter Description
OperationStatus The status of the operation. Possible values: 0: Failed, 1: Ready
WebHookCode The code provided by you when creating the order to prevent conflicts
TransactionID The unique ID of the transaction in your system
ReferenceID The reference number or transaction ID on our platform
price The cost of the operation that will be charged to your account
message Notes or comments regarding the status of the operation
Example Request

The request sent to your WebHookURL will look like this:

cURL 
curl -G "https://your-domain.com/webhook" \
--data-urlencode "OperationStatus=1" \
--data-urlencode "WebHookCode=xxxxxxxxx" \
--data-urlencode "TransactionID=TXN789" \
--data-urlencode "ReferenceID=220065" \
--data-urlencode "price=507.87" \
--data-urlencode "message=Order received and under process"