Al-Qimah REST-API Documentation

📄 Get Started Here

This documentation explains how to work with the API service of our Payment platform.

📃 Please read all instructions carefully.

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

  • UserName
  • Password
  • AccountNumber
  • API Token
  • Request Method: POST
  • Content-Type: application/json

Generate Login Token

Generate Login Token and access token generation are performed by sending AccountNumber, UserName, and Token in the request body fields. Below is the method to generate the Token field:

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

Example in PHP

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

Example in 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();
        }
    }
}

Networks Data

Network Number Description

Services Data

Network Number Service Number Description

Endpoints

Login

POST https://softibs.com/rest-api/login

To obtain the access token, send 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 Yes
UserName Your username on our platform Yes
Token Generate Login Token Yes
Response Type Response Example
Success Response 
{
    "status": true,
    "message": "Login Successful",
    "access_token": "*********************",
    "token_expires": "2024-08-05 19:31:45"
}
Error Response 
{
    "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.

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

For example:

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

Get Account Balance

POST https://softibs.com/rest-api/

To retrieve your account balance.

Request Headers
Header Name Value Description
api-token access_token From Login Request Access token from Login request
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 1 Service Number for balance query
Response Type Response Example
Success Response 
{
    "status": true,
    "agentBalance": 100,
    "message": "Agent Balance Query Success",
    "transactionID": 0
}
Error Response 
{
    "status": false,
    "message": "Error Message"
}

Get Operation Status

POST https://softibs.com/rest-api/

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 from Login request
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 2 Service Number for status query
TransactionID Transaction ID from your system
Response Type Response Example
Operation Success Response 
{
    "status": true,
    "operationStatus": 1,
    "mobileNumber": "777777777",
    "price": 100,
    "message": "جاهزة",
    "details": "Operation Notes",
    "transactionID": 1234,
    "referenceID": 4321
}
Operation Failed Response 
{
  "status": true,
  "operationStatus": 0,
  "mobileNumber": "777777777",
  "price": 100,
  "message": "ملغية",
  "details": "Operation Notes",
  "transactionID": 1234,
  "referenceID": 4321
}
Operation Pending Response 
{
  "status": true,
  "operationStatus": -1,
  "mobileNumber": "777777777",
  "price": 100,
  "message": "في الانتظار",
  "details": "Operation Notes",
  "transactionID": 1234,
  "referenceID": 4321
}
Error Response 
{
    "status": false,
    "message": "Error Message"
}

Get Feed Clients Balance

POST https://softibs.com/rest-api/

This request is used to display the feed vouchers that have been added to your account with us. The response will include an element named data, which is an array of objects. Each object contains the following properties:

  • Date: The date of the document.
  • Amount: The amount that was added.
  • Currency: The name of the currency in which the amount was added.
  • Notes: Any notes related to the document.
Request Headers
Header Name Value Description
api-token access_token From Login Request Access token from Login request
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 3 Service Number for clients balance
Response Type Response Example
Success Response 
{
  "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 
{
    "status": false,
    "message": "Error Message"
}

Get Games and Gift Cards Categories

POST https://softibs.com/rest-api/

To retrieve a list of available games and gift card categories.

Request Headers
Header Name Value Description
api-token access_token From Login Request Access token from Login request
Request Fields
Field Name Value Description
NetworkNumber 0 Global Network Number
ServiceNumber 4 Service Number for categories
Response Type Response Example
Success Response 
{
  "status": true,
  "data": [
    {
      "TheNumber": 968,
      "ServiceName": "شدات بوبجي - Pubg UC",
      "CategoryName": "شدات بوبجي ( 60 شدة )",
      "GameUnitsCount": 60,
      "LinkCode": "pubg_60",
      "Price": 0.9,
      "CurrencyName": "دولار",
      "LocalPrice": 495,
      "LocalCurrencyName": "ريال يمني",
      "AllowFreeQuantity": false,
      "MinQuantity": 1,
      "MaxQuantity": 1,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    },
    {
      "TheNumber": 969,
      "ServiceName": "شدات بوبجي - Pubg UC",
      "CategoryName": "شدات بوبجي ( 120 شدة )",
      "GameUnitsCount": 120,
      "LinkCode": "pubg_120",
      "Price": 1.81,
      "CurrencyName": "دولار",
      "LocalPrice": 995.5,
      "LocalCurrencyName": "ريال يمني",
      "AllowFreeQuantity": false,
      "MinQuantity": 1,
      "MaxQuantity": 1,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    },
    {
      "TheNumber": 970,
      "ServiceName": "شدات بوبجي - Pubg UC",
      "CategoryName": "شدات بوبجي ( 325 شدة )",
      "GameUnitsCount": 325,
      "LinkCode": "pubg_325",
      "Price": 4.38,
      "CurrencyName": "دولار",
      "LocalPrice": 2409,
      "LocalCurrencyName": "ريال يمني",
      "AllowFreeQuantity": false,
      "MinQuantity": 1,
      "MaxQuantity": 1,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    },
    {
      "TheNumber": 971,
      "ServiceName": "شدات بوبجي - Pubg UC",
      "CategoryName": "شدات بوبجي ( 385 شدة )",
      "GameUnitsCount": 385,
      "LinkCode": "pubg_385",
      "Price": 5.2,
      "CurrencyName": "دولار",
      "LocalPrice": 2860,
      "LocalCurrencyName": "ريال يمني",
      "AllowFreeQuantity": false,
      "MinQuantity": 1,
      "MaxQuantity": 1,
      "RequiredFields": [
        {
          "FieldCode": "PlayerID",
          "FieldName": "رقم ايدي - اللاعب"
        }
      ]
    }
  ],
  "message": "Success",
  "transactionID": "1"
}
Error Response 
{
    "status": false,
    "message": "Error Message"
}

Query Operations

POST https://softibs.com/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. This number must be unique for every request.
Request Headers
Header Name Value Description
api-token access_token From Login Request Access token from Login request
Request Fields
Field Name Value Description
NetworkNumber Example: 1 The network number through which the request will be made :
  • 1: Yemen Mobile
  • 5: Balance
  • 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 Type Response Example Description
Yemen Mobile Balance Success Response 
{
  "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 
{
  "status": true,
  "loanStatus": false,
  "loanStatusString": "الرقم غير متسلف",
  "message": "Balance Query Success"
}
Yemen Mobile Offers Success Response 
{
  "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"
    },
    {
      "offerID": "A101044",
      "offerName": "CDMA voice offer",
      "offerStartDate": "2024-07-09 11:01:20",
      "offerEndDate": "2037-01-01 00:00:00"
    },
    {
      "offerID": "A101045",
      "offerName": "خدمة فولتي - VoLTE",
      "offerStartDate": "2024-07-09 11:01:20",
      "offerEndDate": "2037-01-01 00:00:00"
    },
    {
      "offerID": "A101051",
      "offerName": "VoLTE international toll offer",
      "offerStartDate": "2024-07-09 11:01:27",
      "offerEndDate": "2037-01-01 00:00:00"
    }
  ],
  "message": "Balance Query Success"
}
ADSL Balance Success Response 
{
  "status": true,
  "mobileBalance": "44.18 جيجابايت",
  "expiredDate": "21/10/2024",
  "offerAmount": "12600",
  "minAmount": "250",
  "message": "Balance Query Success",
  "transactionID": "1"
}
Landphone Balance Success Response 
{
  "status": true,
  "mobileBalance": "2869",
  "message": "Balance Query Success",
  "transactionID": "1"
}
Yemen4G Balance Success Response 
{
  "status": true,
  "mobileBalance": "26.90جيجابايت",
  "expiredDate": "2024-11-06",
  "offerAmount": "2400",
  "offerSize": "2400",
  "callBalance": "",
  "message": "Balance Query Success",
  "transactionID": "1"
}
Error Response 
{
    "status": false,
    "message": "Error Message"
}

Payment Operations

Optional fields can also be included In All Payment Operations Requests, such as:
  • 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

POST https://softibs.com/rest-api/
Request Headers
Header Name Value Description
api-token access_token From Login Request Access token from Login request
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 that in some networks, this amount represents the number of units to be charged. For example:
  • 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. This allows your system to receive updates without the need to query the transaction status manually
WebHookCode   (optional ) xxxxxxxxx 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.
Response Type Response Example Description
Success Response 
{
  "status": true,
  "operationStatus": 1,
  "agentBalance": 2445990.29131,
  "price": 5227,
  "message": "Payment succcess",
  "transactionID": "1",
  "referenceID": 243085
}
  • 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. The values are defined as follows:
    • 1: Successful
    • 0: Failed
    • -1: Pending, which requires a re-check of the operation status.
  • 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 
{
    "status": false,
    "message": "Error Message"
}

Payment Offers

POST https://softibs.com/rest-api/

For Requesting Payment Offers to Telecom Companies

  • Instead of the Amount field, use the OfferCode field.
  • OfferCode: 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 from Login request
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. 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. This allows your system to receive updates without the need to query the transaction status manually
WebHookCode   (optional ) xxxxxxxxx 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.
Response Type Response Example Description
Success Response 
{
  "status": true,
  "operationStatus": 1,
  "agentBalance": 2445990.29131,
  "price": 5227,
  "message": "Payment succcess",
  "transactionID": "1",
  "referenceID": 243085
}
  • 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. The values are defined as follows:
    • 1: Successful
    • 0: Failed
    • -1: Pending, which requires a re-check of the operation status.
  • 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 
{
    "status": false,
    "message": "Error Message"
}

Payment Game Services and Gift Cards

POST https://softibs.com/rest-api/
Request Headers
Header Name Value Description
api-token access_token From Login Request Access token from Login request
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
LinkCode Example: pubg_60 The category or service code on our platform for which you want to create an order get is from Get Games and Gift Cards Categories Request
Fields 
{"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. Example format
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. 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. This allows your system to receive updates without the need to query the transaction status manually
WebHookCode   (optional ) xxxxxxxxx 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.
Response Type Response Example Description
Success Response 
{
  "status": true,
  "operationStatus": 1,
  "agentBalance": 2445990.29131,
  "price": 5227,
  "message": "Payment succcess",
  "transactionID": "1",
  "referenceID": 243085
}
  • 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. The values are defined as follows:
    • 1: Successful
    • 0: Failed
    • -1: Pending, which requires a re-check of the operation status.
  • 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 
{
    "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:
{
  "OperationStatus": 1,
  "WebHookCode": "xxxxxxxxx",
  "TransactionID": "TransactionID From Your System",
  "ReferenceID": 220065,
  "price": 507.87,
  "message": "Order Sucsses"
}

Parameter Descriptions:

  • OperationStatus: The status of the operation. Possible values are:
    • 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.

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.

Example Request:

The request sent to your WebHookURL will look like this:

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"