Rebalance from Reference Number Flow

📋 Overview

Complete workflow for processing agent rebalance transactions using a reference number in the GafaPay system. This flow allows master agents to process rebalance requests initiated by other agents. The master agent receives a reference number from the requesting agent and completes the rebalance transaction by transferring money between agent wallets.

This flow handles two transaction types:

CIA (Cash In Agent) - Agent deposit rebalance (agent adds money to wallet)
COA (Cash Out Agent) - Agent withdraw rebalance (agent removes money from wallet)

🔄 Workflow Steps

Step 1: Get Cash Transfer Request Details

Master agent enters the reference number provided by the requesting agent
Call the Get Cash Transfer Request API using the reference number
Validate the cash transfer request exists
Check request status:
- If request_status = 3 → Rebalance already processed, show error message and stop the process
- If request_status != 3 → Continue with the flow
Extract and display the following details to the master agent:
- Requesting agent information (from from_user_detail and from_agent_id)
- Transfer amount
- Transaction date
- Reference number
- Note field (CIA or COA) - used to identify transaction type
- Cash transfer request ID (save for Step 6)

Step 2: Get Agent Wallet Balance

Follow the Common Transaction Flow to get master agent wallet balance
Call the Get User Wallet API to retrieve master agent's available balance
For CIA (Deposit): Validate that master agent has sufficient balance (master agent will debit money)
For COA (Withdraw): Validate that requesting agent has sufficient balance (requesting agent will debit money)
Display wallet balance to the master agent for verification

Step 3: Identify Transaction Type

Based on the cash transfer request details, identify the transaction type from the note field:
- CIA (Cash In Agent) - If note = "CIA" → Deposit rebalance (agent wants to add money)
- COA (Cash Out Agent) - If note = "COA" → Withdraw rebalance (agent wants to remove money)
Extract the from_agent_id from the cash transfer request (this is the requesting agent's ID)
This product code (CIA or COA) will be used in the wallet transfer API

Step 4: Check Product Code Availability

Verify that the identified product code (CIA or COA) is allowed for the master agent
Call the Get Agent Profile Products API and pass the master agent's agent_profile_id
Search for the product with matching product_code (CIA or COA) in the returned products list
If product not found → Product is not allowed for this master agent, show error message and stop the process
If product exists → Continue with the transaction flow

Step 5: Prepare and Execute Wallet Transfer API

5.1: CIA (Cash In Agent) - Deposit Rebalance

For CIA transactions, the requesting agent wants to deposit money (add to their wallet)
In the credit_user_info, pass the requesting agent's details (from from_agent_id)
In the debit_user_info, pass the master agent's details (logged-in master agent)
Call the Wallet Transfer API with the following payload structure:

{
    "charges_info": null,
    "note": null,
    "txn_amount": 100,
    "txn_code": "CIA",
    "payment_mode": 3,
    "company_admin_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 1,
        "credit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Mouhamad Amine"
    },
    "txn_device_info": {
        "device_name": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
        "os_name": "MacIntel",
        "location": {},
        "host_name": "localhost",
        "url": "http://localhost:9000"
    },
    "debit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "debit_type": 1,
        "debit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "debit_account_type": 5,
        "debit_account_type_id": "dd4403366e944eb4b302a69f684bc52e",
        "username": "Master Agent Name"
    },
    "credit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 5,
        "credit_account_type_id": "9ce964d02d3a48ada60ee28b8d61c7d3",
        "username": "Requesting Agent Name"
    }
}

Field Descriptions for CIA:

txn_code: "CIA" (Cash In Agent)
payment_mode: 3 (Wallet payment)
txn_amount: Amount from cash transfer request
debit_user_info: Contains master agent's details (logged-in master agent)
- debit_account_type: 5 (Agent account type)
- debit_account_type_id: Master agent's user ID
credit_user_info: Contains requesting agent's details (from from_agent_id)
- credit_account_type: 5 (Agent account type)
- credit_account_type_id: Requesting agent's user ID (from from_agent_id)

5.2: COA (Cash Out Agent) - Withdraw Rebalance

For COA transactions, the requesting agent wants to withdraw money (remove from their wallet)
In the credit_user_info, pass the master agent's details (logged-in master agent)
In the debit_user_info, pass the requesting agent's details (from from_agent_id)
Call the Wallet Transfer API with the following payload structure:

{
    "charges_info": null,
    "note": null,
    "txn_amount": 100,
    "txn_code": "COA",
    "payment_mode": 3,
    "company_admin_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 1,
        "credit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Mouhamad Amine"
    },
    "txn_device_info": {
        "device_name": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",
        "os_name": "MacIntel",
        "location": {},
        "host_name": "localhost",
        "url": "http://localhost:9000"
    },
    "debit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "debit_type": 1,
        "debit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "debit_account_type": 5,
        "debit_account_type_id": "9ce964d02d3a48ada60ee28b8d61c7d3",
        "username": "Requesting Agent Name"
    },
    "credit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 5,
        "credit_account_type_id": "dd4403366e944eb4b302a69f684bc52e",
        "username": "Master Agent Name"
    }
}

Field Descriptions for COA:

txn_code: "COA" (Cash Out Agent)
payment_mode: 3 (Wallet payment)
txn_amount: Amount from cash transfer request
debit_user_info: Contains requesting agent's details (from from_agent_id)
- debit_account_type: 5 (Agent account type)
- debit_account_type_id: Requesting agent's user ID (from from_agent_id)
credit_user_info: Contains master agent's details (logged-in master agent)
- credit_account_type: 5 (Agent account type)
- credit_account_type_id: Master agent's user ID

Step 6: Update Cash Transfer Request

On successful wallet transfer API response, extract the transaction details:
- receiver_txn_id: Transaction ID from the wallet transfer response (extract from data.transaction.txn_id)
Call the Update Cash Transfer Request API (PUT method) with the following payload:

{
    "id": "d0f2eb47ddf740fb94cacb7a740b1b3a",
    "receiver_txn_id": "7eda3f4f87b9497098365811ce03d04c",
    "request_status": 3,
    "to_agent_id": "dd4403366e944eb4b302a69f684bc52e"
}

Field Descriptions:

id: Cash transfer request ID from Step 1
receiver_txn_id: Transaction ID from wallet transfer response (data.transaction.txn_id)
request_status: 3 (Completed/Processed status)
to_agent_id: Master agent's user ID (logged-in master agent who processed the rebalance)

Step 7: Display Transaction Success

Show success message to the master agent
Display the rebalance confirmation with:
- Requesting agent information
- Transaction type (Deposit/Withdraw)
- Amount processed
- Transaction ID
- Reference number
- Updated cash transfer request status
Master agent can provide the transaction receipt to the requesting agent

📡 API References

Get Cash Transfer Request Details

API: Get Cash Transfer Request API
Purpose: Retrieve cash transfer request details using reference number
Validation: Check if request_status != 3 (not already processed)
Extract: from_agent_id, note field (CIA or COA), amount, cash_transfer_request_id

Get Agent Wallet Balance

API: Get User Wallet API
Purpose: Retrieve master agent's current wallet balance
Validation:
- For CIA: Check master agent has sufficient balance (will debit)
- For COA: Check requesting agent has sufficient balance (will debit from requesting agent)

Check Product Availability

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

Execute Wallet Transfer

API: Wallet Transfer API
Purpose: Process the wallet transfer for agent rebalance
For CIA:
- Debit: Master agent account (account type 5)
- Credit: Requesting agent account (account type 5)
For COA:
- Debit: Requesting agent account (account type 5)
- Credit: Master agent account (account type 5)
Response: Extract data.transaction.txn_id to use as receiver_txn_id in Step 6

Update Cash Transfer Request

API: Update Cash Transfer Request API (PUT method)
Purpose: Update the cash transfer request with receiver transaction ID and completed status
Status: Set to 3 (Completed/Processed)
Fields: Update receiver_txn_id, request_status, and to_agent_id

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

🔄 Flow Logic

CIA Flow (Deposit Rebalance)

1. Enter reference number
   ↓
2. Get cash transfer request details
   ├─ Request not found → Show error, stop process
   ├─ Request status = 3 → Already processed, stop process
   └─ Request status != 3 → Extract from_agent_id, note="CIA", continue
      ↓
3. Get master agent wallet balance
   ├─ Insufficient balance → Show error, stop process
   └─ Sufficient balance → Continue
      ↓
4. Identify transaction type: CIA (from note field)
   ↓
5. Check if CIA product is allowed for master agent
   ├─ Product not found → Show error, stop process
   └─ Product found → Continue
      ↓
6. Prepare wallet transfer request
   - Debit: Master agent account
   - Credit: Requesting agent account (from_agent_id)
   - Product code: CIA
   ↓
7. Call Wallet Transfer API
   ├─ Failed → Show error, stop process
   └─ Success → Extract receiver_txn_id
      ↓
8. Update cash transfer request
   - Set receiver_txn_id
   - Set request_status = 3
   - Set to_agent_id (master agent)
   ├─ Update failed → Warning (transaction complete but status not updated)
   └─ Update success → Continue
      ↓
9. Display success message and receipt
   ↓
10. Transaction complete

COA Flow (Withdraw Rebalance)

1. Enter reference number
   ↓
2. Get cash transfer request details
   ├─ Request not found → Show error, stop process
   ├─ Request status = 3 → Already processed, stop process
   └─ Request status != 3 → Extract from_agent_id, note="COA", continue
      ↓
3. Get master agent wallet balance (for display)
   - Note: Balance check for requesting agent should be done separately
   ↓
4. Identify transaction type: COA (from note field)
   ↓
5. Check if COA product is allowed for master agent
   ├─ Product not found → Show error, stop process
   └─ Product found → Continue
      ↓
6. Prepare wallet transfer request
   - Debit: Requesting agent account (from_agent_id)
   - Credit: Master agent account
   - Product code: COA
   ↓
7. Call Wallet Transfer API
   ├─ Failed → Show error, stop process
   └─ Success → Extract receiver_txn_id
      ↓
8. Update cash transfer request
   - Set receiver_txn_id
   - Set request_status = 3
   - Set to_agent_id (master agent)
   ├─ Update failed → Warning (transaction complete but status not updated)
   └─ Update success → Continue
      ↓
9. Display success message and receipt
   ↓
10. Transaction complete

💡 Real-World Scenario

CIA Scenario (Deposit)

Agent A wants to deposit 1000 units to their wallet
Agent A goes through Agent Rebalance Account Flow (Deposit)
System generates reference number: REF12345
Agent A goes to Master Agent with 1000 units cash and REF12345
Master Agent processes "Rebalance from Reference Number":
- Validates REF12345
- Identifies transaction as CIA (from note field)
- Checks CIA product availability
- Master Agent's wallet: -1000 units
- Agent A's wallet: +1000 units
- Updates request status to 3
Master Agent gives receipt to Agent A
Transaction complete - Agent A's wallet increased by 1000 units

COA Scenario (Withdraw)

Agent B wants to withdraw 500 units from their wallet
Agent B goes through Agent Rebalance Account Flow (Withdraw)
System generates reference number: REF67890
Agent B goes to Master Agent with REF67890
Master Agent processes "Rebalance from Reference Number":
- Validates REF67890
- Identifies transaction as COA (from note field)
- Checks COA product availability
- Agent B's wallet: -500 units
- Master Agent's wallet: +500 units
- Updates request status to 3
Master Agent pays 500 units cash to Agent B
Transaction complete - Agent B's wallet decreased by 500 units

📋 Overview​

🔄 Workflow Steps​

Step 1: Get Cash Transfer Request Details​

Step 2: Get Agent Wallet Balance​

Step 3: Identify Transaction Type​

Step 4: Check Product Code Availability​

Step 5: Prepare and Execute Wallet Transfer API​

5.1: CIA (Cash In Agent) - Deposit Rebalance​

5.2: COA (Cash Out Agent) - Withdraw Rebalance​

Step 6: Update Cash Transfer Request​

Step 7: Display Transaction Success​

📡 API References​

Get Cash Transfer Request Details​

Get Agent Wallet Balance​

Check Product Availability​

Execute Wallet Transfer​

Update Cash Transfer Request​

🔄 Flow Logic​

CIA Flow (Deposit Rebalance)​

COA Flow (Withdraw Rebalance)​

💡 Real-World Scenario​

CIA Scenario (Deposit)​

COA Scenario (Withdraw)​