Skip to content

User - Payments ​

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

Admin endpoints for managing payments. All endpoints require admin/staff authentication.


Fetch All Payments ​

Retrieve a paginated list of all payment transactions. Returns payment data with action by user, user data, and subscriber with salesperson information.

PropertyValue
EndpointFetch All Payments
MethodGET
URL/api/v1/payments
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Query Parameters:

Required Parameters ​

ParameterTypeRequiredDescription
isp_idintegerYesISP ID
branch_idintegerYesBranch ID

Pagination Parameters ​

ParameterTypeRequiredDescription
offsetintegerNoPagination offset (default: 0)
limitintegerNoResults per page (default: 100)

Filter Parameters ​

ParameterTypeRequiredDescription
profile_typeintegerNoFilter by profile type (1=User, 2=Subscriber)
payer_idintegerNoFilter by payer ID (requires profile_type)
payment_typeintegerNoFilter by payment method

Request Body: None

Success Response (200 OK):

json
{
    "success": true,
    "data": {
        "payments": [
            {
                "id": 1,
                "subscriber_id": 1,
                "subscriber_name": "John Doe",
                "amount": 1000,
                "payment_method": "Cash",
                "invoice_id": 123,
                "received_by": "Admin User",
                "created_at": "2024-01-15 10:30:00"
            }
        ],
        "total": 50
    }
}

Error Response (401 Unauthorized):

json
{
    "success": false,
    "message": "Unauthenticated"
}

Code Examples:

bash
curl -X GET "https://your-domain.com/api/v1/payments?isp_id=1&branch_id=1&offset=0&limit=100" \
  -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']);

$response = $client->request('GET', '/api/v1/payments', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'query' => [
        'isp_id'    => 1,
        'branch_id' => 1,
        'offset'    => 0,
        'limit'     => 100,
    ],
]);

$data = json_decode($response->getBody(), true);
print_r($data);
javascript
const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';

const params = new URLSearchParams({
  isp_id: 1,
  branch_id: 1,
  offset: 0,
  limit: 100,
});

const response = await fetch(`${BASE_URL}/api/v1/payments?${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"

response = requests.get(
    f"{BASE_URL}/api/v1/payments",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    params={
        "isp_id": 1,
        "branch_id": 1,
        "offset": 0,
        "limit": 100,
    },
)

data = response.json()
print(data)
go
package main

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

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

func main() {
	endpoint := baseURL + "/api/v1/payments"

	q := url.Values{}
	q.Set("isp_id", "1")
	q.Set("branch_id", "1")
	q.Set("offset", "0")
	q.Set("limit", "100")
	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 response = client
        .get(format!("{BASE_URL}/api/v1/payments"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .query(&[
            ("isp_id", "1"),
            ("branch_id", "1"),
            ("offset", "0"),
            ("limit", "100"),
        ])
        .send()
        .await?;

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

Payment Receipt ​

Get payment receipt data including payment details and ISP information with area data.

PropertyValue
EndpointPayment Receipt
MethodGET
URL/api/v1/payments/receipt
AuthenticationBearer Token

Query Parameters:

ParameterTypeRequiredDescription
idintegerYesPayment ID
isp_idintegerYesISP ID
branch_idintegerYesBranch ID
user_idintegerYesUser ID

Success Response (200 OK):

json
{
    "success": true,
    "data": {
        "receipt_number": "RCP-2024-0001",
        "subscriber_name": "John Doe",
        "amount": 1000,
        "payment_method": "Cash",
        "invoice_number": "INV-2024-0123",
        "received_by": "Admin User",
        "isp_name": "Your ISP Name",
        "isp_address": "123 ISP Street",
        "payment_date": "2024-01-15 10:30:00"
    }
}

Error Response (404 Not Found):

Returned when the payment does not exist in your ISP and branch, or is not one you may see (a reseller sees only the payments of its own tree, see What each user sees).

json
{
    "status": "error",
    "message": "Oops! Something Wrong."
}

Code Examples:

bash
curl -X GET "https://your-domain.com/api/v1/payments/receipt?id=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']);

$response = $client->request('GET', '/api/v1/payments/receipt', [
    'headers' => [
        'Accept'        => 'application/json',
        'Authorization' => 'Bearer your-auth-token',
    ],
    'query' => [
        'id'        => 1,
        '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 params = new URLSearchParams({
  id: 1,
  isp_id: 1,
  branch_id: 1,
  user_id: 1,
});

const response = await fetch(`${BASE_URL}/api/v1/payments/receipt?${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"

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

data = response.json()
print(data)
go
package main

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

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

func main() {
	endpoint := baseURL + "/api/v1/payments/receipt"

	q := url.Values{}
	q.Set("id", "1")
	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 response = client
        .get(format!("{BASE_URL}/api/v1/payments/receipt"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .query(&[
            ("id", "1"),
            ("isp_id", "1"),
            ("branch_id", "1"),
            ("user_id", "1"),
        ])
        .send()
        .await?;

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

Add Subscriber Balance ​

Add balance to a subscriber account. Creates a payment record and updates subscriber balance. Rate limited to prevent duplicate payments within 60 seconds.

PropertyValue
EndpointAdd Subscriber Balance
MethodPOST
URL/api/v1/payments/add-subscriber-balance
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Content-Typeapplication/jsonYes
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Request Body:

json
{
    "isp_id": 1,
    "branch_id": 1,
    "user_id": 1,
    "subscriber_id": 1,
    "amount": 500,
    "payment_method": 1,
    "notes": "Balance top-up"
}
ParameterTypeRequiredDescription
isp_idintegerYesISP ID
branch_idintegerYesBranch ID
user_idintegerYesAdmin user ID
subscriber_idintegerYesSubscriber ID
amountdecimalYesAmount to add
payment_methodintegerNoPayment method ID
notesstringNoTransaction notes

Success Response (200 OK):

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

Error Response (404 Not Found):

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

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/payments/add-subscriber-balance" \
  -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,
    "payment_method": 1,
    "notes": "Balance top-up"
  }'
php
<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;

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

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

$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/payments/add-subscriber-balance`, {
  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,
    payment_method: 1,
    notes: 'Balance top-up',
  }),
});

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/payments/add-subscriber-balance",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    },
    json={
        "isp_id": 1,
        "branch_id": 1,
        "user_id": 1,
        "subscriber_id": 1,
        "amount": 500,
        "payment_method": 1,
        "notes": "Balance top-up",
    },
)

data = response.json()
print(data)
go
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/payments/add-subscriber-balance"

	payload, _ := json.Marshal(map[string]any{
		"isp_id":         1,
		"branch_id":      1,
		"user_id":        1,
		"subscriber_id":  1,
		"amount":         500,
		"payment_method": 1,
		"notes":          "Balance top-up",
	})
	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/payments/add-subscriber-balance"))
        .header("Accept", "application/json")
        .bearer_auth(TOKEN)
        .json(&json!({
            "isp_id": 1,
            "branch_id": 1,
            "user_id": 1,
            "subscriber_id": 1,
            "amount": 500,
            "payment_method": 1,
            "notes": "Balance top-up"
        }))
        .send()
        .await?;

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

www.onezeroart.com