Get started

The Jemeni.NET API enables interaction with its services, including user management, transactions, OTP verification, and payment handling

To use this API, you need an API key. Please sign in to get your own API key.

    {BASE_URL} : https://jemeni.net/api
    

Authentication Signature

To authenticate API requests, you need to include an auth-signature in the request headers. This signature is generated using the following formula:

    SHA-512(SK + "+" + TK + "+" + METHOD + "+" + URL + "+" + BODY_REQUEST + "+" + TIMESTAMP)
    

Parameters:

• SK: Secret Key (provided in your API credentials)
• TK: Token Key (your API access token)
• METHOD: HTTP Method (e.g., GET, POST, PUT, DELETE)
• URL: The full API endpoint URL
• BODY_REQUEST: The raw request body (empty string "" for GET requests)
• TIMESTAMP: Current UNIX timestamp (in seconds)

Example HTTP Request:

    POST /resource HTTP/1.1
    Host: api.example.com
    Authorization: Bearer your_token_key
    auth-signature: 2a4e9b10a57e4c3e7b2...
    Content-Type: application/json
    Timestamp: 1700000000

    {
        "data": "test"
    }
    

---

Implementation in Different Languages

🔹 C# Example

    using System;
    using System.Security.Cryptography;
    using System.Text;

    class Program
    {
        static void Main()
        {
            string secretKey = "your_secret_key"; // SK
            string tokenKey = "your_token_key";   // TK
            string method = "POST";               // HTTP Method
            string url ={BASE_URL} +"/resource"; // API URL
            string bodyRequest = "{\"data\":\"test\"}";      // JSON Request Body
            long timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds(); // UNIX timestamp

            // Concatenate the signature string
            string signatureString = $"{secretKey}+{tokenKey}+{method}+{url}+{bodyRequest}+{timestamp}";

            // Compute the SHA-512 hash
            using (SHA512 sha512 = SHA512.Create())
            {
                byte[] hashBytes = sha512.ComputeHash(Encoding.UTF8.GetBytes(signatureString));
                string authSignature = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
                
                Console.WriteLine($"auth-signature: {authSignature}");
            }
        }
    }
    

---

🔹 PHP Example

    <?php
    $secretKey = "your_secret_key"; // SK
    $tokenKey = "your_token_key";   // TK
    $method = "POST";               // HTTP Method
    $url = {BASE_URL} +"/resource"; // API URL
    $bodyRequest = '{"data":"test"}';  // JSON Request Body
    $timestamp = time(); // UNIX timestamp

    // Concatenate the signature string
    $signatureString = "$secretKey+$tokenKey+$method+$url+$bodyRequest+$timestamp";

    // Compute SHA-512 hash
    $authSignature = hash("sha512", $signatureString);

    echo "auth-signature: " . $authSignature;
    ?>
    

---

🔹 Node.js Example

    const crypto = require('crypto');

    const secretKey = "your_secret_key"; // SK
    const tokenKey = "your_token_key";   // TK
    const method = "POST";               // HTTP Method
    const url = {BASE_URL} +"/resource"; // API URL
    const bodyRequest = JSON.stringify({ data: "test" }); // JSON Request Body
    const timestamp = Math.floor(Date.now() / 1000); // UNIX timestamp

    // Concatenate the signature string
    const signatureString = `${secretKey}+${tokenKey}+${method}+${url}+${bodyRequest}+${timestamp}`;

    // Compute SHA-512 hash
    const authSignature = crypto.createHash('sha512').update(signatureString).digest('hex');

    console.log("auth-signature:", authSignature);
    

---

🔹 Flutter (Dart) Example

    import 'dart:convert';
    import 'dart:crypto';

    void main() {
    String secretKey = "your_secret_key"; // SK
    String tokenKey = "your_token_key";   // TK
    String method = "POST";               // HTTP Method
    String url = {BASE_URL} +"/resource"; // API URL
    String bodyRequest = '{"data":"test"}';  // JSON Request Body
    int timestamp = DateTime.now().millisecondsSinceEpoch ~/ 1000; // UNIX timestamp

    // Concatenate the signature string
    String signatureString = "$secretKey+$tokenKey+$method+$url+$bodyRequest+$timestamp";

    // Compute SHA-512 hash
    var bytes = utf8.encode(signatureString);
    var digest = sha512.convert(bytes);

    print("auth-signature: ${digest.toString()}");
    }
    

---

🚀 Final Notes

• The generated auth-signature must be included in the request headers.
• Ensure your secret key (SK) is never exposed in client-side applications.
• The TIMESTAMP should always be the current UNIX timestamp to prevent replay attacks.

Get Transaction State

    
        curl -X GET "{BASE_URL}/sandbox/payment/verify/state?transaction_id={id}" \
        -H "auth-apiKey: pk_test_37........bf76b6dc218" \
        -H "auth-timestamp: 2024-04-24 16:55:00" \
        -H "auth-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
        -H "auth-signature: xxxxxxxxx ............ xxxx"
        -H 'Content-Type: application/json' \
        -H 'Accept: application/json' \
    

To get Transaction State you need to make a GET call to the following url :
{BASE_URL}/sandbox/payment/verify/state?transaction_id={id}

HEADERS PARAMETERS

Field	Type	Description
auth-apiKey	String	(required) Your API key.
auth-timestamp	String	(required) request timestamp.
auth-token	String	(required) User token

Example Response:

{
    "status": "",
    "message": "",
    "data": {
        "id": 0,
        "amount": "",
        "state": 0,
        "transaction_id": "",
        "created_at": "",
        "updated_at": "",
        "customer": {
            "id": 0,
            "first_name": "",
            "last_name": "",
            "email": "",
            "phone": "",
            "country_id": 0,
            "created_at": "",
            "updated_at": ""
        },
        "client_merchants": [
            {
                "id": 0,
                "client_id": 0,
                "code": "",
                "carrier_id": "",
                "active": true,
                "archived": true,
                "created_at": "",
                "updated_at": "",
                "deleted_at": null,
                "carrier": {
                    "id": 0,
                    "carrier_name": "",
                    "country_id": 0,
                    "display_name": "",
                    "active": true,
                    "archived": true
                }
            }
        ],
        "client": {
            "id": 0,
            "name": "",
            "client_type_id": 0,
            "status": 0,
            "verified_at": null,
            "location": "",
            "created_at": "",
            "updated_at": ""
        },
        "payment": {
            "id": "",
            "subscription_id":"",
            "amount": "",
            "due_at": "2024-11-22 19:57:14",
            "nature": null,
            "archived": false,
            "created_at": "2024-11-18T19:57:14.000000Z",
            "updated_at": "2024-11-18T19:57:14.000000Z",
            "deleted_at": null,
            "status": "",
            "payment_reference": "JP-XXXXXXXXXX"
        }
    }
}

Create Transaction (Send Payment)

This endpoint is used to send a payment. It is an HTTP POST request to the specified URL.

                
                curl -X POST "BASE_URL/sandbox/send/payment" \
                -H "auth-apiKey: pk_test_37........bf76b6dc218" \
                -H "auth-timestamp: 2024-04-24 16:55:00" \
                -H "auth-token: xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
                -H "auth-signature: xxxxxxxxx ............ xxxx"
                -H 'Content-Type: application/json' \
                -H 'Accept: application/json' \
                --data '{
                    "customer_phone":"",
                    "amount":"",
                    "device":"",
                    "lang":"",
                    "version":"",
                    "country_id":1,
                    "return_url":"https://your_domain.com/callback"
                }'
            
            

To Create transaction you need to make a POST call to the following url :
{BASE_URL}/sandbox/send/payment

HEADERS PARAMETERS

Field	Type	Description
auth-apiKey	String	(required) Your API key.
auth-timestamp	String	(required) request timestamp.
auth-token	String	(required) User token

Request Body

Field	Type	Description
customer_phone	String	(required) The phone number of the customer..
amount	Number	(required): The amount of the payment.
device	String	(text, optional): The device used for the transaction
lang	String	(optional): The language preference.
version	String	(optional): The version of API v1.
country_id	Number	(required): The ID of the country.
return_url	String	(optional): The URL to return to after the transaction.

Example Response:

{
    "status": "",
    "message": "",
    "data": {
        "id": 0,
        "amount": "",
        "state": 0,
        "transaction_id": "",
        "created_at": "",
        "updated_at": "",
        "customer": {
            "id": 0,
            "first_name": "",
            "last_name": "",
            "email": "",
            "phone": "",
            "country_id": 0,
            "created_at": "",
            "updated_at": ""
        },
        "client_merchants": [
            {
                "id": 0,
                "client_id": 0,
                "code": "",
                "carrier_id": "",
                "active": true,
                "archived": true,
                "created_at": "",
                "updated_at": "",
                "deleted_at": null,
                "carrier": {
                    "id": 0,
                    "carrier_name": "",
                    "country_id": 0,
                    "display_name": "",
                    "active": true,
                    "archived": true
                }
            }
        ],
        "client": {
            "id": 0,
            "name": "",
            "client_type_id": 0,
            "status": 0,
            "verified_at": null,
            "location": "",
            "created_at": "",
            "updated_at": ""
        },
        
    }
}

Create Subscription

This endpoint allows you to create a new subscription for a customer.

        
            curl --location '{BASE_URL}/sandbox/subscriptions/create' \
                --header 'auth-apiKey: pk_test_fce1••••••c821c60e' \
                --header 'auth-timestamp: request date' \
                --header 'auth-token: ••••••••••••••••••' \
                --header 'auth-signature: ••••••••••••••••••••••••' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --data '{
                    "phone" : "0122030465",
                    "plan_id" : 1,
                    "frequency_id":1,
                    "start_at" : "2024-10-27"
                }'
        
    

To Create Subscription you need to make a POST call to the following url :
{BASE_URL}/sandbox/subscriptions/create

HEADERS PARAMETERS

Field	Type	Description
auth-apiKey	String	(required) Your API key.
auth-timestamp	String	(required) request timestamp.
auth-token	String	(required) User token

Response Body

Field	Type	Description
plan_id	String	The unique identifier for the plan.
name	string	The name of the subscription plan.
description	Number	A brief description of the plan.
price	number	The price of the plan.
currency	string	The currency in which the price is denominated.

Example Response:

{
    "status": "Success",
    "message": "Subscription created successfully",
    "data": {
        "id": "",
        "client_id": "",
        "plan_id": "",
        "customer_id": 2,
        "status": "",
        "start_at": "2024-10-27 00:00:00",
        "expire_at": "2025-01-09 21:55:07",
        "archived": false,
        "created_at": "2025-01-02T21:55:07.000000Z",
        "updated_at": "2025-01-02T21:55:07.000000Z",
        "deleted_at": null,
        "renewal_date": null,
        "renewed": false
    }
}

List of plans

This endpoint is used to retrieve a list of subscription plans.

        
            curl --location '{BASE_URL}/sandbox/subscriptions/plans' \
                --header 'auth-timestamp: 2024-09-17 23:08' \
                --header 'auth-signature: ••••••••••••••••••••••••••••••••••••' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \                
        
    

To get List of plans you need to make a POST call to the following url :
{BASE_URL}/sandbox/subscriptions/plans

HEARDERS PARAMETERS

Field	Type	Description
auth-apiKey	String	(required) Your API key.
auth-timestamp	String	(required) request timestamp.
auth-token	String	(required) User token

Request Body

Field	Type	Description
phone	String	(required) The phone number of the customer..
plan_id	Number	(required):The ID of the subscription plan.
frequency_id	Number	(required):The ID of the frequency for the subscription.
start_at	String	(string) - The start date of the subscription in the format "YYYY-MM-DD".

Example Reponse :

    
        {
            "status": "Success",
            "message": "List of subscription plans",
            "data": [
                {
                    "id": null,
                    "client_id": null,
                    "name": "",
                    "price": "",
                    "frequency_id": null,
                    "archived": false,
                    "created_at": "2024-09-14T18:41:00.000000Z",
                    "updated_at": "2024-09-14T18:41:00.000000Z",
                    "deleted_at": null
                },
                ...
            ]
        }
     

Disable Subscription

This endpoint is used to disable a subscription for a user.

    
        curl --location '{BASE_URL}/sandbox/subscriptions/disable' \
            --header 'auth-apiKey: ••••••••••••••••••••••••••••••••••••••••••' \
            --header 'auth-timestamp: requet_date' \
            --header 'auth-token: ••••••••••••••••••••••••' \
            --header 'auth-signature: ••••••••••••••••••••••••••••••••••••••••••' \
            --header 'Content-Type: application/json' \
            --header 'Accept: application/json' \
            --data '{
                "phone" : "0122030465"
            }'             
    

To Disable Subscription you need to make a POST call to the following url :
{BASE_URL}/sandbox/subscriptions/disable

HEADERS PARAMETERS

Field	Type	Description
auth-apiKey	String	(required) Your API key.
auth-timestamp	String	(required) request timestamp.
auth-token	String	(required) User token

Request Body

Field	Type	Description
phone	String	(required) The phone number of the customer..

Response Body

The response will include the details of the disabled subscription in the following JSON schema:

Example Response:

    {
        "status": "Success",
        "message": "Customer subscription disabled successfully",
        "data": {
            "id": "",
            "first_name": "",
            "last_name": "",
            "email": "email@email.ml",
            "phone": "0102030504",
            "remember_token": null,
            "created_at": "2024-09-24T22:06:25.000000Z",
            "updated_at": "2024-09-24T22:06:25.000000Z",
            "deleted_at": null,
            "country_id": 1
        }
    }

Receive Payments Easily with Our Payment Link Solution

You don't need to integrate or connect any API to start receiving payments from your customers. Our payment link solution simplifies the process by allowing you to generate and share a secure payment link with your customers.

Here's how it works:

• Create Your Payment Link: Simply log into your account and generate a unique payment link.
• Share the Link with Your Customers: Send the payment link to your customers via email, SMS, or any messaging platform of your choice.
• Get Paid Instantly: Your customers can use the link to make payments directly and securely.

This solution is perfect for businesses or individuals who want a quick and hassle-free way to receive payments without worrying about technical integration or API usage.

Start using our payment link today and make receiving payments easier than ever!

Streamline Payments with Our Payment Notification System

Our system offers an alternative to payment links by enabling you to send payment notifications directly to JemeniPay customers. This approach is ideal if you prefer not to use or share a payment link while still ensuring a seamless payment experience.

How It Works:

• Initiate a Payment Notification: Use our system to send a detailed payment notification directly to the customer’s JemeniPay account.
• Customer Receives the Notification: The customer is instantly notified about the payment request.
• Direct Payment: The customer can pay you directly through JemeniPay without needing a separate payment link.

This feature ensures security, convenience, and flexibility for both you and your customers. It's a perfect solution for businesses seeking streamlined payment processes without relying on shared links.

Start using our Payment Notification System today and enjoy a faster, more direct way to receive payments!

HTTP Codes

The Jɛmɛnipay API uses the following error codes: