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
   }