Topup Request API Endpoint

Usage

  • This endpoint is used to request balance top-ups through various transfer methods.
  • This endpoint supports multiple transfer types including bank transfers and Accept balance transfers.
  • For trust users with bank transfers, automatic approval may occur based on timing conditions.
Environment API location source HTTP Method Content Type
{ENV} ^topup/request/ POST multipart/form-data

Headers

{
    "Content-Type": "multipart/form-data",
    "Authorization": "Bearer {ACCESS_TOKEN}"
}

Request

  1. Request Parameters

    Field M/O/C Type Notes
    amount M Integer Amount to be topped up
    type M String Transfer type
    currency M String Currency for the topup
    username C String Accept username (required for Accept balance transfers)
    from_bank C String Source bank name (required for bank transfers)
    from_account_number C String Source account number (required for bank transfers)
    from_account_name C String Source account holder name (required for bank transfers)
    from_date C Date Transfer date (required for bank transfers)
    to_attach_proof C File Proof of transfer document (required for bank transfers, max 2.8MB)
    • Usage:
      • {type} options list: [from_bank_transfer, from_accept_balance] -case sensitive-.
      • {currency} options list: [egyptian_pound, american_dollar] -case sensitive-.
      • {amount} must be a positive integer.
      • {from_date} format: YYYY-MM-DD.
      • {to_attach_proof} maximum file size: 2.8MB, supported formats: PDF, JPG, PNG, etc.

Response

  1. Response Parameters

    Field Type Notes
    id Integer Unique identifier for the topup request
    client_id Integer ID of the client making the request
    amount String Amount of the topup request
    transfer_type String Type of transfer
    username String Accept username (nullable)
    from_bank String Source bank name (nullable)
    to_bank String Destination bank name (nullable)
    from_account_number String Source account number (nullable)
    to_account_number String Destination account number (nullable)
    from_account_name String Source account holder name (nullable)
    to_account_name String Destination account holder name (nullable)
    from_date String Transfer date (nullable)
    to_attach_proof String Path to uploaded proof document (nullable)
    automatic Boolean Whether the topup was automatically approved
    accept_balance_transfer_id String Accept balance transfer ID (nullable)
    status String Current status of the topup request
    reason String Reason for rejection (nullable)

  2. IMPORTANT:

    2.1) Status options: [pending, approved, rejected]

    2.2) Transfer Type options: [from_bank_transfer, from_accept_balance]

    2.3) Currency options: [egyptian_pound, american_dollar]

Samples

  1. Bank transfer topup request

    request

        {
        "amount": 1000,
        "type": "from_bank_transfer",
        "currency": "egyptian_pound",
        "from_bank": "Commercial International Bank",
        "from_account_number": "1234567890",
        "from_account_name": "John Doe",
        "from_date": "2024-01-15",
        "to_attach_proof": "[FILE_UPLOAD]"
    }

    response

        {
        "id": 123,
        "client_id": 456,
        "amount": "1000.00",
        "transfer_type": "from_bank_transfer",
        "username": null,
        "from_bank": "Commercial International Bank",
        "to_bank": "CIB",
        "from_account_number": "1234567890",
        "to_account_number": "9876543210",
        "from_account_name": "John Doe",
        "to_account_name": "PayMob Company",
        "from_date": "2024-01-15",
        "to_attach_proof": "/media/transfer_request_attach/abc12_proof.pdf",
        "automatic": false,
        "accept_balance_transfer_id": null,
        "status": "pending",
        "reason": null
    }

  2. Accept balance transfer topup request

    request

        {
        "amount": 500,
        "type": "from_accept_balance",
        "currency": "egyptian_pound",
        "username": "accept_user_123"
    }

    response

        {
        "id": 124,
        "client_id": 456,
        "amount": "500.00",
        "transfer_type": "from_accept_balance",
        "username": "accept_user_123",
        "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": null,
        "status": "pending",
        "reason": null
    }

  3. Validation error response

    {
    "disbursement_status": "failed",
    "status_description": {
        "from_bank": ["This field is required"],
        "to_attach_proof": ["The uploaded attachment size must be less than 3 MB"]
    },
    "status_code": "400"
}

  4. Authentication error response

    {
    "detail": "Authentication credentials were not provided.",
    "disbursement_status": "failed",
    "status_code": "401"
}

  5. Trust user automatic approval response

    {
    "id": 125,
    "client_id": 456,
    "amount": "1000.00",
    "transfer_type": "from_bank_transfer",
    "username": null,
    "from_bank": "Commercial International Bank",
    "to_bank": "CIB",
    "from_account_number": "1234567890",
    "to_account_number": "9876543210",
    "from_account_name": "John Doe",
    "to_account_name": "PayMob Company",
    "from_date": "2024-01-15",
    "to_attach_proof": "/media/transfer_request_attach/abc12_proof.pdf",
    "automatic": true,
    "accept_balance_transfer_id": null,
    "status": "approved",
    "reason": null
}

Topup Status Callbacks

Overview

When a topup request is approved or rejected, the system can send an automatic callback notification to your configured callback URL. This allows you to receive real-time updates about your topup request status changes.

Setup

To receive topup callbacks, you need to: 1. Set your topup_callback_url field in your merchant profile 2. Ensure your callback endpoint can receive POST requests with JSON payloads 3. Return a 200 HTTP status code to acknowledge receipt

Note: The topup callback URL is separate from the disbursement callback URL, allowing you to handle topup and disbursement notifications independently.

Callback Trigger Events

Callbacks are sent when: - ✅ Topup Approved - Manual approval by admin - ✅ Topup Approved - Automatic approval (trust users) - ✅ Topup Approved - Accept balance transfer approval - ❌ Topup Rejected - Manual rejection by admin - ❌ Topup Rejected - Failed balance transfer

Callback Payload Structure

{
    "topup_id": 123,
    "merchant_username": "merchant_api",
    "amount": "1000.00",
    "currency": "egyptian_pound",
    "transfer_type": "from_bank_transfer",
    "status": "approved",
    "reason": null,
    "balance_before": "5000.00",
    "balance_after": "6000.00",
    "from_bank": "Commercial International Bank",
    "from_account_number": "1234567890",
    "accept_balance_transfer_id": null,
    "automatic": false,
    "created_at": "2025-01-15 10:30:00",
    "updated_at": "2025-01-15 14:20:00"
}

Callback Payload Fields

Field Type Description
topup_id Integer Unique identifier of the topup request
merchant_username String Your merchant username
amount String Topup amount
currency String Currency (egyptian_pound/american_dollar)
transfer_type String Transfer type (from_bank_transfer/from_accept_balance)
status String Status (approved/rejected)
reason String/null Rejection reason (null if approved)
balance_before String/null Balance before topup (null if rejected)
balance_after String/null Balance after topup (null if rejected)
from_bank String/null Source bank name
from_account_number String/null Source account number
accept_balance_transfer_id String/null Accept balance transfer ID
automatic Boolean Whether approval was automatic
created_at String Request creation timestamp
updated_at String Last update timestamp

Callback Examples

1. Approved Topup Callback

{
    "topup_id": 125,
    "merchant_username": "merchant_api",
    "amount": "1000.00",
    "currency": "egyptian_pound",
    "transfer_type": "from_bank_transfer",
    "status": "approved",
    "reason": null,
    "balance_before": "5000.00",
    "balance_after": "6000.00",
    "from_bank": "Commercial International Bank",
    "from_account_number": "1234567890",
    "accept_balance_transfer_id": null,
    "automatic": true,
    "created_at": "2025-01-15 10:30:00",
    "updated_at": "2025-01-15 14:20:00"
}

2. Rejected Topup Callback

{
    "topup_id": 126,
    "merchant_username": "merchant_api",
    "amount": "500.00",
    "currency": "egyptian_pound",
    "transfer_type": "from_bank_transfer",
    "status": "rejected",
    "reason": "Invalid bank proof document",
    "balance_before": null,
    "balance_after": null,
    "from_bank": "Commercial International Bank",
    "from_account_number": "1234567890",
    "accept_balance_transfer_id": null,
    "automatic": false,
    "created_at": "2025-01-15 10:30:00",
    "updated_at": "2025-01-15 15:45:00"
}

Callback Response

Your callback endpoint should return a 200 HTTP status code to acknowledge successful receipt. The system will log all callback attempts for monitoring purposes.

Example Response:

{
    "status": "success",
    "message": "Callback received"
}

Error Handling

  • Callbacks have a 10-second timeout
  • Failed callbacks are logged but do not block the topup approval/rejection process
  • Non-200 responses are logged as failed callbacks
  • Network errors and timeouts are logged appropriately