Response Format

Standardized Structure

All OneClickDz Flexy API v3 endpoints follow a consistent response structure, making it easy to handle responses across your application.

Success Response

When a request is successful, the response follows this structure:

{
  "success": true,
  "data": {
    // endpoint-specific data
  },
  "meta": {
    "timestamp": "2025-10-29T00:00:00.000Z"
    // additional metadata (pagination, etc.)
  },
  "requestId": "req_1234567890_abc123"
}

Fields

boolean

required

Always true for successful responses

object

required

Contains the response payload. Structure varies by endpoint.

object

Additional metadata about the response

Show properties

string

ISO 8601 timestamp of when the response was generated

object

Pagination details (for list endpoints)

string

Unique identifier for this request. Use this when contacting support.

Error Response

When a request fails, the response follows this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // additional error context
    }
  },
  "requestId": "req_1234567890_abc123"
}

Fields

boolean

required

Always false for error responses

object

required

Contains error information

Show properties

string

Machine-readable error code (e.g., NO_BALANCE, INVALID_PHONE)

string

Human-readable error description

object

Additional context about the error (optional)

string

Unique identifier for this request. Include this when reporting issues.

Response Examples

Account Balance

{
  "success": true,
  "data": {
    "balance": 1326.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}

Mobile Top-Up Send

{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "my-order-123",
    "newBalance": 826.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:59.454Z"
  }
}

List Transactions (with Pagination)

{
  "success": true,
  "data": {
    "items": [
      {
        "type": "FLEXY",
        "amount": 500,
        "time": "2025-10-29T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.852Z"
  }
}

Pagination

List endpoints include pagination in the response:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  }
}

Pagination Fields

integer

Current page number (1-indexed)

integer

Number of items per page

integer

Total number of pages available

integer

Total number of items across all pages

Pagination Query Parameters

Control pagination using these query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (minimum: 1)
`pageSize`	integer	20	Items per page (min: 1, max: 100)

Always check totalPages to know when to stop paginating.

HTTP Status Codes

The API uses conventional HTTP status codes:

Status Code	Meaning
`200`	Success - Request completed successfully
`400`	Bad Request - Invalid parameters or validation error
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient balance or permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Something went wrong on our end
`503`	Service Unavailable - Temporary service disruption

Even for non-200 status codes, the response follows the standard error format.

Request ID

Every response includes a unique requestId:

{
  "success": true,
  "data": {...},
  "requestId": "req_1761698159_abc123xyz"
}

Uses for Request ID

Debugging

Track requests through logs and identify issues

Support

Include in support tickets for faster resolution

Auditing

Correlate requests with transactions

Monitoring

Track request flow across systems

Always log the requestId for every API call you make. It’s invaluable for debugging.

Content Type

All requests and responses use JSON:

Request Headers

Content-Type: application/json
X-Access-Token: YOUR_API_KEY

Response Headers

Content-Type: application/json; charset=utf-8
X-Request-ID: req_1761698159_abc123xyz
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1761698219

Handling Responses

Best Practices

Always Check success Field

const response = await fetch(url, options);
const data = await response.json();

if (data.success) {
  // Handle success
  console.log(data.data);
} else {
  // Handle error
  console.error(data.error.code, data.error.message);
}

Log Request IDs

console.log(`Request ${data.requestId}: ${data.success ? 'Success' : 'Failed'}`);

if (!data.success) {
  console.error(`Error ${data.error.code}: ${data.error.message}`);
}

Handle Pagination

let page = 1;
let allItems = [];

while (true) {
  const response = await fetch(`${url}?page=${page}&pageSize=100`);
  const data = await response.json();
  
  if (!data.success) break;
  
  allItems.push(...data.data.items);
  
  if (page >= data.data.pagination.totalPages) break;
  page++;
}

Parse Timestamps

const timestamp = new Date(data.meta.timestamp);
console.log(`Response generated at: ${timestamp.toLocaleString()}`);

TypeScript Types

If you’re using TypeScript, here are helpful type definitions:

interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    timestamp: string;
    pagination?: {
      page: number;
      pageSize: number;
      totalPages: number;
      totalResults: number;
    };
  };
  requestId?: string;
}

interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
  };
  requestId?: string;
}

type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;

// Usage
async function getBalance(): Promise<number> {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/account/balance",
    {
      headers: { "X-Access-Token": API_KEY },
    }
  );

  const data: ApiResponse<{ balance: number }> = await response.json();

  if (data.success) {
    return data.data.balance;
  } else {
    throw new Error(`${data.error.code}: ${data.error.message}`);
  }
}

Bill Payment

The Bill Payment API on https://api.oneclickdz.com uses the same envelope described above: success, data, meta and requestId on a success, and success, error and requestId on a failure. Three details are specific to it:

Pagination lives in meta. GET /v3/bills/transactions returns data as a plain array, with total, limit and offset in meta alongside timestamp.
requestId is always present — in the body of every response, and in the X-Request-Id header of every response. Log it against your own order; it is the only thing support needs.
One endpoint returns binary. Download Receipt streams the receipt file itself, so on success there is no JSON envelope and X-Request-Id is the only place the correlation identifier appears. Its failures use the ordinary JSON envelope.

Get Transaction by ID

The transaction object, field by field

Bill Payment Overview

How the whole flow fits together

Next Steps

Error Handling

Learn how to handle errors effectively

Core Endpoints

Explore all available endpoints

API Reference

Core

Account

Mobile Top-Ups

Internet Top-Ups

Gift Cards

Navio

Bill Payment

Standardized Structure

Success Response

Fields

Error Response

Fields

Response Examples

Account Balance

Mobile Top-Up Send

HTTP Status Codes

Request ID

Uses for Request ID

Debugging

Support

Auditing

Monitoring

Content Type

Request Headers

Response Headers

Handling Responses

Best Practices

TypeScript Types

Bill Payment

Get Transaction by ID

Bill Payment Overview

Next Steps

Error Handling

Core Endpoints

​Standardized Structure

​Success Response

​Fields

​Error Response

​Fields

​Response Examples

​Account Balance

​Mobile Top-Up Send

​List Transactions (with Pagination)

​Pagination

​Pagination Fields

​Pagination Query Parameters

​HTTP Status Codes

​Request ID

​Uses for Request ID

Debugging

Support

Auditing

Monitoring

​Content Type

​Request Headers

​Response Headers

​Handling Responses

​Best Practices

​TypeScript Types

​Bill Payment

Get Transaction by ID

Bill Payment Overview

​Next Steps

Error Handling

Core Endpoints

Standardized Structure

Success Response

Fields

Error Response

Fields

Response Examples

Account Balance

Mobile Top-Up Send

List Transactions (with Pagination)

Pagination

Pagination Fields

Pagination Query Parameters

HTTP Status Codes

Request ID

Uses for Request ID

Content Type

Request Headers

Response Headers

Handling Responses

Best Practices

TypeScript Types

Bill Payment

Next Steps