Bulk Transaction Inquiry by Reference API Endpoint

Usage

This endpoint is used to inquire about transaction(s) status by their reference field values.
This endpoint queries transactions using the reference field instead of transaction IDs or client references.
This endpoint implements throttling mechanism, so you can ONLY make 5 transaction inquiry requests per minute.
Requests are paginated, 50 transaction object returned per single request.
Users can only query transactions that belong to them (user isolation is enforced).

Environment	API location source	HTTP Method	Content Type
{ENV}	^transaction/inquire/by-reference/	GET/POST	JSON

Headers

{
    "Content-Type": "application/json",
    "Authorization": "Bearer {ACCESS_TOKEN}"
}

Request

Request Parameters

Field	M/O/C	Type	Notes
references_list	M	String	List of reference values (max 140 characters each). Each reference should match the `reference` field of the transaction.
bank_transactions	O	Boolean	Used when querying bank transactions. Defaults to `false` for instant transactions.

Field Details
- references_list (Mandatory):
  - Array of reference strings
  - Each reference must be a string with maximum length of 140 characters
  - Cannot be empty
  - References are matched exactly against the reference field in transactions
  - Case-sensitive matching
- bank_transactions (Optional):
  - Boolean flag to indicate if querying bank transactions
  - When true, queries BankTransaction objects linked to instant transactions
  - When false or omitted, queries InstantTransaction objects directly
  - Default: false

Response

Response Parameters

Field	Type	Notes
count	Integer	Total count of returned transactions
next	String	Link to the next page of results (null if no next page)
previous	String	Link to the previous page of results (null if no previous page)
results	List	List of transaction dictionaries matching the provided references

Transaction Object Fields

The response includes the same transaction fields as the standard bulk transaction inquiry endpoint: - transaction_id: Unique transaction identifier (UUID) - issuer: Transaction issuer (e.g., "vodafone", "etisalat", "aman", "bank_card") - amount: Transaction amount - disbursement_status: Current status ("successful", "pending", "failed") - status_code: Status code - status_description: Human-readable status description - reference: The reference field value that was used for the query - created_at: Transaction creation timestamp - updated_at: Last update timestamp - Additional fields depending on transaction type (msisdn, bank_card_number, etc.)
IMPORTANT:

3.1) failure_reason attribute will be removed soon, you can use the more generic status_description attribute.

3.2) transaction_status attribute will be renamed to be disbursement status.

3.3) channel attribute will be renamed to be issuer.

3.4) Only transactions belonging to the authenticated user are returned (user isolation).

3.5) If a reference in the list doesn't match any transaction, it is silently ignored (no error).

Samples

Bulk transaction inquiry by reference for instant transactions

request

    {
        "references_list": [
            "REF001",
            "REF002",
            "REF003"
        ]
    }

response

    {
        "count": 3,
        "next": null,
        "previous": null,
        "results": [
            {
                "transaction_id": "607f2a5a-1109-43d2-a12c-9327ab2dca18",
                "issuer": "vodafone",
                "msisdn": "01020304050",
                "amount": 100.0,
                "full_name": "John Doe",
                "disbursement_status": "successful",
                "status_code": "200",
                "status_description": "تم إيداع 100.0 جنيه إلى رقم 01020304050 بنجاح",
                "fees": 0.0,
                "vat": 0.0,
                "reference_id": "",
                "status_description": null,
                "aman_cashing_details": null,
                "client_transaction_reference": null,
                "created_at": "2025-11-23 13:36:04.870974",
                "updated_at": "2025-11-23 13:36:04.870983",
                "accept_balance_transfer_id": null,
                "reference": "REF001",
                "comment1": ""
            },
            {
                "transaction_id": "2a08d70c-49a9-48ed-bcbf-734343065477",
                "issuer": "etisalat",
                "msisdn": "01019706920",
                "amount": 200.5,
                "full_name": "Jane Smith",
                "disbursement_status": "pending",
                "status_code": "8000",
                "status_description": "Transaction received and validated successfully",
                "fees": 0.0,
                "vat": 0.0,
                "reference_id": "",
                "status_description": null,
                "aman_cashing_details": null,
                "client_transaction_reference": null,
                "created_at": "2025-11-23 13:36:04.871753",
                "updated_at": "2025-11-23 13:36:04.871762",
                "accept_balance_transfer_id": null,
                "reference": "REF002",
                "comment1": ""
            },
            {
                "transaction_id": "1531eb29-199e-4487-96ab-72ef76564a42",
                "issuer": "aman",
                "msisdn": "01019506911",
                "amount": 300.75,
                "full_name": "Bob Johnson",
                "disbursement_status": "successful",
                "status_code": "200",
                "status_description": "برجاء التوجه إلى فرع أمان",
                "fees": 0.0,
                "vat": 0.0,
                "reference_id": "",
                "status_description": null,
                "aman_cashing_details": {
                    "bill_reference": 3943627,
                    "is_paid": false
                },
                "client_transaction_reference": null,
                "created_at": "2025-11-23 13:36:04.872497",
                "updated_at": "2025-11-23 13:36:04.872505",
                "accept_balance_transfer_id": null,
                "reference": "REF003",
                "comment1": ""
            }
        ]
    }

Bulk transaction inquiry by reference for bank transactions

request

    {
        "references_list": [
            "BANK_REF_001",
            "BANK_REF_002"
        ],
        "bank_transactions": true
    }

response

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "transaction_id": "1e886593-03b1-4af9-b9e0-72b39fef479b",
                "issuer": "bank_card",
                "amount": "100.00",
                "bank_card_number": "8881914753038370",
                "full_name": "Tom Bernard Ceisar",
                "bank_code": "ADCB",
                "bank_transaction_type": "cash_transfer",
                "disbursement_status": "pending",
                "status_code": "8000",
                "status_description": "Transaction received and validated successfully. Dispatched for being processed by the bank",
                "created_at": "2020-10-06 16:39:06.617370",
                "updated_at": "2020-10-06 16:39:13.093580"
            },
            {
                "transaction_id": "8613a98e-3fa3-47c2-8dbf-874bc4fba62d",
                "issuer": "bank_card",
                "amount": "100.00",
                "bank_card_number": "8602522883580815",
                "full_name": "Tom Bernard Ceisar",
                "bank_code": "ENBD",
                "bank_transaction_type": "prepaid_card",
                "disbursement_status": "pending",
                "status_code": "8000",
                "status_description": "Transaction received and validated successfully. Dispatched for being processed by the bank",
                "created_at": "2020-10-06 16:35:48.823069",
                "updated_at": "2020-10-06 16:35:53.492712"
            }
        ]
    }

Single reference inquiry

request

    {
        "references_list": [
            "REF001"
        ]
    }

response

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "transaction_id": "607f2a5a-1109-43d2-a12c-9327ab2dca18",
                "issuer": "vodafone",
                "msisdn": "01020304050",
                "amount": 100.0,
                "full_name": "John Doe",
                "disbursement_status": "successful",
                "status_code": "200",
                "status_description": "تم إيداع 100.0 جنيه إلى رقم 01020304050 بنجاح",
                "reference": "REF001",
                "created_at": "2025-11-23 13:36:04.870974",
                "updated_at": "2025-11-23 13:36:04.870983"
            }
        ]
    }

Query with nonexistent references

request

    {
        "references_list": [
            "NONEXISTENT_REF",
            "ANOTHER_MISSING_REF"
        ]
    }

response

    {
        "count": 0,
        "next": null,
        "previous": null,
        "results": []
    }

Query with mix of existing and nonexistent references

request

    {
        "references_list": [
            "REF001",
            "NONEXISTENT_REF",
            "REF002"
        ]
    }

response

    {
        "count": 2,
        "next": null,
        "previous": null,
        "results": [
            {
                "transaction_id": "607f2a5a-1109-43d2-a12c-9327ab2dca18",
                "issuer": "vodafone",
                "amount": 100.0,
                "disbursement_status": "successful",
                "reference": "REF001",
                ...
            },
            {
                "transaction_id": "2a08d70c-49a9-48ed-bcbf-734343065477",
                "issuer": "etisalat",
                "amount": 200.5,
                "disbursement_status": "pending",
                "reference": "REF002",
                ...
            }
        ]
    }

Error Responses

Validation Errors (400 Bad Request)

Empty references list

{
    "references_list": ["This field may not be empty."]
}

Missing references_list field

{
    "references_list": ["This field is required."]
}

Reference exceeds max length (140 characters)

{
    "references_list": {
        "0": ["Ensure this field has no more than 140 characters."]
    }
}

Authentication Errors (401 Unauthorized)

Missing or invalid token

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

Authorization Errors (403 Forbidden)

Insufficient permissions

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

Throttling Errors (429 Too Many Requests)

Exceeded rate limit

{
    "status_description": "Request was throttled. Expected available in 55 seconds.",
    "status_code": "429"
}

Differences from Standard Bulk Transaction Inquiry

Feature	Standard Bulk Inquiry	By Reference Inquiry
Query Field	`uid`, `client_transaction_reference`, or `client_reference`	`reference` field only
Input Type	UUIDs or client references	Reference strings (max 140 chars)
Use Case	Query by transaction IDs or client references	Query by custom reference values
Matching	Supports UUID validation and mixed types	Exact string matching only

Best Practices

Reference Format: Use consistent reference formats for easier tracking
Reference Length: Keep references under 140 characters
Batch Size: Query multiple references in a single request for efficiency
Error Handling: Handle cases where some references may not exist
User Isolation: Remember that users can only query their own transactions
Rate Limiting: Respect the 5 requests per minute limit

Integration Notes

The endpoint supports both GET and POST methods
References are matched exactly (case-sensitive)
Non-existent references are silently ignored (no error returned)
Results are paginated (50 transactions per page)
User isolation is enforced - users can only see their own transactions
The reference field is different from client_reference and client_transaction_reference