User - Balance

Base URL: https://your-domain.com

Admin endpoints for managing subscriber and user balances. All endpoints require admin/staff authentication.

Get Subscriber Balance

Retrieve the current balance for a subscriber.

Property	Value
Endpoint	Get Subscriber Balance
Method	`GET`
URL	`/api/v1/balance/subscriber/{id}`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Path Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	Subscriber ID

Query Parameters:

Parameter	Type	Required	Description
`isp_id`	integer	Yes	ISP ID
`branch_id`	integer	Yes	Branch ID
`user_id`	integer	Yes	User ID

Success Response (200 OK):

json

{
    "success": true,
    "data": {
        "subscriber_id": 1,
        "subscriber_name": "John Doe",
        "balance": 1500.00,
        "last_transaction": "2024-01-15 10:30:00"
    }
}

Error Response (404 Not Found):

json

{
    "success": false,
    "message": "Subscriber not found"
}

Code Examples:

bash

curl -X GET "https://your-domain.com/api/v1/balance/subscriber/1?isp_id=1&branch_id=1&user_id=1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$subscriberId = 1;

$response = $client->request('GET', "/api/v1/balance/subscriber/{$subscriberId}", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'query' => [
        'isp_id'    => 1,
        'branch_id' => 1,
        'user_id'   => 1,
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const subscriberId = 1;

const params = new URLSearchParams({
  isp_id: 1,
  branch_id: 1,
  user_id: 1,
});

const response = await fetch(`${BASE_URL}/api/v1/balance/subscriber/${subscriberId}?${params}`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

subscriber_id = 1

response = requests.get(
    f"{BASE_URL}/api/v1/balance/subscriber/{subscriber_id}",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    params={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 1,
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strconv"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	subscriberId := 1
	endpoint := baseURL + "/api/v1/balance/subscriber/" + strconv.Itoa(subscriberId)

	q := url.Values{}
	q.Set("isp_id", "1")
	q.Set("branch_id", "1")
	q.Set("user_id", "1")
	endpoint += "?" + q.Encode()

	req, _ := http.NewRequest("GET", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let subscriber_id = 1;

    let response = client
        .get(format!("{BASE_URL}/api/v1/balance/subscriber/{subscriber_id}"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .query(&[
            ("isp_id", "1"),
            ("branch_id", "1"),
            ("user_id", "1"),
        ])
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Get User Balance

Retrieve the current balance for a user (reseller/staff).

Property	Value
Endpoint	Get User Balance
Method	`GET`
URL	`/api/v1/balance/user/{id}`
Authentication	Bearer Token

Path Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	User ID

Success Response (200 OK):

json

{
    "success": true,
    "data": {
        "user_id": 2,
        "user_name": "Reseller One",
        "balance": 5000.00,
        "last_transaction": "2024-01-15 10:30:00"
    }
}

Code Examples:

bash

curl -X GET "https://your-domain.com/api/v1/balance/user/1" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$userId = 1;

$response = $client->request('GET', "/api/v1/balance/user/{$userId}", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const userId = 1;

const response = await fetch(`${BASE_URL}/api/v1/balance/user/${userId}`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

user_id = 1

response = requests.get(
    f"{BASE_URL}/api/v1/balance/user/{user_id}",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strconv"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	userId := 1
	endpoint := baseURL + "/api/v1/balance/user/" + strconv.Itoa(userId)

	req, _ := http.NewRequest("GET", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let user_id = 1;

    let response = client
        .get(format!("{BASE_URL}/api/v1/balance/user/{user_id}"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Add Subscriber Balance

Add balance to a subscriber's account.

Property	Value
Endpoint	Add Subscriber Balance
Method	`POST`
URL	`/api/v1/balance/subscriber/add`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Request Body:

json

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "subscriber_id": 1,
    "amount": 500
}

Parameter	Type	Required	Description
`isp_id`	integer	Yes	ISP ID
`branch_id`	integer	Yes	Branch ID
`user_id`	integer	Yes	Admin user ID
`subscriber_id`	integer	Yes	Subscriber ID
`amount`	decimal	Yes	Amount to add

Success Response (200 OK):

json

{
    "success": true,
    "message": "Balance added successfully",
    "data": {
        "new_balance": 2000.00,
        "transaction_id": 456
    }
}

Error Response (422 Validation Error):

json

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "amount": ["The amount must be greater than 0."]
    }
}

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/balance/subscriber/add" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "subscriber_id": 1,
    "amount": 500
  }'

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/balance/subscriber/add', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'json' => [
        'isp_id'        => 1,
        'branch_id'     => 1,
        'user_id'       => 1,
        'subscriber_id' => 1,
        'amount'        => 500,
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/balance/subscriber/add`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    isp_id: 1,
    branch_id: 1,
    user_id: 1,
    subscriber_id: 1,
    amount: 500,
  }),
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.post(
    f"{BASE_URL}/api/v1/balance/subscriber/add",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    json={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 1,
        "subscriber_id": 1,
        "amount": 500,
    },
)

data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/balance/subscriber/add"

	payload, _ := json.Marshal(map[string]any{
		"isp_id":        1,
		"branch_id":     1,
		"user_id":       1,
		"subscriber_id": 1,
		"amount":        500,
	})
	req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;
use serde_json::json;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/balance/subscriber/add"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .json(&json!({
            "isp_id": 1,
            "branch_id": 1,
            "user_id": 1,
            "subscriber_id": 1,
            "amount": 500
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Add User Balance

Top up a Reseller / Sub-reseller / Retailer wallet via API. Creates a Payment row with payer_profile_type = 1 and a Ledger entry, so the topup appears in the user's reseller ledger with a clickable Receipt link.

Added in v2.22.26

v1 scope: only admin (profile_type=1) or staff (profile_type=2) callers may perform the topup. Reseller-to-reseller hierarchical topup (which cuts the parent's balance) remains a web-only flow for now.

Property	Value
Endpoint	Add User Balance
Method	`POST`
URL	`/api/v1/balance/user/add`
Authentication	Bearer Token

Request Headers:

Header	Value	Required
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer your-auth-token`	Yes

Request Body:

json

{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 5,
    "target_user_id": 17,
    "amount": 5000.00,
    "payment_method": 1,
    "payment_note": "Monthly topup from HR"
}

Parameter	Type	Required	Description
`isp_id`	integer	Yes	ISP ID
`branch_id`	integer	Yes	Branch ID
`user_id`	integer	Yes	Action-by admin / staff ID
`target_user_id`	integer	Yes	Receiver user ID (must be Reseller / Sub-reseller / Retailer)
`amount`	decimal	Yes	Topup amount, > 0
`payment_method`	integer	No	Payment method code (default `1` = Cash)
`payment_note`	string	No	Free-text note (max 500 chars)

Success Response (200 OK):

json

{
    "status": "success",
    "message": "Balance added successfully.",
    "data": {
        "target_user_id": 17,
        "username": "reseller01",
        "amount_added": 5000.00,
        "new_balance": 12500.00,
        "payment_id": 482,
        "ledger_id": 901
    }
}

Error Responses:

json

// 403 Forbidden — caller is not admin/staff
{
    "status": "error",
    "message": "Only admin or staff profiles can topup user balance via API in this version."
}

json

// 404 Not Found — target user not found
{
    "status": "error",
    "message": "Target user not found."
}

json

// 422 Validation — self-topup, wrong target profile_type, or balance limit exceeded
{
    "status": "error",
    "message": "Target user must be a Reseller, Sub-reseller, or Retailer."
}

json

// 429 Too Many Requests — same amount within 60 seconds
{
    "status": "error",
    "message": "Too frequent payments! Please wait 1 minute and try again."
}

Code Examples:

bash

curl -X POST "https://your-domain.com/api/v1/balance/user/add" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 5,
    "target_user_id": 17,
    "amount": 5000,
    "payment_method": 1,
    "payment_note": "Monthly topup from HR"
  }'

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$response = $client->request('POST', '/api/v1/balance/user/add', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'json' => [
        'isp_id'         => 1,
        'branch_id'      => 1,
        'user_id'        => 5,
        'target_user_id' => 17,
        'amount'         => 5000,
        'payment_method' => 1,
        'payment_note'   => 'Monthly topup from HR',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const response = await fetch(`${BASE_URL}/api/v1/balance/user/add`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
  body: JSON.stringify({
    isp_id: 1,
    branch_id: 1,
    user_id: 5,
    target_user_id: 17,
    amount: 5000,
    payment_method: 1,
    payment_note: 'Monthly topup from HR',
  }),
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

response = requests.post(
    f"{BASE_URL}/api/v1/balance/user/add",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    json={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 5,
        "target_user_id": 17,
        "amount": 5000,
        "payment_method": 1,
        "payment_note": "Monthly topup from HR",
    },
)

data = response.json()
print(data)

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	endpoint := baseURL + "/api/v1/balance/user/add"

	payload, _ := json.Marshal(map[string]any{
		"isp_id":         1,
		"branch_id":      1,
		"user_id":        5,
		"target_user_id": 17,
		"amount":         5000,
		"payment_method": 1,
		"payment_note":   "Monthly topup from HR",
	})
	req, _ := http.NewRequest("POST", endpoint, bytes.NewBuffer(payload))
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;
use serde_json::json;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();

    let response = client
        .post(format!("{BASE_URL}/api/v1/balance/user/add"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .json(&json!({
            "isp_id": 1,
            "branch_id": 1,
            "user_id": 5,
            "target_user_id": 17,
            "amount": 5000,
            "payment_method": 1,
            "payment_note": "Monthly topup from HR"
        }))
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

Get Subscriber Ledger

Retrieve balance transaction history for a subscriber.

Property	Value
Endpoint	Get Subscriber Ledger
Method	`GET`
URL	`/api/v1/balance/subscriber/{id}/ledger`
Authentication	Bearer Token

Path Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	Subscriber ID

Success Response (200 OK):

json

{
    "success": true,
    "data": [
        {
            "id": 1,
            "type": "credit",
            "amount": 500,
            "balance_after": 1500,
            "description": "Balance top-up",
            "created_at": "2024-01-15 10:30:00"
        }
    ]
}

Code Examples:

bash

curl -X GET "https://your-domain.com/api/v1/balance/subscriber/1/ledger" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-auth-token"

php

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://your-domain.com']);

$subscriberId = 1;

$response = $client->request('GET', "/api/v1/balance/subscriber/{$subscriberId}/ledger", [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);

javascript

const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const subscriberId = 1;

const response = await fetch(`${BASE_URL}/api/v1/balance/subscriber/${subscriberId}/ledger`, {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

python

import requests

BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"

subscriber_id = 1

response = requests.get(
    f"{BASE_URL}/api/v1/balance/subscriber/{subscriber_id}/ledger",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
)

data = response.json()
print(data)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strconv"
)

const baseURL = "https://your-domain.com"
const token = "your-auth-token"

func main() {
	subscriberId := 1
	endpoint := baseURL + "/api/v1/balance/subscriber/" + strconv.Itoa(subscriberId) + "/ledger"

	req, _ := http.NewRequest("GET", endpoint, nil)
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer "+token)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

rust

use reqwest::Client;

const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = Client::new();
    let subscriber_id = 1;

    let response = client
        .get(format!("{BASE_URL}/api/v1/balance/subscriber/{subscriber_id}/ledger"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    println!("{data:#}");
    Ok(())
}

User - Balance ​

Get Subscriber Balance ​

Get User Balance ​

Add Subscriber Balance ​

Add User Balance ​

Get Subscriber Ledger ​

User - Balance

Get Subscriber Balance

Get User Balance

Add Subscriber Balance

Add User Balance

Get Subscriber Ledger