Agent Rebalance Account Flow

📋 Overview

Complete workflow for processing agent rebalance account transactions in the GafaPay system. This flow allows agents to rebalance their wallet by depositing or withdrawing money. The agent enters the money amount and receives a reference number that must be provided to the master agent to complete the process.

This flow includes two sub-flows:

1. Deposit Flow - Agent deposits money to rebalance wallet (CIA)
2. Withdraw Flow - Agent withdraws money to rebalance wallet (COA)

🔄 Common Workflow Steps

Step 1: Get Agent Wallet Balance

• Follow the Common Transaction Flow to get agent wallet balance
• Call the Get User Wallet API to retrieve agent's available balance
• Display wallet balance to the agent for verification

Step 2: Enter Amount and Validate

• Agent enters the rebalance amount
• System validates the amount format and range
• Amount should be a positive numeric value
• For Deposit Flow: No wallet balance validation needed (agent is adding money)
• For Withdraw Flow: Validate that agent has sufficient balance for the withdrawal amount
• Display validation result to the agent

Step 3: Check Product Code Availability

• System checks if the appropriate product code is allowed for the agent:
  • Deposit Flow: Check for CIA (Cash In Agent) product code
  • Withdraw Flow: Check for COA (Cash Out Agent) product code
• Call the Get Agent Profile Products API and pass the agent's agent_profile_id
• Search for product with matching product_code in the returned products list
• If product not found → Product is not allowed for this agent, show error message and stop the process
• If product exists → Continue with the transaction flow

Step 4: Save Cash Transfer Request

• Call the Save Cash Transfer Request API with the following payload structure:

Deposit Flow (CIA)

{
    "to_user_type": 5,
    "from_user_type": 5,
    "to_user_detail": null,
    "currency_id": "1f1519903ed240578f071aa45cb479f2",
    "from_user_detail": {
        "dial_code": "+221",
        "first_name": "Suresh",
        "last_name": "Raina",
        "phone_number": "968784529",
        "user_id": "fb8f09210e0f46b7b4262d77f5b6c273",
        "user_type": 5
    },
    "amount": 100,
    "from_agent_id": "9ce964d02d3a48ada60ee28b8d61c7d3",
    "note": "CIA"
}

Withdraw Flow (COA)

{
    "to_user_type": 5,
    "from_user_type": 5,
    "to_user_detail": null,
    "currency_id": "1f1519903ed240578f071aa45cb479f2",
    "from_user_detail": {
        "dial_code": "+221",
        "first_name": "Suresh",
        "last_name": "Raina",
        "phone_number": "968784529",
        "user_id": "fb8f09210e0f46b7b4262d77f5b6c273",
        "user_type": 5
    },
    "amount": 100,
    "from_agent_id": "9ce964d02d3a48ada60ee28b8d61c7d3",
    "note": "COA"
}

Field Descriptions:

• to_user_type: 5 (Agent user type)
• from_user_type: 5 (Agent user type)
• to_user_detail: null (No receiver details needed for rebalance)
• from_user_detail: Contains logged-in agent's own details
  • user_type: 5 (Agent account type)
  • user_id: Agent's user ID
  • dial_code: Agent's country dial code
  • first_name: Agent's first name
  • last_name: Agent's last name
  • phone_number: Agent's phone number
• from_agent_id: Logged-in agent's user ID
• amount: Rebalance amount entered by agent
• note: "CIA" for deposit flow, "COA" for withdraw flow
• currency_id: Currency identifier from currency API

Step 5: Retrieve and Display Reference Number

• Extract the cash_transfer_request_id from the Save Cash Transfer Request API response
• Call the Get Cash Transfer Request API using the cash_transfer_request_id to retrieve the reference_number
• Display success message to the agent with the reference number
• Show transaction details including:
  • Transaction type (Deposit/Withdraw)
  • Amount
  • Reference number
  • Transaction date
• Important: Inform the agent that they must provide this reference number to the master agent to complete the rebalance process

📡 API References

Get Agent Wallet Balance

• API: Get User Wallet API
• Purpose: Retrieve agent's current wallet balance

Check Product Code Availability

• API: Get Agent Profile Products API
• Purpose: Verify that CIA (deposit) or COA (withdraw) product is allowed for the agent's profile
• Filter: agent_profile_id (agent's profile ID)
• Search: Look for product_code: "CIA" (deposit) or product_code: "COA" (withdraw)

Save Cash Transfer Request

• API: Save Cash Transfer Request API
• Purpose: Create and store the cash transfer request for agent rebalance
• Note: Stores agent's own details as sender, with null receiver details

Retrieve Cash Transfer Request

• API: Get Cash Transfer Request API
• Purpose: Retrieve cash transfer request details to get the reference number
• Parameter: cash_transfer_request_id from Save Cash Transfer Request response

Note: For complete API details, request/response formats, and error codes, please refer to the individual API documentation pages linked above.

🔄 Flow Logic

Deposit Flow (CIA)

1. Get agent wallet balance
   ↓
2. Enter deposit amount
   ↓
3. Check if CIA product is allowed for agent
   ├─ Product not found → Show error, stop process
   └─ Product found → Continue
      ↓
4. Call Save Cash Transfer Request API
   - Pass agent's own details
   - Set note: "CIA"
   - Set to_user_detail: null
   ├─ Failed → Show error, stop process
   └─ Success → Get cash_transfer_request_id
      ↓
5. Call Get Cash Transfer Request API
   - Use cash_transfer_request_id to get reference_number
   ├─ Failed → Show error, but transaction is complete
   └─ Success → Extract reference_number
      ↓
6. Display success message with reference number
   ↓
7. Agent provides reference number to master agent
   ↓
8. Transaction complete (pending master agent approval)

Withdraw Flow (COA)

1. Get agent wallet balance
   ↓
2. Enter withdraw amount
   ↓
3. Validate agent has sufficient balance
   ├─ Insufficient balance → Show error, stop process
   └─ Sufficient balance → Continue
      ↓
4. Check if COA product is allowed for agent
   ├─ Product not found → Show error, stop process
   └─ Product found → Continue
      ↓
5. Call Save Cash Transfer Request API
   - Pass agent's own details
   - Set note: "COA"
   - Set to_user_detail: null
   ├─ Failed → Show error, stop process
   └─ Success → Get cash_transfer_request_id
      ↓
6. Call Get Cash Transfer Request API
   - Use cash_transfer_request_id to get reference_number
   ├─ Failed → Show error, but transaction is complete
   └─ Success → Extract reference_number
      ↓
7. Display success message with reference number
   ↓
8. Agent provides reference number to master agent
   ↓
9. Transaction complete (pending master agent approval)

💡 Real-World Scenario

Deposit Scenario (CIA)

1. Agent wants to deposit 1000 units to their wallet
2. Agent opens rebalance deposit flow
3. System checks agent wallet balance (current: 500 units)
4. Agent enters deposit amount: 1000 units
5. System checks if CIA product is allowed → ✅ Allowed
6. System creates cash transfer request with note "CIA"
7. System generates reference number: REF12345
8. Agent receives reference number: REF12345
9. Agent goes to Master Agent with 1000 units cash
10. Agent provides REF12345 to Master Agent
11. Master Agent processes the deposit (outside this flow)
12. Agent's wallet balance increases by 1000 units

Withdraw Scenario (COA)

1. Agent wants to withdraw 500 units from their wallet
2. Agent opens rebalance withdraw flow
3. System checks agent wallet balance (current: 2000 units)
4. Agent enters withdraw amount: 500 units
5. System validates: 2000 >= 500 → ✅ Sufficient balance
6. System checks if COA product is allowed → ✅ Allowed
7. System creates cash transfer request with note "COA"
8. System generates reference number: REF67890
9. Agent receives reference number: REF67890
10. Agent goes to Master Agent with reference number
11. Agent provides REF67890 to Master Agent
12. Master Agent processes the withdrawal (outside this flow)
13. Agent receives 500 units cash, wallet balance decreases by 500 units

---