Getting Started

The Jemeni.NET API enables you to create and manage payments, subscriptions, OTP verifications, and transaction tracking.

To access the API, you'll need an API Key. Please sign in to retrieve your credentials.

    BASE_URL: https://jemeni.net/api
    

Authentication

Every request must include an auth-signature in the headers. The signature is a SHA-512 hash of the following string:

  SHA512(SK + "+" + TK + "+" + METHOD + "+" + URL + "+" + BODY + "+" + TIMESTAMP)
    

• SK: Your secret key (from your credentials)
• TK: Your token key (Bearer token)
• METHOD: HTTP method (e.g. POST)
• URL: Full request URL
• BODY: Raw request body (empty for GET)
• TIMESTAMP: Current UNIX timestamp (in seconds)

📦 Example Request (cURL)

  curl -X POST {BASE_URL}/{resource} \
    -H "Authorization: Bearer your_token_key" \
    -H "auth-signature: 2a4e9b10a57e4c3e7b2..." \
    -H "Timestamp: 1700000000" \
    -H "Content-Type: application/json" \
    -d '{"data":"test"}'
    

You can adapt this request in any programming language using your preferred HTTP client (e.g. Axios, Guzzle, `http` in Dart, etc.).

🔐 Security Notes

• Keep your SK confidential. Never expose it in client-side code.
• Use the current UNIX TIMESTAMP to prevent replay attacks.
• Ensure all requests are sent over HTTPS.

Check Transaction Status

To retrieve the current state of a transaction, send a GET request to the endpoint below, including your authentication headers.

📎 Endpoint

  GET {BASE_URL}/sandbox/payment/verify/state?transaction_id={id}
    

📦 Example Request (cURL)

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

🧾 Required Headers

📤 Example Response

  {
    "status": "success",
    "message": "Transaction retrieved successfully.",
    "data": {
      "id": '132132132',
      "amount": "500.00",
      "state": 2,
      "customer": {
        "id": 45,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "+22370000000",
        "country_code": 1,
      },
      "client_merchants": [...],
      "client": {
        "id": 8,
        "name": "Acme Corp",
        "status": 1,
        ...
      },
      "payment": {
        "id": "xyz123",
        "subscription_id": "sub_456",
        "amount": "500.00",
        "due_at": "2024-11-22 19:57:14",
        "status": "completed",
        "payment_reference": "JP-XXXXXXXXXX"
      }
    }
  }
    

You can refer to the transaction state codes in the error/code reference section for more details on what each state value represents.

Initiate a Transaction

This endpoint allows you to initiate a payment from a customer's mobile account. Send a POST request with the required information and authentication headers.

📎 Endpoint

  POST {BASE_URL}/sandbox/send/payment
    

📦 Example Request (cURL)

  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: your_access_token" \
    -H "auth-signature: your_signature_hash" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    --data '{
    "customer_phone":"78000000",
    "amount":9000,
    "device":"FCFA",
    "country_code":"ml",
    "notifiable":true
    }'

🧾 Required Headers

📨 Request Body

📤 Example Response

    {

        "status": "success",
        "message": "Payment initiated successfully.",
        "data": {
            "id": "01jz0p4y6g5jxe0abeazw12j55",
            "amount": 9000,
            "state": 1,
            "reference": "6862a8914c1d5bbabd99cf54",
            "created_at": "2025-06-30 15:09:05",
            "customer": {
                "id": "01jxk881aztej3mnd5aj4yt7hk",
                "first_name": "Kadiatou",
                "last_name": "Maiga",
                "email": "kmaiga@ktminnov.com",
                "phone": "78521436",
                "country_code": "ml"
            },

            "client": {
                "id": "01jwvrvjswcex8n3ajv0njfpx6",
                "name": "KTM SHOP",
                "client_type_code": "shop",
                "location": "Segou"
            },
        "payment": {
                "id": "01jz0p4y6g5jxe0abeazw12j55",
                "subscription_id": null,
                "amount": "500.00",
                "status": "pending",
                "payment_reference": "JP-ABC123456",
            }
        }

    }
    

Create a Subscription

This endpoint allows you to create a recurring subscription for a customer based on a predefined plan and billing frequency.

📎 Endpoint

     POST {BASE_URL}/sandbox/subscriptions/create
    

📦 Example Request (cURL)

  curl -X POST "{BASE_URL}/sandbox/subscriptions/create" \
    -H "auth-apiKey: pk_test_fce1••••••c821c60e" \
    -H "auth-timestamp: 2024-04-24 16:55:00" \
    -H "auth-token: your_access_token" \
    -H "auth-signature: your_signature_hash" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    --data '{
      "phone": "+22370000000",
      "plan_id": 1,
      "frequency_id": 1,
      "start_at": "2024-10-27"
  }'
    

🧾 Required Headers

📨 Request Body

📤 Example Response

  {
    "status": "success",
    "message": "Subscription created successfully",
    "data": {
      "id": '01ezezezezraezaez',
      "client_id": 3,
      "plan_id": 1,
      "customer_id": 2,
      "status": "active",
      "start_at": "2024-10-27 00:00:00",
      "expire_at": "2025-01-09 21:55:07",
      "archived": false,
      "renewal_date": null,
      "renewed": false
    }
  }
    

List Subscription Plans

This endpoint allows you to retrieve all available subscription plans configured for your account.

📎 Endpoint

  POST {BASE_URL}/sandbox/subscriptions/plans
    

📦 Example Request (cURL)

  curl -X POST "{BASE_URL}/sandbox/subscriptions/plans" \
    -H "auth-apiKey: pk_test_fce1••••••c821c60e" \
    -H "auth-timestamp: 2024-09-17 23:08:00" \
    -H "auth-token: your_access_token" \
    -H "auth-signature: your_signature_hash" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"
    

🧾 Required Headers

📤 Example Response

  {
    "status": "success",
    "message": "List of subscription plans",
    "data": [
      {
        "id": '01zedqfdfqsdfqfqfsqdf',
        "client_id": '01sdsd3123sdsdsdsd',
        "name": "Basic Plan",
        "price": "2000.00",
        "frequency_id": 1,
        "archived": false,
      },
      ...
    ]
  }
    

Cancel a Subscription

This endpoint allows you to cancel an active subscription linked to a specific customer's phone number.

📎 Endpoint

  POST {BASE_URL}/sandbox/subscriptions/disable
    

📦 Example Request (cURL)

  curl -X POST "{BASE_URL}/sandbox/subscriptions/disable" \
    -H "auth-apiKey: pk_test_••••••••••••••••••••" \
    -H "auth-timestamp: 2024-09-24 22:06:00" \
    -H "auth-token: your_access_token" \
    -H "auth-signature: your_signature_hash" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    --data '{
      "phone": "+22370000000"
  }'
    

🧾 Required Headers

📨 Request Body

📤 Example Response

  {
    "status": "success",
    "message": "Customer subscription disabled successfully",
    "data": {
      "id": "01zezezezerdfezdez",
      "first_name": "Awa",
      "last_name": "Sow",
      "email": "awa.sow@email.ml",
      "phone": "+22370000000",
      "country_code": 'ml',
    }
  }
    

Generate a Payment Link

Jemeni.NET allows you to receive payments without needing to integrate the API. You can create secure payment links and share them directly with your customers.

🔧 How It Works

• Step 1 - Generate the Link: Log into your dashboard and create a new payment link for your customer.
• Step 2 - Share the Link: Send the link via SMS, email, WhatsApp, or any messaging platform.
• Step 3 - Receive Payment: The customer clicks the link, fills out payment info, and completes the transaction securely.

✅ Benefits

• No technical integration required.
• Perfect for freelancers, small businesses, or quick one-time charges.
• Real-time payment tracking via your dashboard.

Use cases: Remote sales, invoice payments, social commerce, donation campaigns, and more.

Ready to start? Log in to generate your first payment link today.

Send a Payment Notification

The payment notification system lets you trigger payment requests directly to a customer’s JemeniPay account, without using a public payment link.

🔧 How It Works

• Step 1 - Initiate a Notification: From your system or dashboard, send a payment request tied to the customer's phone number.
• Step 2 - Customer is Notified: The customer receives an instant notification within their JemeniPay app or channel.
• Step 3 - Direct Payment: The customer can pay securely, without the need to click on any external link.

✅ Benefits

• No link sharing required.
• Secure and personalized experience via JemeniPay interface.
• Ideal for in-app payments, recurring charges, or enterprise scenarios.

Use case examples: utility bill reminders, subscription renewals, loan installments, or payment follow-ups.

Ready to try it? Log in to your dashboard and start sending payment notifications to your customers.

Webhooks Integration

JemeniPay supports webhooks to notify your system in real time when key events occur (e.g., successful payments, subscription renewals, invoice creations). This enables automated and efficient workflows between JemeniPay and your backend systems.

📦 How Webhooks Work

• 1. Event Triggered: A specific event (e.g., payment.success) is detected by JemeniPay.
• 2. Notification Sent: JemeniPay sends an HTTP POST request to your configured webhook endpoint.
• 3. Payload Received: Your server receives the JSON payload and processes it (e.g., updates a transaction status).
• 4. Signature Validation: You verify the authenticity of the payload using the signature provided.
• 5. Acknowledgement: Your endpoint responds with a 200 OK status to confirm receipt. If not, JemeniPay retries the request.

🔐 Security & Reliability

• Signature verification: Every webhook request includes a signature hash. We recommend validating it to ensure trust.
• Retry mechanism: JemeniPay automatically retries failed webhook deliveries up to a few times.
• Event filtering: You can choose which events trigger notifications via your dashboard or API settings.

📨 Example Payload

  {
    "event": "payment.success",
    "data": {
      "reference": "TX12345",
      "amount": 1000,
      "currency": "XOF",
      "status": "success",
      "customer_id": "CUST6789"
    },
    "timestamp": "2024-12-30T12:34:56Z",
    "signature": "abcdef1234567890"
  }
    

You can use the reference field to reconcile the transaction in your system, and the signature to validate the payload.

🚧 Status

Webhooks are currently in active development. More event types and customization options will be released soon.

HTTP Codes

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