Topup Inquiry API Endpoint

Overview

The Topup Inquiry API allows you to retrieve and filter your topup requests. This is useful for tracking topup request history, checking status, and managing topup workflows.

Usage

Environment	API location source	HTTP Method	Content Type
{ENV}	^topup/inquire/	GET	JSON
{ENV}	^topup/inquire//	GET	JSON

Authentication

These endpoints require OAuth2 authentication with a valid access token. The user must have InstantAPIChecker role.

Headers

Authorization: Bearer <your_access_token>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by topup status. Valid values: `pending`, `approved`, `rejected`, `initiated`
`from_date`	string	No	Filter topups from this date (format: `YYYY-MM-DD`)
`to_date`	string	No	Filter topups until this date (format: `YYYY-MM-DD`)
`page`	integer	No	Page number for pagination (default: 1)
`page_size`	integer	No	Number of results per page (default: 10, max: 100)

Response Format

Success Response (200 OK)

{
  "count": 45,
  "next": "http://example.com/api/topup/inquire/?page=2",
  "previous": null,
  "results": {
    "status": "success",
    "topup_requests": [
      {
        "id": 123,
        "client_id": 5,
        "amount": "10000.00",
        "currency": "egyptian_pound",
        "transfer_type": "from_bank_transfer",
        "username": "644420",
        "from_bank": "National Bank of Egypt",
        "to_bank": "alex",
        "from_account_number": "1234567890",
        "to_account_number": "9876543210",
        "from_account_name": "John Doe",
        "to_account_name": "Paymob Solutions",
        "from_date": "2025-10-20",
        "to_attach_proof": "media/transfer_request_attach/abc12_proof.jpg",
        "automatic": false,
        "accept_balance_transfer_id": null,
        "status": "pending",
        "reason": null,
        "bank_reference": "REF123456",
        "is_t_plus_two": false,
        "trust_user": false,
        "created_at": "2025-10-20T10:21:50.147215Z",
        "updated_at": "2025-10-20T10:21:50.147215Z"
      },
      {
        "id": 124,
        "client_id": 5,
        "amount": "5000.00",
        "currency": "egyptian_pound",
        "transfer_type": "from_accept_balance",
        "username": "644420",
        "from_bank": null,
        "to_bank": null,
        "from_account_number": null,
        "to_account_number": null,
        "from_account_name": null,
        "to_account_name": null,
        "from_date": null,
        "to_attach_proof": null,
        "automatic": false,
        "accept_balance_transfer_id": "TRX789",
        "status": "approved",
        "reason": null,
        "bank_reference": null,
        "is_t_plus_two": false,
        "trust_user": false,
        "created_at": "2025-10-19T15:30:20.123456Z",
        "updated_at": "2025-10-19T16:45:10.654321Z"
      }
    ],
    "count": 45
  }
}

Error Responses

400 Bad Request - Invalid Parameters

{
  "status": "failed",
  "message": "Invalid status. Must be one of: pending, approved, rejected, initiated",
  "status_code": "400"
}

{
  "status": "failed",
  "message": "Invalid from_date format. Use YYYY-MM-DD",
  "status_code": "400"
}

401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

403 Forbidden

{
  "detail": "You do not have permission to perform this action."
}

500 Internal Server Error

{
  "status": "failed",
  "message": "Process stopped during an internal error, can you try again or contact your support team",
  "status_code": "500"
}

Response Fields

Field	Type	Description
`id`	integer	Unique identifier for the topup request
`client_id`	integer	ID of the client who made the request
`amount`	decimal	Amount to be topped up
`currency`	string	Currency of the topup (e.g., `egyptian_pound`, `american_dollar`)
`transfer_type`	string	Type of transfer (`from_bank_transfer`, `from_accept_balance`, `from_bank_deposit`)
`username`	string	Accept username (for Accept Balance transfers)
`from_bank`	string	Source bank name
`to_bank`	string	Destination bank (`alex`, `other`)
`from_account_number`	string	Source account number
`to_account_number`	string	Destination account number
`from_account_name`	string	Source account holder name
`to_account_name`	string	Destination account holder name
`from_date`	date	Date of transfer
`to_attach_proof`	string	Path to transfer proof attachment
`automatic`	boolean	Whether topup was automatic
`accept_balance_transfer_id`	string	Accept balance transfer reference ID
`status`	string	Current status: `pending`, `approved`, `rejected`, or `initiated`
`reason`	string	Rejection reason (if rejected)
`bank_reference`	string	Bank reference number
`is_t_plus_two`	boolean	Whether this is a T+2 topup
`trust_user`	boolean	Whether this is from a trust user
`created_at`	datetime	When the topup request was created
`updated_at`	datetime	When the topup request was last updated

Inquire Specific Topup by ID

Endpoint

GET ^topup/inquire/<topup_id>/

Authentication

Same as list endpoint - requires OAuth2 authentication with InstantAPIChecker role.

Path Parameters

Parameter	Type	Required	Description
`topup_id`	integer	Yes	The ID of the topup request to retrieve

Success Response (200 OK)

{
  "status": "success",
  "topup_request": {
    "id": 123,
    "client_id": 5,
    "amount": "10000.00",
    "currency": "egyptian_pound",
    "transfer_type": "from_bank_transfer",
    "username": "644420",
    "from_bank": "National Bank of Egypt",
    "to_bank": "alex",
    "from_account_number": "1234567890",
    "to_account_number": "9876543210",
    "from_account_name": "John Doe",
    "to_account_name": "Paymob Solutions",
    "from_date": "2025-10-20",
    "to_attach_proof": "media/transfer_request_attach/abc12_proof.jpg",
    "automatic": false,
    "accept_balance_transfer_id": null,
    "status": "pending",
    "reason": null,
    "bank_reference": "REF123456",
    "is_t_plus_two": false,
    "trust_user": false,
    "created_at": "2025-10-20T10:21:50.147215Z",
    "updated_at": "2025-10-20T10:21:50.147215Z"
  }
}

Error Responses

404 Not Found

{
  "status": "failed",
  "message": "Topup request with ID 123 not found or you don't have permission to access it",
  "status_code": "404"
}

401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

500 Internal Server Error

{
  "status": "failed",
  "message": "Process stopped during an internal error, can you try again or contact your support team",
  "status_code": "500"
}

Examples

Example 1: Get Specific Topup by ID

curl -X GET "^topup/inquire/123/" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

Example 2: Get All Topup Requests (First Page)

curl -X GET "^topup/inquire/" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

Example 3: Filter by Status

curl -X GET "^topup/inquire/?status=pending" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

Example 4: Filter by Date Range

curl -X GET "^topup/inquire/?from_date=2025-10-01&to_date=2025-10-31" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

Example 5: Filter by Status and Date with Custom Page Size

curl -X GET "^topup/inquire/?status=approved&from_date=2025-10-01&page_size=25" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

Example 6: Get Specific Page

curl -X GET "^topup/inquire/?page=2&page_size=20" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json"

Pagination

The API uses cursor-based pagination. The response includes: - count: Total number of topup requests matching your filters - next: URL for the next page (null if no more pages) - previous: URL for the previous page (null if on first page) - results: The actual data

Use Cases

Get Specific Topup Details: Use the ID endpoint to get full details of a specific topup request
Monitor Pending Topups: Filter by status=pending to see all pending topup requests awaiting approval
Audit Approved Topups: Filter by status=approved and date range to audit completed topups
Track Rejected Requests: Filter by status=rejected to review rejected topups and their reasons
Generate Reports: Use date filters to generate monthly or weekly topup reports
Integration Workflows: Automatically check topup status in your application
Polling for Updates: Periodically check specific topup IDs to monitor status changes

Notes

All topup requests are filtered by the authenticated user's root client automatically
Dates are returned in ISO 8601 format with UTC timezone
The maximum page size is 100 results
Results are ordered by created_at in descending order (newest first)
File attachments are returned as relative paths; construct full URLs using your media root

Topup Request API - Create new topup requests
Budget Inquiry API - Check current budget balance
Bulk Transaction Inquiry API - Check transaction status

Support

For additional help or questions, please contact the Paymob support team.

Topup Inquiry API Endpoint

Overview

Usage

Authentication

Headers

Query Parameters

Response Format

Success Response (200 OK)

Error Responses

400 Bad Request - Invalid Parameters

401 Unauthorized

403 Forbidden

500 Internal Server Error

Response Fields

Inquire Specific Topup by ID

Endpoint

Authentication

Path Parameters

Success Response (200 OK)

Error Responses

404 Not Found

401 Unauthorized

500 Internal Server Error

Examples

Example 1: Get Specific Topup by ID

Example 2: Get All Topup Requests (First Page)

Example 3: Filter by Status

Example 4: Filter by Date Range

Example 5: Filter by Status and Date with Custom Page Size

Example 6: Get Specific Page

Pagination

Use Cases

Notes

Related APIs

Support