Appearance
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.
| Property | Value |
|---|---|
| Endpoint | Fetch All Payments |
| Method | GET |
| URL | /api/v1/payments |
| Authentication | Bearer Token |
Request Headers:
| Header | Value | Required |
|---|---|---|
Accept | application/json | Yes |
Authorization | Bearer your-auth-token | Yes |
Query Parameters:
Required Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
isp_id | integer | Yes | ISP ID |
branch_id | integer | Yes | Branch ID |
Pagination Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
offset | integer | No | Pagination offset (default: 0) |
limit | integer | No | Results per page (default: 100) |
Filter Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
profile_type | integer | No | Filter by profile type (1=User, 2=Subscriber) |
payer_id | integer | No | Filter by payer ID (requires profile_type) |
payment_type | integer | No | Filter 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.
| Property | Value |
|---|---|
| Endpoint | Payment Receipt |
| Method | GET |
| URL | /api/v1/payments/receipt |
| Authentication | Bearer Token |
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Payment ID |
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": {
"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.
| Property | Value |
|---|---|
| Endpoint | Add Subscriber Balance |
| Method | POST |
| URL | /api/v1/payments/add-subscriber-balance |
| 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,
"payment_method": 1,
"notes": "Balance top-up"
}| 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 |
payment_method | integer | No | Payment method ID |
notes | string | No | Transaction 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(())
}