Skip to main content
GET
/
v3
/
mobile
/
list
List Mobile Top-Ups
curl --request GET \
  --url https://api.oneclickdz.com/v3/mobile/list \
  --header 'X-Access-Token: <api-key>'
{
  "success": true,
  "data": {
    "items": [
      {}
    ],
    "pagination": {
      "page": 123,
      "pageSize": 123,
      "totalPages": 123,
      "totalResults": 123
    }
  },
  "meta": {
    "timestamp": "<string>"
  }
}

​
Overview

Returns a paginated list of all mobile top-up transactions for your account with optional date filtering.

​
Query Parameters

​
page
integer
default:1
Page number (minimum: 1)
​
pageSize
integer
default:20
Items per page (minimum: 1, maximum: 100)
​
from
string
Start date filter (ISO 8601: 2025-10-01T00:00:00Z)
​
to
string
End date filter (ISO 8601: 2025-10-31T23:59:59Z)
Both from and to must be provided together when filtering by date.

​
Response

​
success
boolean
required
Indicates if the request was successful
​
data
object
required
​
meta
object
required

​
Examples

curl https://api.oneclickdz.com/v3/mobile/list?page=1&pageSize=20 \
  -H "X-Access-Token: YOUR_API_KEY"

​
Response Example

{
  "success": true,
  "data": {
    "items": [
      {
        "ref": "API-+213665983439-test-1761698196315-suggest",
        "status": "REFUNDED",
        "plan_code": "PREPAID_DJEZZY",
        "MSSIDN": "0600000002",
        "topup_amount": 500,
        "balance_amount": 0,
        "created_at": "2025-10-29T00:36:36.385Z",
        "_id": "69016194e9e88196b4eb64ce",
        "refund_message": "هذا رقم الهاتف لا يقبل العرض المرسل، الرجاء إرسال أحد العروض التالية",
        "suggested_offers": [
          {
            "typename": "📋 FACTURE | فاتورة",
            "plan_code": "FACTURE_DJEZZY",
            "amount": 500
          }
        ]
      },
      {
        "ref": "API-+213665983439-test-1761698175883-refund",
        "status": "REFUNDED",
        "plan_code": "PREPAID_DJEZZY",
        "MSSIDN": "0600000001",
        "topup_amount": 500,
        "balance_amount": 0,
        "created_at": "2025-10-29T00:36:15.952Z",
        "_id": "6901617fe9e88196b4eb64c7",
        "refund_message": "رقم الهاتف خاطئ يرجى التحقق منه"
      },
      {
        "ref": "API-+213665983439-test-1761698159224-success",
        "status": "FULFILLED",
        "plan_code": "PREPAID_DJEZZY",
        "MSSIDN": "0778037340",
        "topup_amount": 500,
        "balance_amount": 0,
        "created_at": "2025-10-29T00:35:59.378Z",
        "_id": "6901616fe9e88196b4eb64b0"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 5,
      "totalPages": 72,
      "totalResults": 358
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:47.159Z"
  }
}

​
Use Cases

Transaction History

Display top-up history to users

Reports & Analytics

Generate sales reports and statistics

Reconciliation

Verify transactions and balance changes

Customer Support

Look up user transactions for support

​
Filtering Examples

​
By Date Range

curl "https://api.oneclickdz.com/v3/mobile/list?from=2025-10-01T00:00:00Z&to=2025-10-31T23:59:59Z" \
  -H "X-Access-Token: YOUR_API_KEY"

​
Client-Side Filtering

const { items } = data;

// Filter by status
const fulfilled = items.filter((t) => t.status === "FULFILLED");
const refunded = items.filter((t) => t.status === "REFUNDED");

// Filter by operator
const djezzy = items.filter((t) => t.plan_code.includes("DJEZZY"));

// Filter by amount range
const large = items.filter((t) => t.topup_amount >= 1000);

// Calculate totals
const totalAmount = items.reduce((sum, t) => sum + t.topup_amount, 0);
const totalCost = items.reduce((sum, t) => sum + t.balance_amount, 0);
const profit = totalAmount - totalCost;

​
Best Practices

  • Use reasonable page sizes (20-50 items)
  • Cache results when possible
  • Implement “Load More” or infinite scroll
  • Use pagination.totalPages to determine if there are more pages
  • Always provide both from and to - Use proper ISO 8601 format - Consider user’s timezone when filtering - Set reasonable date ranges for performance
  • Cache list data for short periods - Use date filters to limit result sets - Avoid fetching all pages at once - Index by created_at in your local database
  • Show status with icons/colors
  • Format timestamps in local timezone
  • Display operator logos
  • Link to detailed status pages
  • Show refund reason for failed top-ups

Send Top-Up

Create new top-up

Check Status

Track specific top-up

List Plans

View available plans