Reseller API Documentation

This document describes how an authorized reseller can:

Send a wallet top-up request to Elyonko Online.
Search for a user and retrieve basic user information.

Base URL https://elyonko.online

Version v1

Format JSON over HTTPS

1. Authentication 2. Wallet Top-up Endpoint 3. User Search Endpoint 4. Error Responses 5. Short Reference

1. Authentication

Every request must be authenticated using a valid API Key assigned to the reseller account.

Send the key in the request headers as follows:

X-API-Key: YOUR_API_KEY
Content-Type: application/json

2. Wallet Top-up Endpoint

POST https://elyonko.online/wp-json/elyonko-gw/v1/wallet/topup

The request body must be sent as JSON with the following structure:

{
  "customer_ref": {
    "type": "id",
    "value": "USER_ID"
  },
  "amount": 1000,
  "currency": "SDG",
  "txn_id": "UNIQUE_TXN_ID"
}

Field Description

Field	Type	Required	Description
`customer_ref.type`	string	Yes	Reference type. For wallet top-up, use `"id"`.
`customer_ref.value`	string	Yes	The customer ID or wallet ID inside the Elyonko Online system.
`amount`	number	Yes	The amount to top up in SDG (Sudanese Pound).
`currency`	string	Yes	Currency code. For this endpoint, always use `"SDG"`.
`txn_id`	string	Yes	Unique transaction identifier generated by the reseller. It must not be reused. Any duplicate `txn_id` will be rejected.

            Important: The txn_id must be unique per reseller.
            Use your own order ID, invoice ID, or a unique reference to prevent duplicates.
        

Example cURL Request (Wallet Top-up)

curl -X POST "https://elyonko.online/wp-json/elyonko-gw/v1/wallet/topup" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
        "customer_ref": { "type": "id", "value": "133221" },
        "amount": 2500,
        "currency": "SDG",
        "txn_id": "EL-REQ-2025-001"
      }'

Successful Response (Wallet Top-up)

{
  "status": "success",
  "code": "topup_completed",
  "message": "Topup processed successfully via gateway.",
  "data": {
    "amount": 2500,
    "currency": "SDG",
    "txn_id": "EL-REQ-2025-001",
    "core_txn_id": "CORE-001"
  }
}

3. User Search Endpoint

Before performing a wallet top-up, resellers can verify a user by sending a User Search request. This endpoint allows you to confirm that the user exists and optionally retrieve basic information.

POST https://elyonko.online/wp-json/elyonko-gw/v1/user/search

The request body must be sent as JSON with the following structure:

{
  "customer_ref": {
    "type": "id",
    "value": "USER_ID"
  }
}

Field Description

Field	Type	Required	Description
`customer_ref.type`	string	Yes	Reference type. For user search, use `"id"`.
`customer_ref.value`	string	Yes	The customer ID inside the Elyonko Online system.

Example cURL Request (User Search)

curl -X POST "https://elyonko.online/wp-json/elyonko-gw/v1/user/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_RESELLER_KEY" \
  -d "{ \"customer_ref\": { \"type\": \"id\", \"value\": \"2\" } }"

Example Successful Response (User Search)

{
  "status": "success",
  "code": "user_found",
  "message": "User information retrieved successfully.",
  "data": {
    "user_id": 2,
    "name": "Example User",
    "phone": "0923000000",
    "wallet_balance": 15000,
    "status": "active"
  }
}

Note: The exact structure of the data object may vary depending on your Elyonko Online configuration. Only use the fields that are documented and officially supported in your environment.

4. Error Responses

4.1 Duplicate Transaction (Wallet Top-up)

{
  "status": "failed",
  "code": "duplicate_txn",
  "message": "This transaction has already been processed.",
  "data": {
    "txn_id": "EL-REQ-2025-001"
  }
}

4.2 Insufficient Balance (Wallet Top-up)

{
  "status": "failed",
  "code": "insufficient_balance",
  "message": "Your wallet balance is not enough."
}

4.3 Invalid API Key (Any Endpoint)

{
  "status": "failed",
  "code": "invalid_api_key",
  "message": "API key is invalid or disabled."
}

4.4 Forbidden IP (Any Endpoint)

{
  "status": "failed",
  "code": "forbidden_ip",
  "message": "IP not allowed"
}

4.5 User Not Found (User Search)

{
  "status": "failed",
  "code": "user_not_found",
  "message": "No user found with the provided ID."
}

Best Practices for Resellers:
• Always call /user/search before large top-ups to verify the user.
• Never mark a transaction as completed in your system until you receive status = "success" from the Elyonko API.
• Log both the request and response (without exposing the API key) for auditing and troubleshooting.
• In case of network errors or timeouts, do not blindly retry with the same txn_id without checking if the transaction was processed.

5. Short Reference (for Quick Sharing)

Wallet Top-up

POST https://elyonko.online/wp-json/elyonko-gw/v1/wallet/topup

Headers:
  X-API-Key: YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "customer_ref": { "type": "id", "value": "USER_ID" },
  "amount": 1000,
  "currency": "SDG",
  "txn_id": "UNIQUE_TXN_ID"
}

User Search

POST https://elyonko.online/wp-json/elyonko-gw/v1/user/search

Headers:
  X-API-Key: YOUR_API_KEY
  Content-Type: application/json

Body:
{
  "customer_ref": { "type": "id", "value": "USER_ID" }
}