Syriatel Cash API v1

Integrate transaction history and balance checks into your applications.

BASE URL https://api.melchersman.com/syr-cash/v1/

Response Format

All endpoints return a standard JSON structure:

Standard JSON Response

{
  "success": true,
  "code": "SUCCESS",
  "data": { ... } // Object or null
}

Smart Query Parameter

All endpoints support a smart query parameter that auto-detects whether you're passing a phone number or secret code:

Input	Detected As	Example
10 digits starting with `09`	Phone Number	`0991234567`
Anything else	Secret Code	`65288500`, `ABC123`

Authentication

All requests must include your unique API Token in the header.

Header Example

api-token: YOUR_SECRET_TOKEN_HERE

Security Warning Keep your tokens secure. Do not expose them in client-side code or public repositories.

Rate Limits

To ensure fair usage and system stability, rate limits are enforced per phone number:

Endpoint	Limit	Window
`/Balance`	2 requests	per minute per number
`/IncomingHistory`	2 requests	per minute per number
`/OutgoingHistory`	2 requests	per minute per number

RATE_LIMIT_EXCEEDED If you exceed the rate limit, you'll receive this error. Wait 60 seconds before retrying.

Endpoints

GET /Balance Check account balance

Get the current Syriatel Cash balance for a subscribed phone number or secret code.

Rate Limit: 2 requests/minute per number

Query Parameters

Parameter	Type	Description
queryRecommended	string	Phone number or secret code (auto-detected). Use this instead of separate number/code params.
numberOptional	string	Phone number (e.g. `0991234567`). Deprecated - use `query` instead.
codeOptional	string	Secret code for the account. Deprecated - use `query` instead.

Example

cURL

curl -X GET "https://api.melchersman.com/syr-cash/v1/Balance?query=0991234567" \
  -H "api-token: YOUR_API_TOKEN"

cURL

curl -X GET "https://api.melchersman.com/syr-cash/v1/Balance?query=65288500" \
  -H "api-token: YOUR_API_TOKEN"

JSON

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "balance": 50000.0
  }
}

Note: Balance is a float in SYP.

JSON

{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "data": {
    "message": "Rate limit exceeded (2 requests per minute per number)"
  }
}

GET /IncomingHistory Get deposits history

Get incoming transaction history (deposits). If no query is provided, returns a list of active subscriptions.

Rate Limit: 2 requests/minute per number By default, only successful transactions are returned. Use status=all to get all transactions.

Query Parameters

Parameter	Type	Description
queryRecommended	string	Phone number or secret code (auto-detected).
statusNew	string	Filter transactions by status: • `success` (default) - Only successful transactions • `failed` - Only failed transactions • `all` - All transactions
pageOptional	integer	Pagination offset (Default: 1).
numberDeprecated	string	Use `query` instead.
codeDeprecated	string	Use `query` instead.

Example

cURL - Successful transactions only (default)

curl -X GET "https://api.melchersman.com/syr-cash/v1/IncomingHistory?query=0991234567" \
  -H "api-token: YOUR_API_TOKEN"

cURL - All transactions (including failed)

curl -X GET "https://api.melchersman.com/syr-cash/v1/IncomingHistory?query=0991234567&status=all" \
  -H "api-token: YOUR_API_TOKEN"

JSON

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "total": 25,
    "transactions": [
      {
        "transaction_no": "TXN123456",
        "date": "2024-01-15 14:30:00",
        "from_gsm": "0991234567",
        "to_gsm": "0997654321",
        "amount": 10000.0,
        "fee": 0.0,
        "net": 10000.0,
        "channel": "Mobile",
        "status": "1"
      }
    ]
  }
}

Note: All amounts are floats in SYP. Status "1" = success, "0" = failed.

Response (No Parameters)

{
  "success": true,
  "code": "SUCCESS",
  "data": {
    "numbers": [
      { "number": "0991234567", "code": "1234" },
      { "number": "0997654321", "code": "" }
    ]
  }
}

GET /OutgoingHistory Get withdrawals history

Get outgoing transaction history (withdrawals/transfers sent). Same parameters as /IncomingHistory.

Rate Limit: 2 requests/minute per number By default, only successful transactions are returned.

Query Parameters

Parameter	Type	Description
queryRecommended	string	Phone number or secret code (auto-detected).
statusNew	string	`success` (default), `failed`, or `all`
pageOptional	integer	Pagination offset (Default: 1).

Example

cURL

curl -X GET "https://api.melchersman.com/syr-cash/v1/OutgoingHistory?query=0991234567&status=all" \
  -H "api-token: YOUR_API_TOKEN"

Python Library

Official Python client with async/sync support.

INSTALL pip install PySyriatel

PyPI GitHub

Async Usage

Python

from syriatel import SyriatelAPI

async with SyriatelAPI(api_token="your_token") as api:
    # Accepts phone number OR secret code (auto-detected)
    balance = await api.syrcash.balance("0991234567")  # Phone
    balance = await api.syrcash.balance(65288500)       # Code as int
    
    # Get only successful transactions (default)
    incoming = await api.syrcash.get_incoming_history("0991234567")
    
    # Get ALL transactions including failed
    all_tx = await api.syrcash.get_incoming_history("0991234567", status="all")
    
    # Get only failed transactions
    failed = await api.syrcash.get_incoming_history("0991234567", status="failed")

Sync Usage

Python

from syriatel import SyriatelAPISync

with SyriatelAPISync(api_token="your_token") as api:
    balance = api.syrcash.balance("0991234567")
    incoming = api.syrcash.get_incoming_history("0991234567", status="all")

Available Methods

Method	Returns	Description
`api.get_numbers()`	`List[str]`	Active phone numbers
`api.get_codes()`	`List[str]`	Secret codes
`api.syrcash.balance(query)`	`float`	Balance in SYP
`api.syrcash.get_incoming_history(query, status)`	`List[Transaction]`	Incoming transfers
`api.syrcash.get_outgoing_history(query, status)`	`List[Transaction]`	Outgoing transfers

Error Handling

Python

from syriatel import (
    SyriatelAPIError,
    InvalidTokenError,
    SubscriptionExpiredError,
    NetworkError,
)

try:
    balance = await api.syrcash.balance("0991234567")
except SubscriptionExpiredError:
    print("Subscription expired")
except InvalidTokenError:
    print("Invalid token")
except NetworkError as e:
    print(f"Network error: {e}")

Error Codes

If success is false, the code field will contain one of the following:

Code	Description
`INVALID_TOKEN`	The provided API token is missing, invalid, or expired.
`SUBSCRIPTION_EXPIRED`	No active subscription found for this number. Prompt user to subscribe.
`RATE_LIMIT_EXCEEDED`	Too many requests. Wait 60 seconds before retrying. Limit: 2 requests/minute per number.
`FETCH_FAILED`	Failed to fetch data from Syriatel.
`RATE_LIMITED`	Blocked by Syriatel. Your account has been temporarily suspended due to exceeding Syriatel's own transaction limit. Wait and retry later.
`SESSION_EXPIRED`	Syriatel session expired. The user must re-login with their Syriatel Cash password to refresh the session. Prompt the user to re-enter their password.
`SERVER_MAINTENANCE`	Syriatel servers are under maintenance (Codes -15000, -25000).
`NOT_AUTHORIZED`	Account authorization issue or PIN invalid.
`NETWORK_ERROR`	Internal connectivity issue.