Agent Receive Money Flow

📋 Overview

Complete workflow for processing agent receive money transactions in the GafaPay system. This flow allows agents to disburse money to receivers (non-registered users) who have a pending cash transfer request. The agent validates the reference number, verifies the receiver via OTP, and completes the payout from the company admin wallet to the agent's wallet.

🔄 Workflow Steps

Step 1: Get Cash Transfer Request Details

• Agent enters the reference number provided by the sender
• Call the Get Cash Transfer Request API using the reference number
• Validate the cash transfer request exists
• Check request status:
  • If request_status = 3 → Cash already disbursed, show error message and stop the process
  • If request_status != 3 → Continue with the flow
• Extract and display the following details to the agent:
  • Sender information (name, phone number)
  • Receiver information (name, phone number)
  • Transfer amount
  • Transaction date
  • Reference number

Step 2: 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
• Validate that agent has sufficient balance for the transaction
• Display wallet balance to the agent for verification
• Note: Agent needs sufficient balance as they will receive money into their wallet

Step 3: Identify Transaction Type

• Based on the cash transfer request details, identify the product code:
  • CTA (Cash Transfer via Agent) - Regular cash transfer request
  • NRTA (Non-Register to Non-Register Transfer via Agent) - Agent send money request
• Extract the product code from the original transaction or determine based on:
  • If sender is registered → Likely CTA
  • If sender is non-registered → Likely NRTA
• This product code will be used in the wallet transfer API

Step 4: Check Product Availability

• Verify that the identified product (CTA or NRTA) is allowed for the agent
• Call the Get Agent Profile Products API and pass the agent's agent_profile_id
• Search for the 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 5: Send and Verify OTP to Receiver

• Extract receiver's phone number from the cash transfer request details
• Call the Send OTP API with the following parameters:
  • phone_number: Receiver's phone number
  • dial_code: Receiver's dial code
  • otp_type: 11 (OTP type for cash collection/receive money)
• Display OTP input field to collect the code from receiver
• Agent collects the OTP from the receiver (who received it via SMS)
• Call the Verify OTP API with:
  • phone_number: Receiver's phone number
  • dial_code: Receiver's dial code
  • otp: OTP code provided by receiver
  • otp_type: 11
• If OTP verification fails → Show error message and allow retry
• If OTP verification succeeds → Continue to wallet transfer

Step 6: Prepare and Execute Wallet Transfer API

• Prepare wallet transfer request with the identified product code (CTA or NRTA)
• In the debit_user_info, pass the company admin user details
• In the credit_user_info, pass the logged-in agent's details
• Call the Wallet Transfer API with the following payload structure:

{
    "charges_info": null,
    "note": null,
    "txn_amount": 100,
    "txn_code": "CTA",
    "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": 1,
        "debit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Mouhamad Amine"
    },
    "credit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 5,
        "credit_account_type_id": "dd4403366e944eb4b302a69f684bc52e",
        "username": "Md Siraj"
    }
}

Field Descriptions:

• txn_code: "CTA" or "NRTA" (based on original transaction type)
• payment_mode: 3 (Wallet payment)
• txn_amount: Amount from cash transfer request
• debit_user_info: Contains company admin user details
  • debit_account_type: 1 (Admin account type)
  • debit_account_type_id: Admin user ID
• credit_user_info: Contains logged-in agent's details
  • credit_account_type: 5 (Agent account type)
  • credit_account_type_id: Agent's user ID

Step 7: Update Cash Transfer Request

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

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

Field Descriptions:

• id: Cash transfer request ID from Step 1
• receiver_txn_id: Transaction ID from wallet transfer response
• request_status: 3 (Completed/Disbursed status)

Step 8: Display Transaction Success

• Show success message to the agent
• Display the disbursement confirmation with:
  • Receiver name
  • Amount disbursed
  • Transaction ID
  • Reference number
  • Updated cash transfer request status
• Agent can provide the transaction receipt to the receiver

📡 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 disbursed)

Get Agent Wallet Balance

• API: Get User Wallet API
• Purpose: Retrieve agent's current wallet balance to verify sufficient funds

Check Product Availability

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

Send OTP to Receiver

• API: Send OTP API
• Purpose: Send OTP to receiver's phone number for verification
• OTP Type: 11 (Cash collection/receive money)

Verify OTP from Receiver

• API: Verify OTP API
• Purpose: Verify the OTP code provided by the receiver
• OTP Type: 11 (Cash collection/receive money)

Execute Wallet Transfer

• API: Wallet Transfer API
• Purpose: Process the wallet transfer for cash disbursement
• Debit: Admin account (account type 1)
• Credit: Agent account (account type 5)

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/Disbursed)

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

🔄 Flow Logic

1. Enter reference number
   ↓
2. Get cash transfer request details
   ├─ Request not found → Show error, stop process
   ├─ Request status = 3 → Already disbursed, stop process
   └─ Request status != 3 → Continue
      ↓
3. Get agent wallet balance
   ├─ Insufficient balance → Show error
   └─ Sufficient balance → Continue
      ↓
4. Identify transaction type (CTA or NRTA)
   ↓
5. Check if product is allowed for agent
   ├─ Product not found → Show error, stop process
   └─ Product found → Continue
      ↓
6. Send OTP to receiver's phone number (type 11)
   ├─ OTP send failed → Show error
   └─ OTP sent → Continue
      ↓
7. Agent collects OTP from receiver
   ↓
8. Verify OTP
   ├─ OTP verification failed → Show error, allow retry
   └─ OTP verified → Continue
      ↓
9. Prepare wallet transfer request
   - Debit: Admin account
   - Credit: Agent account
   - Product code: CTA or NRTA
   ↓
10. Call Wallet Transfer API
    ├─ Failed → Show error, stop process
    └─ Success → Extract receiver_txn_id
       ↓
11. Update cash transfer request
    - Set receiver_txn_id
    - Set request_status = 3
    ├─ Update failed → Warning (transaction complete but status not updated)
    └─ Update success → Continue
       ↓
12. Display success message and receipt
    ↓
13. Transaction complete

🎯 Key Points

Reference Number

• Provided by the sender to the receiver
• Used to retrieve the cash transfer request
• Must be valid and exist in the system

Request Status Validation

• Status 3 = Already disbursed/completed
• If status is already 3, the money has been collected
• Prevents double disbursement of the same request

Transaction Type Identification

• CTA: Regular cash transfer request (sender is registered user)
• NRTA: Agent send money request (sender is non-registered user via agent)
• Product code must match the original transaction type

OTP Verification (Type 11)

• Ensures the person collecting is the intended receiver
• OTP sent to receiver's phone number
• Agent collects OTP from receiver in person
• OTP type 11 is specifically for cash collection/receive money

Account Types in Wallet Transfer

• Debit Account Type: 1 (Admin)
• Credit Account Type: 5 (Agent)
• Money flows from admin wallet to agent wallet
• Admin wallet was credited during the send money transaction

Money Flow

1. Send Money: Sender/Agent → Admin wallet (money held)
2. Receive Money: Admin wallet → Receiving Agent (money disbursed)
3. Agent pays out cash to receiver in person

Status Update

• request_status = 3 marks the transaction as completed
• receiver_txn_id links to the disbursement transaction
• Both fields must be updated after successful wallet transfer

Important Validations

• ✅ Reference number must be valid
• ✅ Request must not be already disbursed (status != 3)
• ✅ Agent must have sufficient wallet balance
• ✅ Product (CTA or NRTA) must be assigned to agent's profile
• ✅ OTP verification must succeed
• ✅ Wallet transfer must complete successfully
• ✅ Cash transfer request status must be updated

Error Handling

• If reference number invalid → Show "Request not found" message
• If already disbursed (status = 3) → Show "Already collected" message
• If product check fails → Show "Product not allowed" message
• If OTP verification fails → Show error and allow retry (3 attempts typically)
• If wallet transfer fails → Show wallet transfer error message
• If status update fails → Transaction is complete but tracking may be inconsistent
• Always verify API response status before proceeding to next step

Agent Commission

• Agent may earn commission based on profile product configuration
• Commission is calculated based on the commission_type and commission_value in the agent profile product
• Commission is automatically processed during the wallet transfer

📊 Complete Transaction Cycle

Phase 1: Send Money (Previous Transaction)

Sender → Agent (Send) → Wallet Transfer → Admin Wallet
                                            ↓
                                  Cash Transfer Request Created
                                            ↓
                                    Reference Number Generated

Phase 2: Receive Money (Current Flow)

Receiver with Reference Number → Agent (Receive)
                                        ↓
                                  Get Request Details
                                        ↓
                                  Verify OTP (Type 11)
                                        ↓
                                  Wallet Transfer
                                        ↓
                        Admin Wallet → Agent Wallet
                                        ↓
                            Update Request Status = 3
                                        ↓
                            Agent Pays Cash to Receiver

🔍 Difference Between Send and Receive Money Flows

Aspect	Send Money (Agent)	Receive Money (Agent)
Initiator	Sender brings money	Receiver with reference number
Money Direction	Agent/Sender → Admin	Admin → Agent
Debit Account	Agent wallet	Admin wallet
Credit Account	Admin wallet	Agent wallet
OTP Verification	Not required	Required (Type 11)
Request Status	Creates new (status 1)	Updates existing (status 3)
Cash Flow	Receiver receives cash from agent	Agent pays cash to receiver
Reference Number	Generated at end	Required at start
Transaction ID Field	sender_txn_id set	receiver_txn_id set

💡 Real-World Scenario

1. Alice (in City A) wants to send 100 units to Bob (in City B)
2. Alice goes to Agent 1 (in City A) with cash
3. Agent 1 processes "Send Money" (NRTA flow):
   • Agent 1's wallet: -100 units
   • Admin wallet: +100 units
   • Reference number: REF12345 generated
4. Alice sends REF12345 to Bob via phone
5. Bob goes to Agent 2 (in City B) with reference number
6. Agent 2 processes "Receive Money" (current flow):
   • Validates REF12345
   • Sends OTP to Bob's phone
   • Bob provides OTP to Agent 2
   • Admin wallet: -100 units
   • Agent 2's wallet: +100 units
   • Agent 2 pays 100 units cash to Bob
7. Transaction complete - Cash transferred from City A to City B

---